super-ux 0.28.0 → 0.30.0

package/CHANGELOG.md

@@ -1,5 +1,116 @@
 # Changelog
 
+## 0.30.0 — 2026-08-05
+
+The verbal identity layer. `docs/ux/` decides what the product does; the new
+`docs/brand/` decides how it speaks — one voice, many registers, and a linter
+that makes copy drift as findable as chain drift.
+
+### The contract — `brand-contract v1`
+
+`docs/brand/` is a second artifact root beside `docs/ux/`, seeded by the
+installer: `voice.md` (a voice pack, five fixed axes as IS / IS NOT, the
+narrative, the invariants that survive translation), `terminology.md` (our
+words, banned words, exact entity and tier spellings), `facts.md` (the only
+source of any figure in public copy), `channels.md` (one record per surface),
+`strings.md` (the interface string registry, key → `file:line` → scenario),
+and `locales/<code>.md`.
+
+Separate root on purpose: the brand also governs surfaces that are not UX at
+all — a store listing, an ad, a post. The pack derives from `foundation.md`
+and never the reverse.
+
+### Two skills
+
+- **`brand-voice`** — defines and holds the identity. Six shipped voice packs
+  (`operator-brief`, `calm-expert`, `peer-builder`, `editorial-premium`,
+  `plain-service`, `playful-consumer`), each declaring the degeneration it
+  collapses into when overdone, so an overshoot is a finding rather than a
+  matter of taste. Invoked with no task it reports state and proposes exactly
+  one next action, and never invents a missing fact to close a gap.
+- **`copywriting`** — writes in the voice and never writes *to* it. A missing
+  term or an unsourced number is reported, because adding it is the other
+  skill's decision.
+
+Commands: `/brand`, `/brand-init`, `/brand-update`, `/brand-lint`, `/copy`.
+
+### `brand_lint.py` — 31 deterministic checks
+
+Seeded as `docs/brand/lint.py`. Contract and sources (B001–B006), terminology
+(B010–B012), string consistency (B020–B025), facts (B030–B032), channel
+physics (B040–B043), bot safety (B050–B054), machine-drafting markers
+(B060–B061), locales (B070–B073). Exit 0 clean, 1 warnings, 2 errors;
+`--fix` touches only casing, the iOS keyword field, and re-pointing a registry
+row whose string is unchanged. 32 fixtures, one per code, each watched failing
+against a planted defect before it was trusted — and they run in CI.
+
+Three rules it exists to enforce: one action keeps one name everywhere; a
+number in public copy has a sourced row or is not written; no humor on error,
+destructive-confirm, billing or paywall surfaces, in any voice.
+
+### Catalog
+
+`BP-182..205` in six clusters of four — voice and consistency, product
+microcopy, conversion copy, bot safety, channel physics, localization — and
+`PRN-22..24`. New entries carry a sixth field, `Checked:`, dating the last
+verification against the source. It starts at BP-182 deliberately:
+backfilling it onto BP-001..181 would record a verification nobody performed.
+New tags `brand-voice` `copy` `narrative` `terminology` `channel-physics`
+`seo` `aeo` `aso` — `voice` was already taken, and it means a voice interface.
+
+### Elsewhere
+
+`ux-audit` gains scope `copy`, the judgement twin of the linter. `ux_doctor`
+reads the brand marker, because a pack on an old contract is internally
+consistent and the linter stays quiet about it. Scenarios gain an optional
+`Strings:` field. The brand hard rule ships in the Claude rule template and a
+new Cursor rule.
+
+### Fixed
+
+- `CONTRIBUTING.md` told maintainers to run `npm publish --access public`
+  by hand in `sshlg-skills` after a release. Every repo in the family has
+  published from CI on a `v*` tag since that text was written.
+
+## 0.29.0 — 2026-08-05
+
+A pass aimed at the installed base rather than the catalog. Run across the
+twelve projects using super-ux, the tooling turned out to be blind to the
+most common failure: only two are cleanly on contract v4, five carry no
+marker at all — including the two largest bases, at 119 and 120 scenarios —
+one holds v2, v3 and v4 across four artifacts simultaneously, and one keeps
+its base under a name the contract does not own, so four audit reports were
+produced against scenarios the tooling could not find.
+
+### Added
+- **`/ux-doctor` and `docs/ux/doctor.py`.** `ux_lint` checks a chain against
+  itself, so a base written entirely to an old contract passes it — from the
+  inside such a chain is consistent. The doctor reports the effective
+  contract version, what each version since it introduced, mixed versions
+  across artifacts, files the tooling cannot find under their contract
+  names, audits produced against a base that is not there, and which
+  additive sections a project has not adopted. Read-only unless `--fix`,
+  which does only what cannot be wrong: renames, and moving loose audit
+  reports into `audits/`. Contract upgrades stay content decisions for
+  `/ux-update`. Wired into `/ux` status and the Cursor rule.
+- **Information architecture — BP-180, BP-181.** BP-052 requires navigation
+  to be visible and BP-049 puts it in reach; neither judges whether the
+  *groups* make sense. Card sorting for grouping, tree testing for labels —
+  the one navigation decision that cannot be judged from the inside, because
+  the team already knows where everything is.
+- **Moderated test tasks generated from `scenarios.md`.** A scenario is
+  already the shape a test task wants — situation, goal, observable success
+  — so the tasks are a rewrite of the base rather than a new artifact, and
+  what comes back grades against the same base.
+- **`benchmark:<competitor>` audit scope.** Every other scope measures the
+  product against its own chain and cannot report that a flow is two steps
+  longer than everyone else's. Same axes both sides, observable from outside
+  only, and gaps recorded as opportunities for the foundation rather than as
+  defects in the report.
+- **Reviews and support tickets as WHY-layer evidence** in `ux-foundation` —
+  the cheapest input the layer has, and the one most often skipped because
+  it does not feel like research.
+
 ## 0.28.0 — 2026-08-05
 
 Closes the carry-over ledger the 0.27 audit opened. Twenty-three practices,

