super-ux 0.55.1 → 0.56.1

package/CHANGELOG.md

@@ -1,3 +1,54 @@
+## 0.56.1 — the one contract that pointed at a neighbour
+
+`vision/SKILL.md` named its section contract as `` `ux-scenarios/references/scenario-format.md` `` —
+a path into a SIBLING skill, in backticks. The skills CLI ships only a skill's own
+directory, so on Cursor, Codex, OpenClaw and the rest the contract arrived dangling;
+`vision/references/` held a single file while the text pointed elsewhere. The four other
+skills that use the same contract all write it as `](references/scenario-format.md)`.
+
+- The link is now local, and `test/sync_references.py` ships `scenario-format.md` plus
+  its transitive closure (10 files) inside `vision/`.
+- **The validator had a check for this and it was keyed to the wrong spelling.**
+  `validate_shipped_references` refused `../references/`, so a bare
+  `<sibling>/references/<file>.md` passed for as long as it existed. It now refuses any
+  path naming another skill's `references/`, keyed to the real sibling directory names so
+  a project output path like `docs/ux/…` cannot trip it — watched refusing the
+  pre-change wording before this shipped.
+- `docs/brand/facts.md`: the stated validator check count recomputed, 4718 → 4821.
+
+## 0.56.0 — the sherlock audit closes, and two prototype documents stop pretending to be one
+
+Sherlock external-v3, 41 findings across this member, each one a commit carrying
+its own executable regression under `test/audit_regressions/`. The ones worth
+naming here:
+
+- **Scenarios carry three axes, not one word.** `evidence_kind`,
+  `decision_status` and `validation_status` are separate: approval moves the
+  decision, and only a dated interview or observation moves validation. A founder
+  cannot promote a wished-for persona to `observed` by approving it.
+- **Competitor funnels are observed exposure, never a proven base.** The reference
+  admitted a well-funded loss-maker looks profitable and then called common
+  patterns proven; it now says what it can see. Frequency is computed with a
+  denominator, duplicates collapsed — two funnels of one owner are ONE
+  observation — and adoption is decided by a local experiment.
+- **`/ux-audit` preconditions are per scope.** A standalone blog with a brand pack
+  and no scenarios runs the copy audit instead of being routed into writing
+  scenarios it has no use for. Evidence is typed by claim: `file:line` for this
+  codebase, URL + timestamp + capture for anything outside it.
+- **BP-212 no longer calls local payment testing impossible.** Three environments:
+  a local sandbox tests the whole payment→webhook→entitlement→success path with
+  the provider's own forwarding, and a public HTTPS endpoint is what PRODUCTION
+  delivery needs.
+
+Two documents now share the ground one filename used to: `interactive-flow-prototypes.md`
+is the machine-checkable graph contract (`IFP-01 … IFP-06`), and
+`clickable-flow-prototypes.md` is the operator-facing practice that arrived with the
+context-ready handoff. `prototyping.md` owns the decision to reach for either.
+
+`ux-audit` and `ux-flows` were split back under the house working limit —
+`audit-depth.md` and `prototyping.md` — after the audit's own doctrine grew them
+past it. CI now MEASURES that budget with a real tokenizer instead of estimating it.
+
 ## 0.55.1 — the opt-out the router promises now lives in the bodies that honor it
 
 Family audit 2026-09-06, wave AUDIT-WAVE-0906. **The operator's routing block

package/bin/super-ux.js

@@ -25,9 +25,16 @@ const ROOT = path.resolve(__dirname, '..');
 const REPO = 'ssheleg/super-ux';
 const NAME = 'super-ux';
 
-// Exit codes are the contract: 0 installed or nothing selected, 1 error,
-// 3 refused — the plugin channel owns this agent (--force overrides).
+// Exit codes are the contract: 0 installed/unchanged or nothing selected,
+// 1 a selected operation FAILED (the backend's exit/signal/command are printed
+//   and preserved on the result),
+// 3 refused — the plugin channel owns this agent (--force overrides),
+// 4 unsupported — a selected channel's backend is absent (claude CLI/npx not
+//   found); the remedy is printed, and 4 says "nothing was installed" out loud.
+// Failure outranks refusal outranks unsupported when several were selected.
 const EXIT_PLUGIN_PRESENT = 3;
