super-ux 0.48.4 → 0.49.1

package/CHANGELOG.md

@@ -1,5 +1,60 @@
 # Changelog
 
+## 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
+  marker is more common in model output; none proves a machine wrote anything, and the
+  failure is not symmetric. Independent audits found false-positive rates **above 60% on
+  non-native English writers** (Liang et al., Stanford, *Patterns*, 2023). Three rules bind
+  the rest of the file: never say a text was AI-written, only which markers appear at what
+  density; never gate on a marker count; and a second-language writer is not a defect to be
+  edited into fluency they did not ask for.
+- **Other implementations are named, compared and pointed at** — `blader/humanizer` and
+  `conorbronsdon/avoid-ai-writing`, with a table of what each does that this pack does not
+  and the reverse. Reach outward for an audit that changes nothing (only one has a
+  detect-only mode), for long-form prose, or when the writer has a sample of their own
+  writing to match. Stay here for product copy: the brand pack's registers, terminology and
+  canonical facts are the constraint, and a general-purpose humanizer does not read them.
+  Two guards remain this pack's own — the 50% change-rate refusal and the mandatory
+  semantic-preservation check — and neither external implementation carries an equivalent.
+- **`voice.md` gains an optional `Humanization pass:` field**, and its absence is
+  meaningful: it means nobody has been asked. `brand-voice` Init asks once and records the
+  answer; `copywriting` reads it rather than asking again. A value naming a tool that is not
+  installed falls back to `own` and says so — a missing optional tool must not stop copy
+  being written.
+- `npx sshlg-skills humanizers` lists what is installed on the machine.
+
 ## 0.48.4 — the channel that sends the installs, on npm too
 
 - The `skills.sh` badge and the canonical `homepage` reached GitHub in the previous cycle and stopped

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.48.4",
+  "version": "0.49.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"
+    "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": {

package/templates/brand/voice.md

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