package/README.md

@@ -100,6 +100,41 @@ plugin user-globally — any combination in one run. Also works straight from
 GitHub: `npx github:ssheleg/super-ux --cursor <dir>`, or clone and run
 `./install.sh --cursor <dir>`.
 
+## The brand layer — how the product speaks
+
+`docs/ux/` decides what the product does. **`docs/brand/`** decides how it
+speaks, under `brand-contract v1`: one voice, many registers, and a linter
+that makes copy drift as findable as chain drift.
+
+| File | Holds |
+|---|---|
+| `voice.md` | the pack, five fixed axes, narrative, invariants, locales |
+| `terminology.md` | our words, banned words, entity and tier names |
+| `facts.md` | canonical figures — the only source of a number in public copy |
+| `channels.md` | one record per surface: register deltas, limits, bans |
+| `strings.md` | the interface string registry → `file:line` → scenario |
+| `locales/<code>.md` | address form, length coefficient, dead idioms, keywords |
+
+Two skills: **`brand-voice`** defines and holds the identity (six shipped
+voice packs, each declaring the degeneration it collapses into when overdone);
+**`copywriting`** writes in it and never writes *to* it — a missing term or an
+unsourced number is reported, never invented.
+
+Commands: `/brand` (status → one recommended action), `/brand-init`,
+`/brand-update`, `/brand-lint`, `/copy`.
+
+```bash
+python3 docs/brand/lint.py
+```
+
+31 deterministic checks — banned words, one action under two names, a figure
+with no sourced fact, a field over its limit with the locale coefficient
+applied, blocked AI crawlers, keyword stuffing, humor on a billing screen,
+a locale that lags without saying so. Exit 0 clean, 1 warnings, 2 errors.
+
+Clean means *checkable*, not *good*: tone drift, unproven claims and a voice
+that has overshot its own failure mode are judged by `/ux-audit copy`.
+
 ## The hard rule
 
 Installed into your project's `CLAUDE.md` (and as the always-on Cursor rule):
@@ -185,9 +220,10 @@ The contracts every skill reads:
 |---|---|
 | [scenario-format.md](plugins/super-ux/skills/references/scenario-format.md) | **The contract (ux-contract v4).** File layout, every field name, stable IDs (`P` `JTBD` `JRN` `ST` `FLW` `SCR` `SCN`), completeness checklists, the `draft → validated → implemented` lifecycle, audit verdicts and severities, the UX-plan format |
 | [system-map.md](plugins/super-ux/skills/references/system-map.md) | The whole system on one page — pipeline, files, skills, companions, and the four sync rules; every skill points here |
+| [ux_doctor.py](plugins/super-ux/scripts/ux_doctor.py) | Contract doctor — reports mixed or stale contract versions across a project's artifacts, files the tooling cannot find under their contract names, and audits produced against a base that is not there. `/ux-lint` checks a chain against itself; this checks it against the contract. Installed as `docs/ux/doctor.py`, read-only unless `--fix` |
 | [best-practices-index.md](plugins/super-ux/skills/references/best-practices-index.md) | Generated tag index over the catalog — tag → ids, id → title. Read it to decide which entries to open; regenerated by `plugins/super-ux/scripts/bp_index.py` and checked for drift by the validator |
 | [ux-design-principles.md](plugins/super-ux/skills/references/ux-design-principles.md) | How the agent thinks: the design pipeline (forward and backwards), task analysis, flow rules, heuristics PRN-01..21, the improvement procedure, anti-patterns |