+const EXIT_FAILED = 1;
+const EXIT_UNSUPPORTED = 4;
 
 /**
  * The plugin spec (`<name>@<marketplace>`) installed for `name` in this home,
@@ -41,10 +48,23 @@ const EXIT_PLUGIN_PRESENT = 3;
  * HOME is the common case, and an installer that crashes on a parse error
  * refuses the machines that need it most.
  */
+// The bundled HostContext resolver (FIX-UP-08.02) — one contract, a local
+// copy per member (npx installers share no lib): a host's config root is an
+// explicit root > the documented host env var > `~/<dir>`, verbatim (spaces
+// preserved), and host existence is a separate probe on the returned path.
+const HOST_ENV = { claude: 'CLAUDE_CONFIG_DIR', codex: 'CODEX_HOME', gemini: 'GEMINI_CONFIG_DIR' };
+const HOST_DIR = { claude: '.claude', codex: '.codex', gemini: '.gemini' };
+function hostRoot(agent, home, env, explicit) {
+  if (explicit) return explicit;
+  const e = (env || process.env)[HOST_ENV[agent]];
+  if (e) return e;
+  return path.join(home, HOST_DIR[agent]);
+}
+
 function installedPluginSpec(home, name) {
   try {
     const raw = fs.readFileSync(
-      path.join(home, '.claude', 'plugins', 'installed_plugins.json'), 'utf8');
+      path.join(hostRoot('claude', home, process.env), 'plugins', 'installed_plugins.json'), 'utf8');
     const parsed = JSON.parse(raw);
     const plugins =
       parsed && typeof parsed === 'object' &&
@@ -199,8 +219,11 @@ function installCursor(target, force) {
 
 function run(cmd, args) {
   const result = spawnSync(cmd, args, { stdio: 'inherit' });
-  if (result.error && result.error.code === 'ENOENT') return 'missing';
-  return result.status === 0 ? 'ok' : 'failed';
+  const command = [cmd, ...args].join(' ');
+  if (result.error && result.error.code === 'ENOENT')
+    return { status: 'missing', code: null, signal: null, command };
+  return { status: result.status === 0 ? 'ok' : 'failed',
+           code: result.status, signal: result.signal ?? null, command };
 }
 
 /**
@@ -219,7 +242,7 @@ function run(cmd, args) {
 function installSkillsCli(force) {
   const home = os.homedir();
   const spec = installedPluginSpec(home, NAME);
-  const marketplace = path.join(home, '.claude', 'plugins', 'marketplaces', NAME);
+  const marketplace = path.join(hostRoot('claude', home, process.env), 'plugins', 'marketplaces', NAME);
   const viaMarketplaceDir = !spec && fs.existsSync(marketplace);
   if ((spec || viaMarketplaceDir) && !force) {
     const found = spec
@@ -241,9 +264,17 @@ function installSkillsCli(force) {
     return 'refused';
   }
   console.log(`\n--- Skills for any agent: delegating to the skills CLI picker ---`);
-  const status = run('npx', ['--yes', 'skills', 'add', REPO]);
-  if (status !== 'ok') console.error(`warning: 'npx skills add ${REPO}' ${status}`);
-  return status;
+  const r = run('npx', ['--yes', 'skills', 'add', REPO]);
+  if (r.status === 'missing') {
+    console.error('The npx command was not found; install Node.js to use the skills channel.');
+    return { status: 'unsupported', ...r };
+  }
+  if (r.status === 'failed') {
+    console.error(`error: '${r.command}' exited ${r.code}` +
+      (r.signal ? ` (signal ${r.signal})` : ''));
+    return { status: 'failed', ...r };
+  }
+  return { status: 'installed', ...r };
 }
 
 /**
@@ -268,16 +299,21 @@ function installClaudePlugin() {
     console.log(`claude CLI not found. Run inside Claude Code instead:
   /plugin marketplace add ${REPO}
   /plugin install super-ux@super-ux`);
-    return;
+    return { status: 'unsupported', code: null, signal: null,
+             command: 'claude --version' };
   }
-  if (run('claude', ['plugin', 'marketplace', 'add', REPO]) !== 'ok') {
+  if (run('claude', ['plugin', 'marketplace', 'add', REPO]).status !== 'ok') {
     console.log('(marketplace may already be added, continuing)');
   }
-  if (run('claude', ['plugin', 'install', 'super-ux@super-ux']) === 'ok') {
+  const r = run('claude', ['plugin', 'install', 'super-ux@super-ux']);
+  if (r.status === 'ok') {
     console.log('Claude Code plugin installed (scope: user). Restart sessions to pick it up; then run /ux in any project.');
-  } else {
-    console.error('warning: claude plugin install failed, see output above');
+    return { status: 'installed', ...r };
   }
+  console.error(`error: '${r.command}' exited ${r.code}` +
+    (r.signal ? ` (signal ${r.signal})` : ''));
+  console.error('The plugin did not install; see the command output above.');
+  return { status: 'failed', ...r };
 }
 
 function makePrompter() {
@@ -441,20 +477,48 @@ async function menu(force) {
   }
   if (prompter) prompter.close();
 
-  if (keys.includes('cursor')) installCursor(cursorDir, false);
-  if (keys.includes('claude')) installClaudePlugin();
-  let refused = false;
-  if (keys.includes('skills')) refused = installSkillsCli(force) === 'refused';
+  // Only the SELECTED install operations are the result — each labelled by its
+  // channel, so a mixed selection reports which one failed rather than a single
+  // aggregate verdict. The router offer below is optional enrichment and is
+  // deliberately NOT in this list: whether it prints a block cannot change
+  // whether the install succeeded.
+  const results = [];
+  if (keys.includes('cursor')) { installCursor(cursorDir, false); results.push({ channel: 'cursor', status: 'installed' }); }
+  if (keys.includes('claude')) results.push({ channel: 'claude', ...installClaudePlugin() });
+  if (keys.includes('skills')) {
+    const r = installSkillsCli(force);
+    results.push({ channel: 'skills', ...(r === 'refused' ? { status: 'refused' } : r) });
+  }
 
   // Same offer the --cursor flag path makes. Two doors into one install that
   // behave differently is how a feature comes to exist for half its users.
   // Offered on the refused path too: the skill IS present on this machine —
-  // as the plugin — so the routing block is exactly as wanted.
-  offerRouters();
-  if (refused) {
+  // as the plugin — so the routing block is exactly as wanted. Guarded: an
+  // optional offer that threw must not become an install failure.
+  try { offerRouters(); } catch (e) {
+    console.error(`note: the routing-block offer could not run (${e.message}); the install above is unaffected`);
+  }
+
+  // The exit code is computed from the TYPED results of the SELECTED
+  // operations, never from the last print and never from the optional router
+  // offer: a failed child that ends in exit 0 reads as success to every script
+  // above it. Failure outranks refusal outranks unsupported.
+  const statuses = results.map((r) => r.status);
+  const failed = results.filter((r) => r.status === 'failed').map((r) => r.channel);
+  const ok = results.filter((r) => r.status === 'installed').map((r) => r.channel);
+  if (statuses.includes('failed')) {
+    // PARTIAL: name what installed and what failed rather than one word.
+    if (ok.length)
+      console.error(`partial: installed ${ok.join(', ')}; FAILED ${failed.join(', ')} — see the errors above`);
+    else
+      console.error(`failed: ${failed.join(', ')} — see the errors above`);
+    process.exitCode = EXIT_FAILED;
+  } else if (statuses.includes('refused')) {
     // The refusal already carries the update commands; repeating the update
     // line under it would bury the remedy. Exit 3 so scripts read the refusal.
     process.exitCode = EXIT_PLUGIN_PRESENT;
+  } else if (statuses.includes('unsupported')) {
+    process.exitCode = EXIT_UNSUPPORTED;
   } else {
     printUpdateLine();
   }

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "super-ux",
-  "version": "0.55.1",
+  "version": "0.56.1",
   "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"
+    "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 && npm run test:audit",
+    "test:audit": "for t in test/audit_regressions/*.py; do python3 \"$t\" || exit 1; done"
   },
   "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": {

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

@@ -1063,40 +1063,115 @@ 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.
+# A figure's provenance is more than its digits (FIX-UX-01.02 / UX-01). "500
+# supported integrations" does NOT source "500 million paying customers": the
+# digits coincide, the SCALE and the SUBJECT differ. So B030 resolves a claim
+# against a SIGNATURE -- (digits, unit, scale, precision) -- not against a bag
+# of numbers. Subject/population match is a reader's judgement, kept to the
+# separate semantic review; this token-level check verifies the provenance
+# LINK, the UNIT, the PRECISION and the date TYPE, and says so in its own name.
+SCALE_WORDS = {
+    "k": "k", "thousand": "k", "thousands": "k",
+    "m": "m", "mn": "m", "million": "m", "millions": "m",
+    "b": "b", "bn": "b", "billion": "b", "billions": "b",
+}
+# Words that follow a year but do not make it a COUNT ("2025 and Material").
+_NOT_A_COUNT_NOUN = {
+    "and", "or", "but", "to", "the", "of", "a", "an", "rev", "edition",
+    "version", "release", "guidelines", "guidance",
+}
+# Cues that a nearby four-digit token is a DATE, not a figure.
+_DATE_CUE = re.compile(
+    r"(?:©|\bin\b|\bsince\b|\bcirca\b|\bas of\b|\best\.?\b|\brev\b"
+    r"|\bedition\b|\bversion\b|\bv\b|\bHIG\b|\bSP\b|\bISO\b|\bRFC\b"
+    r"|\b(?:Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)[a-z]*\b)",
+    re.IGNORECASE,
+)
+
+
+def _signature(token: str, scale_word: str = "") -> tuple:
+    """(digits, unit, scale, precision) for one numeric token.
+
+    Digits keep their decimal places so precision is part of identity: a row of
+    `$3.10` does not source a copy `$3.1`. Unit is % or a currency mark; scale
+    is a magnitude word beside the number, so a bare `500` never sources
+    `500 million`.
     """
-    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}
+    s = token.strip()
+    unit = ""
+    if s.endswith("%"):
+        unit, s = "%", s[:-1].strip()
+    m = re.match(r"^([$€£])\s?(.*)$", s)
+    if m:
+        unit, s = m.group(1), m.group(2)
+    s = s.replace(",", "").strip("+~><≈").strip()
+    if "." in s:
+        intp, _dot, frac = s.partition(".")
+        digits, precision = intp + "." + frac, len(frac)
+    else:
+        digits, precision = s, 0
+    scale = SCALE_WORDS.get((scale_word or "").lower(), "")
+    return (digits, unit, scale, precision)
+
+
+def _row_signatures(value: str) -> set:
+    """Every SIGNATURE one fact's `Value` sources (replaces the old digit set).
+
+    Same anti-substring guarantee as before -- a figure not written in the
+    table is not in the table -- now carrying unit, scale and precision so a
+    coincidence of digits can no longer launder a different claim.
+    """
+    sigs = set()
+    for m in NUMBER_RE.finditer(value):
+        tail = value[m.end():].lstrip()
+        sw = re.match(r"([A-Za-z]+)", tail)
+        scale_word = sw.group(1) if sw and sw.group(1).lower() in SCALE_WORDS else ""
+        sigs.add(_signature(m.group(0), scale_word))
+    compact = re.sub(r"\s+", "", value).strip("+~><≈").strip()
+    if compact and re.search(r"\d", compact):
+        sigs.add(_signature(compact))
+    return sigs
+
+
+def _reads_as_date(body: str, start: int, end: int) -> bool:
+    """A four-digit year-form token is a DATE (not a checkable figure) by
+    default; it is a FIGURE -- and needs a row -- only when a plural count noun
+    follows it with no date cue before and no range dash beside it. So
+    "2026 integrations" and "2026 customers" are checked, while "Apple HIG
+    2025", "in 2026", "2020—2024" and "2024 without a gap" stay dates.
+
+    A plural count noun is approximated as a lowercase word of four or more
+    letters ending in "s" and not in the small stoplist -- deliberately narrow,
+    because a false FIGURE here is a B030 nobody can clear (the range fixture
+    that caught exactly this)."""
+    before = body[max(0, start - 24):start]
+    if _DATE_CUE.search(before) or before.rstrip().endswith(("-", "\u2013", "\u2014")):
+        return True
+    after = body[end:]
+    if after.lstrip().startswith(("-", "\u2013", "\u2014")):
+        return True                                   # a range: 2020—2024
+    # A year preceded by a proper noun or an acronym is an edition/benchmark
+    # year ("Apple HIG 2025", "PLG 2025 benchmarks"), not a count. Only a year
+    # after a lowercase word (or nothing) — "spanning 2026 integrations" — reads
+    # as the count itself.
+    prev = re.search(r"([A-Za-z][A-Za-z-]*)[\s/]*$", before)
+    prev_is_name = bool(prev and (prev.group(1)[:1].isupper() or prev.group(1).isupper()))
+    nxt = re.match(r"\s*([A-Za-z][A-Za-z-]*)", after)
+    if nxt and not prev_is_name:
+        w = nxt.group(1).lower()
+        if len(w) >= 4 and w.endswith("s") and w not in _NOT_A_COUNT_NOUN:
+            return False                              # a count noun follows: check it
+    return True
 
 
 def check_facts(brand_dir: Path, sources: dict) -> list[Finding]:
     """B030-B033 -- every figure traces to a row, every row to a source."""
     findings: list[Finding] = []
     rows = facts(brand_dir)
-    known: set[str] = set()
+    known: set = set()
     for row in rows:
         if row["public"].lower() != "no":
-            known |= _fact_figures(row["value"])
+            known |= _row_signatures(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
@@ -1132,16 +1207,31 @@ def check_facts(brand_dir: Path, sources: dict) -> list[Finding]:
             ))
 
     for path, _fields, body in documents(brand_dir, sources, "marketing"):
-        for number in NUMBER_RE.findall(body):
-            compact = number.replace(" ", "")
-            if YEAR_RE.match(compact):
+        for m in NUMBER_RE.finditer(body):
+            number = m.group(0)
+            digits = re.sub(r"\s+", "", number)
+            # A year-form token: excluded ONLY when it reads as a date, never
+            # automatically (UX-01). "2026 integrations" is a figure that needs
+            # a row; "Apple HIG 2025" is a date.
+            if YEAR_RE.match(digits.strip("+~><≈")) and _reads_as_date(body, m.start(), m.end()):
                 continue
-            if compact not in known:
+            tail = body[m.end():].lstrip()
+            sw = re.match(r"([A-Za-z]+)", tail)
+            scale_word = sw.group(1) if sw and sw.group(1).lower() in SCALE_WORDS else ""
+            sig = _signature(number, scale_word)
+            if sig not in known:
+                # Name WHICH axis failed, so a writer can act: a bare digit that
+                # a row DOES carry under a different unit/scale/precision is a
+                # provenance mismatch, not a missing fact.
+                bare_matches = any(s[0] == sig[0] for s in known)
+                why = ("its unit, scale or precision does not match any facts.md row"
+                       if bare_matches else "no row in facts.md")
                 findings.append(Finding(
                     "B030", SEVERITY_ERROR, path, 0,
-                    f"`{number}` appears in public copy with no row in "
-                    f"facts.md -- a number nobody can check is a claim "
-                    f"nobody should make",
+                    f"`{number}` in public copy: {why} -- a number nobody can "
+                    f"check against a sourced claim is a claim nobody should make. "
+                    f"(Whether it means what the sentence says is the semantic "
+                    f"review's question, not this check's.)",
                 ))
         for paragraph in re.split(r"\n\s*\n", body):
             lowered = paragraph.lower()
@@ -1272,6 +1362,38 @@ S1_MARKERS = (
     "crucial to", "navigate the complexities",
 )
 
+# B051 keyword-stuffing is ADVISORY and about UNNATURAL REPETITION (FIX-UX-02.01):
+# a token must repeat many times on a page long enough to read, not merely clear
+# a percentage. These bars make a zero-repeat page (45/80/100 unique words)
+# always clean, and leave a genuinely stuffed block to warn.
+B051_MIN_WORDS = 40      # enough words to talk about; repetition COUNT guards the rest
+B051_MIN_REPEAT = 5      # a word must actually recur, not appear once
+B051_SHARE = 0.04        # and take an unnatural share on top of that
+
+
+def _domain_terms(brand_dir) -> set:
+    """Registered terms that are SUPPOSED to recur — exempt from B051. Drawn
+    from terminology.md (product terms, entity names) and facts.md fact names,
+    so a brand's own vocabulary is never read as stuffing."""
+    terms = set()
+    try:
+        _banned, products, entities = dictionary(brand_dir)
+        for pair in products:
+            terms.add(pair[0].lower())
+        for pair in entities:
+            terms.add(pair[0].lower())
+    except Exception:
+        pass
+    try:
+        for row in facts(brand_dir):
+            for tok in normalise(row["fact"]).lower().split():
+                if len(tok) > 3:
+                    terms.add(tok)
+    except Exception:
+        pass
+    return terms
+
+
 STOPWORDS = {
     "the", "and", "for", "with", "that", "this", "from", "your", "you",
     "are", "was", "were", "have", "has", "had", "not", "but", "all",
@@ -1527,22 +1649,39 @@ def check_bot_safety(brand_dir: Path, sources: dict) -> list[Finding]:
                  if len(pooled) > 1 else pooled[0][0])
         per_file.append((label, {}, "\n\n".join(d[2] for d in pooled)))
 
+    # Keyword stuffing is UNNATURAL REPETITION, not a frequency threshold. The
+    # old rule fired B051 (an ERROR) on any token above 1% of the words once a
+    # page passed 40 significant words -- but with 45 unique words and NO repeat
+    # each token is 1/45 = 2.2%, so a page that repeats nothing was flagged, and
+    # for a short page the 1% bar is mathematically unmeetable. Google's policy
+    # describes unnatural repetition / manipulative intent, not a 1% line
+    # (https://developers.google.com/search/docs/essentials/spam-policies#keyword-stuffing),
+    # so this is now ADVISORY: a word must actually REPEAT many times on a page
+    # long enough to judge, and a registered domain term (which is SUPPOSED to
+    # recur) is exempt. Each page is judged on its own rendered body.
+    domain_terms = _domain_terms(brand_dir)
     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:
-            counts: dict[str, int] = {}
-            for word in real:
-                counts[word] = counts.get(word, 0) + 1
-            for word, count in sorted(counts.items()):
-                if count / len(words) > 0.01:
-                    findings.append(Finding(
-                        "B051", SEVERITY_ERROR, path, 0,
-                        f"`{word}` is {count / len(words):.1%} of the "
-                        f"document -- above 1% reads as stuffing, which "
-                        f"lowers citation likelihood rather than raising it",
-                    ))
-                    break
+        if len(words) < B051_MIN_WORDS:
+            continue                                  # too short to read repetition at all
+        counts: dict[str, int] = {}
+        for word in real:
+            counts[word] = counts.get(word, 0) + 1
+        for word, count in sorted(counts.items()):
+            if word in domain_terms:
+                continue                              # a registered term is meant to recur
+            share = count / len(words)
+            if count >= B051_MIN_REPEAT and share > B051_SHARE:
+                findings.append(Finding(
+                    "B051", SEVERITY_WARN, path, 0,
+                    f"`{word}` repeats {count}x ({share:.1%}) on this page -- "
+                    f"advisory: unnatural repetition reads as keyword stuffing "
+                    f"(Google's spam policy is about manipulative repetition, "
+                    f"not a fixed percentage). If it is a registered term, add "
+                    f"it to terminology.md; otherwise vary the wording",
+                ))
+                break
 
     for path, fields, body in marketing:
 
@@ -1597,11 +1736,15 @@ def check_ai_tells(brand_dir: Path, sources: dict) -> list[Finding]:
         if not hits:
             continue
         grade = "B" if len(hits) < 3 else "C"
-        severity = SEVERITY_ERROR if len(hits) >= 3 else SEVERITY_WARN
+        # B060 is ADVISORY (FIX-UX-03.01/03.02): it WARNS, and it NEVER escalates
+        # to an error by marker count. A count is a signal to a writer, not proof
+        # of authorship and not a gate — so marker-rich but correct text does not
+        # block the run. The grade stays as an advisory reading of the density.
         findings.append(Finding(
-            "B060", severity, path, 0,
+            "B060", SEVERITY_WARN, path, 0,
             f"{len(hits)} S1 marker(s) -- {', '.join(sorted(hits))}. "
-            f"Naturalness grade {grade}",
+            f"Naturalness grade {grade} (advisory — vary the wording if you wish; "
+            f"a marker count is not proof of authorship)",
         ))
 
     # B062 -- the rhetorical dash, in every surface that ships prose.

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

@@ -686,17 +686,18 @@ def check_web_surface(screens: str, flows: str) -> None:
                 )
 
 
-VISION_SECTIONS = [
-    "1. Essence",
-    "2. Core idea",
-    "3. What the system does",
-    "4. The user's role",
-    "5. Principles",
-    "6. Anti-vision",
-    "7. Horizon",
-    "8. The one sentence",
-    "9. The alignment test",
-]
+# The machine IDENTITY of a vision section is its NUMBER (FIX-UX-07.01); the
+# title after it is DISPLAY prose and may be localized. The linter matches on
+# `## N.` so a Russian vision keeps all nine section ids without English titles.
+# The English titles here are the seed default, not the parser's key.
+VISION_SECTION_TITLES = {
+    1: "Essence", 2: "Core idea", 3: "What the system does", 4: "The user's role",
+    5: "Principles", 6: "Anti-vision", 7: "Horizon", 8: "The one sentence",
+    9: "The alignment test",
+}
+VISION_SECTION_IDS = list(VISION_SECTION_TITLES)      # [1..9]
+# The number is the id: `## 6.` or `## 6. Anti-vision` or `## 6. Анти-видение`.
+_VSEC = lambda n: rf"^##\s+{n}\.[^\n]*$"   # whole heading line: title (any language) is part of the heading, not the body
 
 VISION_RULE_HEADING = "## Vision alignment — hard rule (super-ux)"
 
@@ -728,6 +729,20 @@ 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")
 
+# Which instruction file each HOST actually reads, and the marker directory that
+# says the host is present in this project (FIX-UX-06.01). A rule in CLAUDE.md
+# does not cover a Codex host, which reads AGENTS.md — so the check is per active
+# host, not "any of the three files exists".
+HOST_TARGET = {"claude": "CLAUDE.md", "codex": "AGENTS.md", "gemini": "GEMINI.md"}
+HOST_MARKER = {"claude": ".claude", "codex": ".codex", "gemini": ".gemini"}
+
+
+def active_hosts(root: Path) -> list[str]:
+    """Hosts present in this project, by their marker directory. When none is
+    detectable the target defaults to Claude, matching the seed default."""
+    found = [h for h, m in HOST_MARKER.items() if (root / m).is_dir()]
+    return found or ["claude"]
+
 
 def check_vision(ux: Path, vision: str) -> None:
     """The vision layer: all nine sections, and the rule that makes it read.
@@ -738,21 +753,31 @@ def check_vision(ux: Path, vision: str) -> None:
     """
     if not vision.strip():
         return
-    for section in VISION_SECTIONS:
-        if not re.search(rf"^##\s+{re.escape(section)}\s*$", vision, re.MULTILINE):
-            err(f"[U030] vision.md: missing section '## {section}'")
+    for n in VISION_SECTION_IDS:
+        hits = re.findall(_VSEC(n), vision, re.MULTILINE)
+        if not hits:
+            err(f"[U030] vision.md: missing section '## {n}.' "
+                f"(e.g. '{n}. {VISION_SECTION_TITLES[n]}' — the number is the id, "
+                f"the title may be in the document's language)")
+        elif len(hits) > 1:
+            # FIX-UX-07.02: the id is the number, so two `## N.` headings are two
+            # sections claiming one identity — a duplicate the parser would
+            # otherwise resolve to whichever it found first, silently.
+            err(f"[U034] vision.md: section id {n} appears {len(hits)} times — "
+                f"a section id is unique; give one of them a different number or "
+                f"merge them (found: {', '.join(h.strip() for h in hits)})")
     # 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.
     approved = bool(re.search(r"\*\*Status:\*\*\s*approved", vision, re.IGNORECASE))
     if approved:
-        for section in ("6. Anti-vision", "9. The alignment test"):
-            body = re.split(rf"^##\s+{re.escape(section)}\s*$", vision, maxsplit=1,
-                            flags=re.MULTILINE)
+        for n in (6, 9):
+            body = re.split(_VSEC(n), vision, maxsplit=1, flags=re.MULTILINE)
             if len(body) == 2:
                 tail = re.split(r"^##\s", body[1], maxsplit=1, flags=re.MULTILINE)[0]
                 if not tail.strip():
-                    err(f"[U031] vision.md: approved but '## {section}' is empty — "
+                    err(f"[U031] vision.md: approved but section {n} "
+                        f"({VISION_SECTION_TITLES[n]}) is empty — "
                         f"the section that settles arguments cannot be blank")
 
     # `B-005`: the seeded template is nine headings above HTML comments, and
@@ -762,9 +787,8 @@ def check_vision(ux: Path, vision: str) -> None:
     # 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)
+    def _authored(n: int) -> bool:
+        parts = re.split(_VSEC(n), 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]
@@ -777,24 +801,39 @@ def check_vision(ux: Path, vision: str) -> None:
         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)]
+    written = [n for n in VISION_SECTION_IDS if _authored(n)]
     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"{len(VISION_SECTION_IDS)} 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
-    carrying = [p for p in present if VISION_RULE_HEADING in read(p)]
-    if not carrying:
+    # FIX-UX-06.01 — the rule must live in the file the ACTIVE HOST reads, not
+    # in any of the three. A Codex project with the rule only in CLAUDE.md is
+    # uncovered: Codex reads AGENTS.md and never sees it.
+    hosts = active_hosts(root)
+    carrying = []
+    missing_file = []      # U032: the active host has no instruction file at all
+    missing_rule = []      # U033: the file exists but carries no rule block
+    for h in hosts:
+        target = root / HOST_TARGET[h]
+        if not target.is_file():
+            missing_file.append((h, HOST_TARGET[h]))
+        elif VISION_RULE_HEADING in read(target):
+            carrying.append(target)
+        else:
+            missing_rule.append((h, HOST_TARGET[h]))
+    if missing_file:
+        detail = ", ".join(f"{h} reads {f}" for h, f in missing_file)
+        warn(f"[U032] vision.md exists but the active host has no instruction file "
+             f"({detail}) — the alignment rule has nowhere the running host can read it")
+    if missing_rule:
+        detail = ", ".join(f"{f} ({h})" for h, f in missing_rule)
         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"{detail} — nothing the running host reads ever sees the vision "
              f"(run the `vision` skill's step 4)")
+    if not carrying:
         return
     for path in carrying:
         text = read(path)