super-ux 0.49.0 → 0.50.0

package/CHANGELOG.md

@@ -1,5 +1,71 @@
 # Changelog
 
+## 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
+  «мокап»).
+
+## 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`
+  auto-detects Claude Code and writes a plain `~/.claude/skills/super-ux` copy even when
+  claude-code is never picked, and on a machine where super-ux is installed as a Claude
+  Code plugin that copy shadows the plugin and serves the version it was copied from
+  forever. The handoff now reads `~/.claude/plugins/installed_plugins.json` — the record of
+  what is actually installed, under any marketplace name — and refuses with **exit 3**, the
+  remedy in the refusal (`claude plugin marketplace update super-ux`, `claude plugin update
+  <spec from the JSON>`, and the family launcher), and `npx super-ux --force` as the named
+  override. The `plugins/marketplaces/super-ux` directory is kept only as the fallback
+  signal: it under-reports, because a directory-sourced marketplace has no dir there and
+  plugin names differ from marketplace names. A missing or corrupt JSON reads as "no
+  plugin" — fail open, never crash. Only the Claude Code channel is gated; `--cursor`
+  installs into a project beside the plugin exactly as before. Canon:
+  make-skill v0.25.0, `references/distribution.md` §3; reproduced live 2026-08-29 when a
+  bare `npx @ssheleg/telegram-dev` shipped three shadows past this exact class of hole.
+- **A successful run now ends by saying how the next version arrives** — `npx
+  super-ux@latest` for this member, the family launcher for every channel at once. An
+  installer that never mentions updates has still chosen an update model: never.
+- **`test/installer_test.js`** runs both installers against throwaway HOMEs — the
+  plugin-present refusal (exit 3, remedy, nothing delegated, nothing written), the
+  differently-named marketplace spec in the remedy, `--force`, corrupt-JSON fail-open, a
+  prefix collider (`super-ux-extra@x`), the marketplaces-dir fallback, the fresh HOME, and
+  that `install.sh` never touches `~/.claude` at all. Wired into `npm test` and CI; watched
+  failing against the pre-fix installer (7 of 10 cases red, the plugin-present case
+  delegating with exit 0) before the fix was un-stashed.
+- SCN-016 and SCN-017 record the refusal and the update line in `docs/ux/scenarios.md`;
+  SCR-05 gains the `refused` state; the string registry carries the new copy and the
+  `refused:` prefix joins the state vocabulary.
+
 ## 0.49.0 — the humanization pass names what it cannot prove
 
 - **`ai-tells.md` now says these markers are not a verdict, and who they misjudge.** Every

package/README.md

@@ -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/bin/super-ux.js

@@ -7,16 +7,60 @@
  * rules into a project, Claude Code plugin user-globally. Non-TTY stdin gets
  * a text fallback ("1,3" / "all"). Flags keep the non-interactive paths:
  * --cursor [dir] [--force].
+ *
+ * The skills handoff is gated: while super-ux is installed as a Claude Code
+ * plugin, delegating to the skills CLI would recreate the plain
+ * ~/.claude/skills/super-ux copy that shadows the plugin, so the handoff is
+ * refused (exit 3) unless --force records the two-channel choice.
  */
 'use strict';
 
 const fs = require('fs');
+const os = require('os');
 const path = require('path');
 const readline = require('readline');
 const { spawnSync } = require('child_process');
 
 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).