-| [best-practices.md](plugins/super-ux/skills/references/best-practices.md) | Living, tag-indexed catalog of 179 proven practices — subscription-app laws, mobile/web/voice guidance (Apple HIG 2025, M3 Expressive, NN/g, Baymard, WCAG 2.2), monetization economics (RevenueCat/PLG 2025 benchmarks, ASO, freemium boundaries), web funnels end to end (landing, pricing, checkout, dunning, cancel) and web2app (paid handoff, deferred deep links, storefront rules), motion and page weight (HTTP Archive field data, W3C sustainability), accessibility as it actually fails (WebAIM Million, EAA/ADA exposure), frustration telemetry, gamification and trend governance, growth loops and referral mechanics, empty states, authentication (NIST SP 800-63B rev 4) and form recovery, motion craft and perceived quality, the defaults that make an interface read as generated, interface state, locale and platform surfaces (Web Interface Guidelines), visual craft, Figma structure |
+| [best-practices.md](plugins/super-ux/skills/references/best-practices.md) | Living, tag-indexed catalog of 181 proven practices — subscription-app laws, mobile/web/voice guidance (Apple HIG 2025, M3 Expressive, NN/g, Baymard, WCAG 2.2), monetization economics (RevenueCat/PLG 2025 benchmarks, ASO, freemium boundaries), web funnels end to end (landing, pricing, checkout, dunning, cancel) and web2app (paid handoff, deferred deep links, storefront rules), motion and page weight (HTTP Archive field data, W3C sustainability), accessibility as it actually fails (WebAIM Million, EAA/ADA exposure), frustration telemetry, gamification and trend governance, growth loops and referral mechanics, empty states, authentication (NIST SP 800-63B rev 4) and form recovery, motion craft and perceived quality, the defaults that make an interface read as generated, interface state, locale and platform surfaces (Web Interface Guidelines), visual craft, Figma structure |
 | [practice-selection.md](plugins/super-ux/skills/references/practice-selection.md) | The deterministic bridge: product profile → mandatory consideration sets → per-artifact checklists → a compliance table where every pulled practice gets a verdict. No silent skips, no cargo cult |
 | [component-guidelines.md](plugins/super-ux/skills/references/component-guidelines.md) | Which control for which job (radios/select/switch, sheet/alert, modal/disclosure, combobox, nav bar/rail, FAB, dates, toasts) and the platform rules — Apple HIG, Material 3, W3C ARIA APG, GOV.UK |
 | [visual-identity.md](plugins/super-ux/skills/references/visual-identity.md) | The visual layer and its owner: one style pack for the whole product, where it's recorded, how it meets Figma and code, and the division of labor with the craft floors |

package/bin/super-ux.js

@@ -86,19 +86,49 @@ function installCursor(target, force) {
       console.log(`seed:    ${dst}`);
     }
   }
+  // The brand pack lives beside the UX chain, not inside it: it also governs
+  // surfaces that are not UX at all — a store listing, an ad, a post.
+  fs.mkdirSync(path.join(target, 'docs', 'brand', 'locales'), { recursive: true });
+  for (const tpl of [
+    'README', 'voice', 'terminology', 'facts', 'channels', 'strings',
+  ]) {
+    const dst = path.join(target, 'docs', 'brand', `${tpl}.md`);
+    if (fs.existsSync(dst)) {
+      console.log(`keep:    ${dst} exists (never overwritten)`);
+    } else {
+      fs.copyFileSync(path.join(ROOT, 'templates', 'brand', `${tpl}.md`), dst);
+      console.log(`seed:    ${dst}`);
+    }
+  }
+  {
+    const dst = path.join(target, 'docs', 'brand', 'locales', 'en.md');
+    if (!fs.existsSync(dst)) {
+      fs.copyFileSync(path.join(ROOT, 'templates', 'brand', 'locale.md'), dst);
+      console.log(`seed:    ${dst}`);
+    }
+  }
+
   // The linter is code, not a template — refresh it to the shipped version.
   // Shipped via package.json files[]; if that ever regresses, warn instead of
   // dying on an ENOENT stack trace after the rules are already installed.
