super-ux 0.28.0 → 0.30.0

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

@@ -0,0 +1,251 @@
+#!/usr/bin/env python3
+"""Diagnose a project's UX chain against the current contract (stdlib only).
+
+`ux_lint.py` checks a chain against itself -- ids, links, orphans. It cannot
+tell you that the whole base is written to a contract three versions old,
+because from the inside everything is consistent. That is the drift this
+finds: between the project and the contract it was written to.
+
+Read-only by default. `--fix` applies only the changes that cannot be wrong:
+renaming a file the contract owns and stamping a marker onto an artifact whose
+shape already matches. Everything else is reported for a human to decide.
+
+    python3 ux_doctor.py [path]           # report
+    python3 ux_doctor.py [path] --fix     # apply the safe subset
+    python3 ux_doctor.py [path] --brief   # one line, for sweeping many projects
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+
+CURRENT = 4
+
+# What each contract version introduced, so a report can say what is missing
+# rather than only that something is old.
+HISTORY = {
+    2: "`Traces:` on every scenario + traceability rules; `foundation.md` (personas, JTBD, journeys, stories)",
+    3: "scenarios become use cases (`user action -> system response`), `Alt paths`, `Traces` includes `FLW-NN`; `flows.md`; `plans/`",
+    4: "`screens.md` — one `SCR-NN` entry per screen with per-state Figma frames; flows reference screens by id instead of respecifying them",
+}
+
+# Additive since v4 — absence is not a version problem, but it is worth naming.
+ADDITIVE = [
+    ("foundation.md", "## Product mechanics", "Product mechanics section (personalization, engagement, a11y regime) — 0.26.1"),
+    ("scenarios.md", "**Telemetry:**", "`Telemetry` on scenarios — the bridge to analytics practices, 0.28.0"),
+    ("foundation.md", "**Kill criteria:**", "`Kill criteria` on stories — gives `dropped` a definition, 0.28.0"),
+]
+
+ARTIFACTS = ["foundation.md", "flows.md", "screens.md", "scenarios.md"]
+
+# Names the contract owns, and the near-misses seen in the wild.
+RENAMES = {
+    "ux-scenarios.md": "scenarios.md",
+    "ux-flows.md": "flows.md",
+    "ux-foundation.md": "foundation.md",
+    "ux-screens.md": "screens.md",
+}
+
+
+def find_ux_dir(arg: str | None) -> Path | None:
+    base = Path(arg) if arg else Path.cwd()
+    for cand in (base, base / "docs" / "ux", base.parent if base.name else base):
+        if any((cand / a).exists() for a in ARTIFACTS) or (cand / "ux-scenarios.md").exists():
+            return cand
+    return None
+
+
+def marker(path: Path) -> int | None:
+    try:
+        head = path.read_text(encoding="utf-8", errors="ignore")[:2000]
+    except OSError:
+        return None
+    m = re.search(r"ux-contract v(\d+)", head)
+    return int(m.group(1)) if m else None
+
+
+def diagnose(ux: Path) -> dict:
+    present = {a: (ux / a).exists() for a in ARTIFACTS}
+    markers = {a: marker(ux / a) for a in ARTIFACTS if present[a]}
+    known = [v for v in markers.values() if v is not None]
+
+    misnamed = {
+        wrong: right
+        for wrong, right in RENAMES.items()
+        if (ux / wrong).exists() and not (ux / right).exists()
+    }
+    # Audit reports loose in docs/ux instead of docs/ux/audits/
+    loose = sorted(
+        p.name for p in ux.glob("*.md")
+        if re.search(r"audit", p.name, re.I) and p.name not in ARTIFACTS
+    )
+    audits = sorted(p.name for p in (ux / "audits").glob("*.md")) if (ux / "audits").is_dir() else []
+
+    missing_additive = []
+    for fname, needle, label in ADDITIVE:
+        f = ux / fname
+        if f.exists() and needle not in f.read_text(encoding="utf-8", errors="ignore"):
+            missing_additive.append(label)
+
+    return {
+        "present": present,
+        "markers": markers,
+        "effective": min(known) if known else None,
+        "mixed": len(set(known)) > 1,
+        "misnamed": misnamed,
+        "loose_audits": loose,
+        "audits": audits,
+        "missing_additive": missing_additive,
+    }
+
+
+def report(ux: Path, d: dict) -> int:
+    problems = 0
+    print(f"docs/ux: {ux}")
+
+    eff, markers = d["effective"], d["markers"]
+    unmarked = [a for a, v in markers.items() if v is None]
+
+    if d["mixed"]:
+        problems += 1
+        detail = ", ".join(f"{a} v{v}" for a, v in sorted(markers.items()) if v)
+        print(f"  MIXED CONTRACT: {detail}")
+        print("    Each artifact was last touched by a different version and nothing reconciled them.")
+    elif eff is None:
+        problems += 1
+        print("  NO CONTRACT MARKER on any artifact — the chain is unmanaged.")
+    elif eff < CURRENT:
+        problems += 1
+        print(f"  BEHIND: contract v{eff}, current v{CURRENT}")
+
+    if unmarked and not d["mixed"]:
+        problems += 1
+        print(f"  UNMARKED: {', '.join(sorted(unmarked))}")
+
+    lowest = eff if eff is not None else 1
+    for v in range(lowest + 1, CURRENT + 1):
+        if v in HISTORY:
+            print(f"    v{v} added — {HISTORY[v]}")
+
+    for wrong, right in d["misnamed"].items():
+        problems += 1
+        print(f"  MISNAMED: {wrong} -> {right}  (the tooling looks for the contract name and finds nothing)")
+
+    missing_core = [a for a, ok in d["present"].items() if not ok]
+    if missing_core:
+        print(f"  ABSENT: {', '.join(missing_core)}")
+
+    if d["loose_audits"]:
+        problems += 1
+        print(f"  AUDITS OUTSIDE audits/: {', '.join(d['loose_audits'])}")
+
+    if d["audits"] and not d["present"].get("scenarios.md"):
+        problems += 1
+        print(f"  {len(d['audits'])} audit report(s) but no scenarios.md — audited against a base that is not there")
+
+    for label in d["missing_additive"]:
+        print(f"  optional, absent: {label}")
+
+    print("  OK — on the current contract" if problems == 0 else f"  {problems} problem(s)")
+    return problems
+
+
+def fix(ux: Path, d: dict) -> list[str]:
+    """Only the changes that cannot be wrong."""
+    done = []
+    for wrong, right in d["misnamed"].items():
+        (ux / wrong).rename(ux / right)
+        done.append(f"renamed {wrong} -> {right}")
+    if d["loose_audits"]:
+        (ux / "audits").mkdir(exist_ok=True)
+        for name in d["loose_audits"]:
+            (ux / name).rename(ux / "audits" / name)
+            done.append(f"moved {name} -> audits/")
+    return done
+
+
+def brand_contract_state(root: Path) -> list[str]:
+    """The brand pack's contract version, or why there is nothing to report.
+
+    Same blind spot as the chain's: a pack written to an old contract is
+    internally consistent, so `brand_lint.py` stays quiet about it. Only a
+    marker comparison notices, which is why the doctor reads it too.
+    """
+    brand = root / "docs" / "brand"
+    if not brand.is_dir():
+        return []
+    versions: dict[str, str] = {}
+    unmarked: list[str] = []
+    for path in sorted(brand.rglob("*.md")):
+        text = path.read_text(encoding="utf-8", errors="replace")
+        found = re.search(r"^Contract:\s*brand-contract\s*(v\d+)\s*$", text, re.M)
+        rel = path.relative_to(brand).as_posix()
+        if found:
+            versions[rel] = found.group(1)
+        else:
+            unmarked.append(rel)
+    out = []
+    distinct = set(versions.values())
+    if len(distinct) > 1:
+        out.append(
+            "docs/brand: mixed contract versions -- "
+            + ", ".join(f"{k} {v}" for k, v in sorted(versions.items()))
+        )
+    elif distinct and distinct != {"v1"}:
+        out.append(
+            f"docs/brand: written to brand-contract {distinct.pop()}, current is v1"
+        )
+    if unmarked:
+        out.append(
+            "docs/brand: no contract marker on " + ", ".join(unmarked[:4])
+        )
+    return out
+
+
+def main() -> int:
+    args = [a for a in sys.argv[1:] if not a.startswith("--")]
+    ux = find_ux_dir(args[0] if args else None)
+    if ux is None:
+        print("no UX docs found (docs/ux/). Run /ux to set one up.")
+        return 0
+
+    d = diagnose(ux)
+    if "--brief" in sys.argv:
+        eff = d["effective"]
+        state = "mixed" if d["mixed"] else (f"v{eff}" if eff else "unmarked")
+        flags = []
+        if d["misnamed"]:
+            flags.append("misnamed")
+        if d["loose_audits"]:
+            flags.append("loose-audits")
+        if d["audits"] and not d["present"].get("scenarios.md"):
+            flags.append("audits-without-base")
+        print(f"{ux}  {state}{'  ' + ','.join(flags) if flags else ''}")
+        return 0
+
+    problems = report(ux, d)
+
+    brand = brand_contract_state(ux.parent.parent)
+    if brand:
+        print("\nBrand pack:")
+        for line in brand:
+            print(f"  {line}")
+        problems = True
+
+    if "--fix" in sys.argv:
+        applied = fix(ux, d)
+        print("\nApplied:" if applied else "\nNothing to apply automatically.")
+        for line in applied:
+            print(f"  {line}")
+        if applied:
+            print("  Re-run without --fix to see what is left for a human.")
+    elif problems:
+        print("\n  --fix applies the mechanical subset (renames, moving audit reports).")
+        print("  Contract upgrades are content decisions: run /ux-update for those.")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/templates/brand/README.md

@@ -0,0 +1,53 @@
+Contract: brand-contract v1
+
+# docs/brand/ — how this product speaks
+
+`docs/ux/` decides **what the product does**. This folder decides **how it
+speaks** — in the interface, on the landing page, in the store listing, in a
+post. One voice, many registers.
+
+Owned by the `brand-voice` skill. Written by `copywriting`. Checked by
+`python3 docs/brand/lint.py` and by `/ux-audit copy`.
+
+| File | Holds |
+|---|---|
+| `voice.md` | the identity: pack, five axes, narrative, invariants |
+| `terminology.md` | our words, banned words, entity and tier names |
+| `facts.md` | canonical numbers and proof — the only source of a figure |
+| `channels.md` | one record per surface: register, limits, bans |
+| `strings.md` | interface string registry → `file:line` → scenario |
+| `locales/<code>.md` | per-locale delta |
+
+## Sources
+
+**Fill this in before anything else.** The linter scans nothing outside these
+paths, and refuses to report a clean run over a surface it never read
+(`B006`). Delete the keys this project does not have — a declared-but-absent
+source is worse than an omitted one.
+
+```
+Sources:
+  ui:        src/**/*.{ts,tsx,js,jsx,vue,svelte}
+  marketing: content/**/*.{md,mdx}
+  store:     store/{ios,android}/*.md
+  robots:    public/robots.txt
+  locales:   src/locales/*.json
+```
+
+`ui` and `marketing` also classify findings — several checks apply to only
+one of the two.
+
+## The hard rule
+
+Any change to public-facing text updates this folder in the same change, and
+`python3 docs/brand/lint.py` exits clean before the work is called done.
+
+## Commands
+
+| Command | Does |
+|---|---|
+| `/brand` | status across every file, then one recommended action |
+| `/brand-init` | pick a voice pack and calibrate it to this product |
+| `/brand-update` | recalibrate after positioning or personas changed |
+| `/brand-lint` | run the linter |
+| `/copy` | write or edit copy for a named surface |

package/templates/brand/channels.md

@@ -0,0 +1,129 @@
+Contract: brand-contract v1
+
+# Channels
+
+One record per surface. `Register` is deltas against the five axes in
+`voice.md` — a register moves the axes, never the invariants.
+
+`Forbidden` always carries both halves, even when one is `none`. Platform
+physics and brand choice written on one line become indistinguishable within
+a quarter, and then nobody can tell which is safe to revisit when the
+platform changes.
+
+Delete the surfaces this product does not have. Do not rename one: the
+linter and the audit address surfaces by the names in the contract.
+
+---
+
+## Product surfaces
+
+### primary action
+
+```
+Register:   <humor -1>
+Format:     <verb phrase naming the outcome; one primary per screen>
+Limits:     <24 characters>
+Forbidden:  physics: none | brand: <"Submit", "OK", bare nouns>
+CTA:        <this surface is the CTA>
+Proof:      none
+Locales:    <coefficient applies to the character limit>
+```
+
+### error
+
+```
+Register:   humor -3, density +1, distance -1
+Format:     what happened, what was not affected, one next step
+Limits:     <…>
+Forbidden:  physics: none | brand: humor, "unexpected", blame, bare codes
+CTA:        the recovery action
+Proof:      none
+Locales:    <…>
+```
+
+### empty state
+
+```
+Register:   <unchanged>
+Format:     what belongs here, why it is worth it, the one starting action
+Limits:     <…>
+Forbidden:  physics: none | brand: apology, "Nothing here yet" alone
+CTA:        one
+Proof:      none
+Locales:    <…>
+```
+
+### paywall and upgrade
+
+```
+Register:   humor -3, distance +1
+Format:     what is sold, what it costs, what happens at term end, how to leave
+Limits:     <…>
+Forbidden:  physics: none | brand: humor, manufactured urgency, hidden terms
+CTA:        one primary, one way out
+Proof:      one sourced figure
+Locales:    <legal differences per locale>
+```
+
+### destructive confirm
+
+```
+Register:   humor -3
+Format:     object, consequence, reversibility; verb repeats the action
+Limits:     <…>
+Forbidden:  physics: none | brand: humor, "OK" as the confirming verb
+CTA:        the destructive verb
+Proof:      none
+Locales:    <…>
+```
+
+<add the remaining product surfaces this product has: loading,
+success/toast, onboarding, billing and receipts, settings and legal,
+transactional email and push, docs and help>
+
+---
+
+## Marketing surfaces
+
+### landing hero
+
+```
+Register:   confidence +1, density -1
+Format:     one headline, one subhead, one primary action
+Limits:     title 60, meta description 160
+Forbidden:  physics: none | brand: superlatives with no facts.md row
+CTA:        one, verb plus outcome
+Proof:      one number, sourced
+Locales:    <coefficient applies to both limits>
+```
+
+### X
+
+```
+Register:   density +1, distance -1
+Format:     one idea; threads 5-12 posts, each standing alone
+Limits:     280
+Forbidden:  physics: link in body suppresses reach; >2 hashtags penalised;
+            editing within 30 minutes resets distribution
+            | brand: <engagement bait, fake urgency>
+CTA:        <in the first reply, not the post>
+Proof:      <one figure, sourced>
+Locales:    <…>
+```
+
+### Reddit
+
+```
+Register:   distance -2, humor +1
+Format:     a statement, not a headline; the comments are the content
+Limits:     <per subreddit>
+Forbidden:  physics: <subreddit rules outrank everything here>
+            | brand: undisclosed affiliation, CTA of any kind
+CTA:        none
+Proof:      <first-hand only>
+Locales:    <…>
+```
+
+<add the remaining marketing surfaces this product uses: landing body,
+pricing, blog, changelog, LinkedIn, HN and Product Hunt, App Store,
+Google Play, ads, lifecycle email>

package/templates/brand/facts.md

@@ -0,0 +1,36 @@
+Contract: brand-contract v1
+
+# Facts
+
+**The only source of any figure in public copy.** A number on a public
+surface with no row here is `B030` and blocks. A row with no `Source`, or one
+past its `Review by`, is `B031` and warns.
+
+A missing fact is reported, never invented to close a gap.
+
+| Fact | Value | Source | Checked | Review by | Public |
+|---|---|---|---|---|---|
+| <what the number counts> | <448> | <api/catalog.json> | <2026-08-05> | <2026-11-05> | <yes> |
+| <internal figure> | <$3.10> | <billing export> | <2026-08-05> | <2026-11-05> | <no> |
+
+`Public: no` marks figures that exist and must never be quoted — internal
+margins, unreleased counts, anything under embargo. The linter treats
+quoting one as the same failure as quoting a number that does not exist.
+
+## Proof that is not a number
+
+Testimonials, awards, certifications and press. Same rules: attributed,
+dated, and re-checked.
+
+| Claim | Attribution | Source | Checked | Review by | Public |
+|---|---|---|---|---|---|
+| <…> | <name, role, company> | <where it was said> | <YYYY-MM-DD> | <YYYY-MM-DD> | <yes> |
+
+## Required disclaimers
+
+Text that must appear alongside specific claims — regulatory, contractual, or
+promised. Locale differences live in `locales/<code>.md`.
+
+| Claim it attaches to | Required text |
+|---|---|
+| <…> | <…> |

package/templates/brand/locale.md

@@ -0,0 +1,68 @@
+Contract: brand-contract v1
+Locale: <de>
+Primary: <no>
+Address form: <Sie>
+Length coefficient: <1.30>
+Humor: <-1 from base>
+Never translated: <product name, entity names, tier names>
+Keywords: <own research — see below>
+Reviewed by: <name of someone who reads this language daily, or `unreviewed`>
+
+# Locale delta
+
+Copy this file to `locales/<code>.md`, one per declared locale. The invariant
+half of the voice does not appear here — it is in `voice.md` and holds in
+every language. This file carries only what is decided again.
+
+## Address form
+
+<The single choice, applied everywhere. This decision changes how the brand
+is perceived more than any word choice, so it is made once and recorded, not
+per string.>
+
+## Dead idioms
+
+Idiom and wordplay from the primary locale that does not survive. The
+replacement does the same **job**; it is not a translation of the joke.
+
+| Primary | Replacement | Job it does |
+|---|---|---|
+| <"ship it"> | <"raus damit"> | <permission to stop polishing> |
+
+## Keywords
+
+Researched in this market, never translated from the primary. The
+translation of a high-volume English term is routinely a term with no volume,
+while the term people actually type is a different word.
+
+| Term | Volume | Where it is used |
+|---|---|---|
+| <…> | <…> | <…> |
+
+## Legal differences
+
+Required copy this locale has and others do not. Treated as required strings:
+a missing one is a defect even when parity is otherwise complete.
+
+| Requirement | Text or reference |
+|---|---|
+| <Impressum> | <…> |
+| <VAT-inclusive pricing> | <…> |
+
+## Length notes
+
+Surfaces where the coefficient bites hardest in this locale — usually
+buttons, tab labels, store title and subtitle. Recorded here so the
+constraint reaches the primary-locale original, where it can still be
+designed around.
+
+| Surface | Primary limit | Effective limit | Note |
+|---|---|---|---|
+| <App Store title> | <30> | <23> | <…> |
+
+## Parity
+
+Computed by the linter against `strings.md`; not maintained by hand. Below
+the threshold in `voice.md` it warns (`B071`) with the percentage. A partial
+locale that declares itself is a known state; one that does not is a surprise
+for a user who does not speak the fallback.

package/templates/brand/strings.md

@@ -0,0 +1,41 @@
+Contract: brand-contract v1
+
+# Interface strings
+
+A **decision registry**, not a message catalog. It holds no translations and
+does not replace i18n keys. It records which strings have been reconciled
+with the voice, which scenario each serves, and where each one lives.
+
+This is what makes "one action, two names" (`B020`) checkable at all. Without
+it, that defect is only findable by reading the entire interface — which is
+why it survives in every product that has not written one down.
+
+Populated by an inventory sweep at init, not by hand.
+
+| Key | Text (primary) | Location | Scenario | Status |
+|---|---|---|---|---|
+| <action.project.publish> | <Publish> | <src/ui/ProjectBar.tsx:47> | <SCN-014> | <agreed> |
+
+## Columns
+
+- **Key** — dot-separated, stable, names the action rather than the screen.
+  Two rows sharing a `Key` with different `Text` is `B020`.
+- **Text (primary)** — the string in the primary locale. Other locales live
+  in the project's own i18n files; parity is computed against this column.
+- **Location** — `file:line`. A location that no longer resolves is `B023`.
+- **Scenario** — the `SCN-NNN` this string serves. A string serving no
+  scenario is a question for `ux-scenarios`, not a copy problem.
+- **Status** — `agreed` · `proposed` · `drifted` · `orphan`.
+
+## Statuses
+
+| Status | Means |
+|---|---|
+| `agreed` | reconciled with the voice and approved |
+| `proposed` | written, not yet approved |
+| `drifted` | the code no longer matches this row (`B021`) |
+| `orphan` | in the registry, no longer in the code |
+
+A string found in code with no row here is `B022` — a warning, not an error,
+so adopting this registry on an existing product does not block from day one.
+It becomes an error only once someone agrees the row.

package/templates/brand/terminology.md

@@ -0,0 +1,45 @@
+Contract: brand-contract v1
+
+# Terminology
+
+The dictionary the linter reads. Column one of **Product terms** and
+**Banned** drives `B010` and `B011`; **Entity and tier names** drives `B012`.
+
+## Product terms — always
+
+Where the product has its own word, the generic one is a defect, not a
+synonym.
+
+| Our term | Never write | Applies to |
+|---|---|---|
+| <Run> | <Execution, Job> | <what the product performs> |
+
+## Entity and tier names — exact spelling
+
+One spelling, everywhere: interface, marketing, billing, support, docs.
+
+| Name | Wrong forms seen |
+|---|---|
+| <Pro> | <PRO, Pro plan, pro> |
+
+## Banned
+
+Seeded at init from weak verbs, hedging chains and the marker vocabulary in
+`ai-tells.md`. Calibration adds what is specific to this product.
+
+| Word or phrase | Why | Use instead |
+|---|---|---|
+| leverage | filler verb | use |
+| seamless | claims what it cannot show | name the step that disappeared |
+| utilize | longer word, same meaning | use |
+| robust | hides the number | the number |
+| <…> | <…> | <…> |
+
+## Glossary
+
+Terms this product uses in a specific sense. If a term is here, it is
+grounded before it is leaned on.
+
+| Term | Meaning |
+|---|---|
+| <…> | <…> |

package/templates/brand/voice.md

@@ -0,0 +1,58 @@
+Contract: brand-contract v1
+Voice pack: <pack id from voice-packs.md, or `custom`>
+Locales: <en (primary)>
+Locale parity threshold: 80%
+Derived-from: <PER-NN, JTBD-NN from docs/ux/foundation.md — or `inferred`>
+Status: draft
+Last calibrated: <YYYY-MM-DD>
+
+# Voice
+
+The pack was the starting position. This file is the truth.
+
+## Axes
+
+The five axes are fixed. A project sharpens the wording; it does not add or
+remove an axis, because `channels.md` expresses every register as a delta
+against exactly these five.
+
+| Axis | The product IS | The product IS NOT |
+|---|---|---|
+| Confidence | <…> | <…> |
+| Register | <…> | <…> |
+| Distance | <…> | <…> |
+| Humor | <…> | <…> |
+| Density | <…> | <…> |
+
+## Narrative
+
+```
+Hero:         <who the reader is, in the role this product meets them in>
+Enemy:        <the state of the world that costs them — not a competitor>
+Product role: <instrument | guide | weapon>
+Promise:      <one line, checkable against a row in facts.md>
+```
+
+## Invariant in every language
+
+What survives translation. Breaking one of these is a finding on any surface,
+in any locale.
+
+- <e.g. never hedges>
+- <e.g. never claims a number that is not in facts.md>
+
+## Reconsidered per locale
+
+Conventions rather than character. Each is decided again in
+`locales/<code>.md`.
+
+- address form
+- humor level
+- idiom and wordplay
+- <…>
+
+## Failure mode
+
+Copied from the pack, kept here so the audit can look for it by name.
+
+<the degenerate form this voice collapses into when overdone>