+const EXIT_PLUGIN_PRESENT = 3;
+
+/**
+ * The plugin spec (`<name>@<marketplace>`) installed for `name` in this home,
+ * or null.
+ *
+ * `installed_plugins.json` is the record of what is actually installed. The
+ * `plugins/marketplaces/<name>` directory under-reports: a marketplace added
+ * from a local `directory` source has no dir there at all, and plugin names
+ * differ from marketplace names, so a check keyed on it stays green while the
+ * shadow lands. Absence and corruption both read as "no plugin": the fresh
+ * HOME is the common case, and an installer that crashes on a parse error
+ * refuses the machines that need it most.
+ */
+function installedPluginSpec(home, name) {
+  try {
+    const raw = fs.readFileSync(
+      path.join(home, '.claude', 'plugins', 'installed_plugins.json'), 'utf8');
+    const parsed = JSON.parse(raw);
+    const plugins =
+      parsed && typeof parsed === 'object' &&
+      parsed.plugins && typeof parsed.plugins === 'object'
+        ? parsed.plugins
+        : parsed;
+    if (!plugins || typeof plugins !== 'object') return null;
+    for (const spec of Object.keys(plugins)) {
+      if (spec === name) return `${name}@${name}`;
+      if (spec.startsWith(name + '@')) return spec;
+    }
+  } catch {
+    // missing or corrupt = no plugin — fail open on absence, never crash
+  }
+  return null;
+}
 
 const MENU_ITEMS = [
   { key: 'skills', label: 'Skills for any AI agent (Claude Code, Codex, Cursor, 70+; opens agent picker)' },
@@ -28,13 +72,20 @@ function usage() {
   console.log(`super-ux installer
 
 Usage:
-  npx super-ux                                  interactive menu (multi-select)
+  npx super-ux [--force]                        interactive menu (multi-select)
   npx super-ux --cursor [project-dir] [--force] Cursor rules, non-interactive
   npx super-ux --help
 
+Exit codes:
+  0 installed or nothing selected   1 error
+  3 refused: the super-ux PLUGIN is installed in this home, and the skills
+    CLI would write the plain ~/.claude/skills copy that shadows it
+    (pass --force to run the picker anyway)
+
 Menu items (select any combination, 'a' = all):
   1. Skills for any AI agent (Claude Code, Codex, Cursor, 70+) — delegates to
      'npx skills add ${REPO}' with its agent/global/project picker.
+     Refused while the super-ux plugin is installed (see exit code 3).
   2. Cursor rules: cursor/rules/*.mdc -> <project>/.cursor/rules/, plus the
      docs/ux skeleton, the docs/brand pack, and all three linters
      (docs/ux/lint.py, docs/ux/doctor.py, docs/brand/lint.py). Existing
@@ -152,10 +203,62 @@ function run(cmd, args) {
   return result.status === 0 ? 'ok' : 'failed';
 }
 
-function installSkillsCli() {
+/**
+ * One channel per agent. The skills CLI auto-detects Claude Code and writes
+ * ~/.claude/skills/super-ux even when claude-code is never picked, and on a
+ * machine where super-ux is installed as a Claude Code plugin that plain copy
+ * shadows the plugin and serves the version it was copied from forever. So
+ * the handoff consults the TARGET home's installed_plugins.json first and
+ * refuses LOUDLY: a refusal that exits 0 reads as success to every script
+ * above it. The marketplaces/<name> dir is only the fallback signal — a
+ * directory-sourced marketplace has no dir there, and plugin names differ
+ * from marketplace names. Reproduced live 2026-08-29: a bare
+ * `npx @ssheleg/telegram-dev` shipped three shadows past exactly this class
+ * of hole while the plugin was enabled.
+ */
+function installSkillsCli(force) {
+  const home = os.homedir();
+  const spec = installedPluginSpec(home, NAME);
+  const marketplace = path.join(home, '.claude', 'plugins', 'marketplaces', NAME);
+  const viaMarketplaceDir = !spec && fs.existsSync(marketplace);
+  if ((spec || viaMarketplaceDir) && !force) {
+    const found = spec
+      ? `installed as the Claude Code plugin ${spec}\n` +
+        '         (declared in ~/.claude/plugins/installed_plugins.json)'
+      : `registered as a Claude Code marketplace\n         (${marketplace})`;
+    console.error(
+      `refused: super-ux is already ${found}.\n` +
+      '         The skills CLI auto-detects Claude Code and would write a plain copy\n' +
+      '         to ~/.claude/skills/super-ux, which shadows the plugin and serves the\n' +
+      '         version it was copied from forever. Update the plugin channel instead:\n' +
+      '           claude plugin marketplace update super-ux\n' +
+      `           claude plugin update ${spec || 'super-ux@super-ux'}\n` +
+      '         Family launcher (updates every member, prunes shadow copies):\n' +
+      '           npx --yes sshlg-skills@latest update\n' +
+      '         Pass --force (npx super-ux --force) to run the picker anyway: a\n' +
+      '         deliberate choice to run two channels, where the stale one wins.'
+    );
+    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;
+}
+
+/**
+ * The last line of a successful run says how the next version arrives —
+ * "Installed" is not a complete sentence. Auto-update is off on purpose:
+ * this member composes with its family, and per-marketplace autoUpdate moves
+ * each member on its own clock, into combinations nobody tested together.
+ */
+function printUpdateLine() {
+  console.log(
+    '\nUpdates: rerun npx super-ux@latest (--cursor <dir> --force refreshes a\n' +
+    "project's rules and linters), or refresh the whole family with\n" +
+    'npx --yes sshlg-skills@latest update (every channel, and it prunes plain\n' +
+    'copies that would shadow a plugin).'
+  );
 }
 
 function installClaudePlugin() {
@@ -305,7 +408,7 @@ async function selectFallback(items, prompter) {
   return picked;
 }
 
-async function menu() {
+async function menu(force) {
   console.log('super-ux: scenario-driven UI development. Select what to install:\n');
   const interactive = Boolean(process.stdin.isTTY && process.stdout.isTTY);
 
@@ -340,11 +443,21 @@ async function menu() {
 
   if (keys.includes('cursor')) installCursor(cursorDir, false);
   if (keys.includes('claude')) installClaudePlugin();
-  if (keys.includes('skills')) installSkillsCli();
+  let refused = false;
+  if (keys.includes('skills')) refused = installSkillsCli(force) === 'refused';
 
   // 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) {
+    // 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 {
+    printUpdateLine();
+  }
 }
 
 /**
@@ -379,7 +492,14 @@ function main() {
     return;
   }
   if (args.length === 0) {
-    menu();
+    menu(false);
+    return;
+  }
+  // `--force` alone still opens the menu: it is the named override for the
+  // skills-handoff refusal, so it must be reachable from the same door the
+  // refusal names.
+  if (args.length === 1 && args[0] === '--force') {
+    menu(true);
     return;
   }
   if (args[0] !== '--cursor') {
@@ -391,6 +511,7 @@ function main() {
   const dirArg = args[1] && args[1] !== '--force' ? args[1] : '.';
   installCursor(path.resolve(dirArg), force);
   offerRouters();
+  printUpdateLine();
 }
 
 main();

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "super-ux",
-  "version": "0.49.0",
+  "version": "0.50.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"
+    "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"
   },
   "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": {