-  const lintSrc = path.join(ROOT, 'plugins', 'super-ux', 'scripts', 'ux_lint.py');
-  const lintDst = path.join(target, 'docs', 'ux', 'lint.py');
-  if (fs.existsSync(lintSrc)) {
-    fs.copyFileSync(lintSrc, lintDst);
-    console.log(`sync:    ${lintDst}`);
-  } else {
-    console.error(
-      `warning: linter not found in this package (${lintSrc}); docs/ux/lint.py was not installed.\n` +
-        `         Get it from https://github.com/${REPO}/blob/main/plugins/super-ux/scripts/ux_lint.py`
-    );
+  // Paths stay literal so test/validate.py can read them out of this source and
+  // check them against package.json files[] — a variable segment here silently
+  // turns that check into a directory prefix nobody ships.
+  for (const [src, from, area, dst] of [
+    ['ux_lint.py', path.join(ROOT, 'plugins', 'super-ux', 'scripts', 'ux_lint.py'), 'ux', 'lint.py'],
+    ['ux_doctor.py', path.join(ROOT, 'plugins', 'super-ux', 'scripts', 'ux_doctor.py'), 'ux', 'doctor.py'],
+    ['brand_lint.py', path.join(ROOT, 'plugins', 'super-ux', 'scripts', 'brand_lint.py'), 'brand', 'lint.py'],
+  ]) {
+    const to = path.join(target, 'docs', area, dst);
+    if (fs.existsSync(from)) {
+      fs.copyFileSync(from, to);
+      console.log(`sync:    ${to}`);
+    } else {
+      console.error(
+        `warning: ${src} not found in this package (${from}); docs/${area}/${dst} was not installed.\n` +
+          `         Get it from https://github.com/${REPO}/blob/main/plugins/super-ux/scripts/${src}`
+      );
+    }
   }
 
   console.log(`done: ${installed} installed, ${skipped} skipped`);

package/cursor/rules/brand-voice.mdc

@@ -0,0 +1,37 @@
+---
+description: Brand voice and copy — docs/brand/ is the source of truth for how the product speaks; any public-facing text change updates it in the same change and passes docs/brand/lint.py
+alwaysApply: false
+---
+
+# Brand voice (super-ux)
+
+`docs/ux/` decides what the product does. `docs/brand/` decides how it
+speaks, under `brand-contract v1`.
+
+## Before writing any user-visible text
+
+Read `docs/brand/voice.md`, `terminology.md`, and the `channels.md` record
+for the surface. No pack yet → run `/brand-init` rather than improvising a
+voice; a product whose copy was invented surface by surface is the drift
+this layer removes.
+
+## Rules
+
+- Any change to public text updates `docs/brand/` in the same change.
+- Never quote a figure with no row in `facts.md`. Never invent a fact,
+  statistic, quote or expert — report the gap.
+- One action, one name, everywhere it appears. Check `strings.md` first.
+- A register moves the voice axes; it never crosses the invariants listed in
+  `voice.md`.
+- No humor, exclamation marks or emoji on error, destructive confirm,
+  billing or paywall surfaces, in any voice.
+- New interface strings get a `strings.md` row: key, `file:line`, scenario.
+
+## Check
+
+```bash
+python3 docs/brand/lint.py
+```
+
+Exit 0 clean, 1 warnings, 2 errors. Clean means checkable, not good — the
+judgement half is `/ux-audit copy`.

package/cursor/rules/super-ux.mdc

@@ -14,6 +14,10 @@ alwaysApply: true
 - Run the linter after any UX change and before calling work done:
   `python3 docs/ux/lint.py`. It must pass — drift must not merge; wire it
   into CI/pre-commit.
+- Run `python3 docs/ux/doctor.py` when picking this base up after a while.
+  The linter checks the chain against itself and stays silent when the whole
+  base is written to an old contract; the doctor is what notices. Fix a
+  mixed or stale contract before designing on top of it.
 - Any change that touches user-facing behavior MUST update
   `docs/ux/scenarios.md` in the same change (add/adjust scenarios, statuses,
   coverage). New user-facing behavior with no scenario is a blocker, not a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "super-ux",
-  "version": "0.28.0",
+  "version": "0.30.0",
   "description": "Scenario-driven UI development for AI agents (Claude Code, Cursor, 70+ agents): a versioned design chain in docs/ux/, a scenario-first hard rule, a deterministic drift linter, and evidence-backed UX audits. This package is the installer CLI.",
   "bin": {
     "super-ux": "bin/super-ux.js"
@@ -10,6 +10,8 @@
     "cursor",
     "templates",
     "plugins/super-ux/scripts/ux_lint.py",
+    "plugins/super-ux/scripts/ux_doctor.py",
+    "plugins/super-ux/scripts/brand_lint.py",
     "README.md",
     "LICENSE",
     "CHANGELOG.md"