sheleg-design-skill 1.54.0 → 1.54.1

package/CHANGELOG.md

@@ -6,6 +6,61 @@ follow [SemVer](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [1.54.1] - 2026-08-29
+
+### The installer refuses the shadow it documents
+
+Both installers write a plain skill copy on request, and on a machine where
+`sheleg-design` is installed as a Claude Code plugin, a write to that home's
+`~/.claude/skills/sheleg-design` is a copy that shadows the plugin and serves
+this frozen version forever. Neither installer checked the plugin channel at
+all, and CI tested a fresh HOME only, so the plugin-present case had never run
+anywhere. Canon: make-skill v0.25.0, `references/distribution.md` §"The
+installer must refuse the shadow it documents"; family audit SHD-07/UM-03.
+
+### Added
+
+- `bin/cli.js` and `install.sh` now consult the **target home's**
+  `~/.claude/plugins/installed_plugins.json` before any write to that home's
+  `~/.claude/skills/sheleg-design`, and refuse with **exit 3** when the plugin
+  channel owns the skill. The refusal names the real spec read from the JSON
+  (`sheleg-design@<marketplace>` — the marketplace name differs from the
+  plugin name here, and a remedy that guesses it sends the operator to a
+  marketplace that does not exist), prints the plugin-channel remedy
+  (`claude plugin marketplace update` + `claude plugin update <spec>`, plus
+  the family launcher line), and offers `--force` as the deliberate override.
+  The `plugins/marketplaces/` directory is read only as the fallback signal —
+  it under-reports (a `directory`-sourced marketplace has no dir there), which
+  is the fail-open class the canon names. A missing or unparsable JSON reads
+  as "no plugin": fail open, never crash. Only the Claude Code channel is
+  gated — `.cursor/` and every other agent's install are untouched, and a
+  project-level `.claude/` falls open naturally because a project holds no
+  plugin registry.
+- `install.sh` accepts `--force` (the override for the gate above) and refuses
+  unknown flags with exit 2 instead of treating them as a target directory.
+- `test/installer_test.js` — thirteen cases against throwaway HOMEs, wired
+  into `npm test` and CI: plugin-present (exit 3 + remedy + nothing written,
+  all three asserted), the differently-named marketplace spec carried into the
+  remedy, `--force` installing, corrupt JSON installing, a prefix-collider
+  (`sheleg-design-extra@x`) not falsely refused, marketplaces-dir-only still
+  refusing, fresh HOME still installing, the `.cursor` channel untouched by
+  the gate, and the install.sh mirrors of the same. Watched failing first: run
+  against the pre-fix installers, 7 cases red.
+
+### Changed
+
+- Both installers now end a successful install by saying how the next version
+  arrives (`npx sheleg-design-skill@latest --force`, or the family launcher) —
+  an installer that never mentions updates has still chosen an update model:
+  never.
+- `bin/cli.js --help` documents the exit-code contract, including the new
+  exit 3.
+- CONTRIBUTING: release tags must be **annotated** (`git tag -a`) — v1.53.0
+  and v1.54.0 were lightweight, and `git submodule status` describes a pinned
+  commit with `git describe`, which ignores lightweight tags, so the family
+  umbrella misreported the member's version (SHD-07/UM-03). Applies from this
+  release forward; the old tags are not re-cut.
+
 ## [1.54.0] - 2026-08-29
 
 ### The thirty-eighth pack — the terrain is mapped

package/bin/cli.js

@@ -225,6 +225,13 @@ ${c("bold", "Default")}
   Auto-detects: uses .cursor/ if present, else .claude/ if present,
   otherwise creates .cursor/skills/${SKILL_SLUG}/.
 
+${c("bold", "Exit codes")}
+  0 installed or skipped    2 usage error
+  1 packaging bug, or       3 refused: the sheleg-design PLUGIN is installed
+    overwrite refused         in the target home — a plain copy in
+                              ~/.claude/skills would shadow it and serve this
+                              frozen version forever (--force overrides)
+
 ${c("bold", "What it installs")}
   SKILL.md             the agent-facing skill (discovery + principles)
   SHELEG_DESIGN.md     the full reference (architecture, recipes, why it works)
@@ -328,6 +335,112 @@ function resolveTargetDir(opts, cwd) {
   return path.join(cwd, ".cursor", "skills", SKILL_SLUG);
 }
 
+// Exit codes are the contract: 0 installed or skipped, 1 packaging bug or
+// overwrite refusal, 2 usage error, 3 refused — the plugin channel owns the
+// target home's Claude Code install (--force overrides).
+const EXIT_PLUGIN_PRESENT = 3;
+
+/**
+ * The home whose Claude Code channel this write would land in, or null.
+ *
+ * Only the Claude Code channel is gated: a write to `<H>/.claude/skills/
+ * sheleg-design` is the shape that can shadow a plugin installed in `<H>`.
+ * `.cursor/` and every other agent's skill directory have no plugin channel,
+ * so installs there are untouched by the check. A project-level `.claude/`
+ * matches this shape too, and falls open naturally: a project holds no
+ * `plugins/installed_plugins.json`, so the gate reads "no plugin" and the
+ * install proceeds.
+ */
+function claudeHomeOf(targetDir) {
+  const parts = path.resolve(targetDir).split(path.sep);
+  const tail = parts.slice(-3).join("/");
+  if (tail !== `.claude/skills/${SKILL_SLUG}`) return null;
+  return parts.slice(0, -3).join(path.sep) || path.sep;
+}
+
+/**
+ * The plugin spec (`<name>@<marketplace>`) installed for sheleg-design 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 — this very plugin is `sheleg-design` shipped
+ * from the `sheleg-design-skill` marketplace — so a check keyed on the dir
+ * alone 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) {
+  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 === SKILL_SLUG) return `${SKILL_SLUG}@${SKILL_SLUG}`;
+      if (spec.startsWith(SKILL_SLUG + "@")) return spec;
+    }
+  } catch {
+    // missing or corrupt = no plugin — fail open on absence, never crash
+  }
+  return null;
+}
+
+/**
+ * One channel per agent. A plain `<H>/.claude/skills/sheleg-design` beside an
+ * installed plugin is two listings of the same skill, and the stale copy wins
+ * — the exact shadow the family canon forbids (make-skill
+ * references/distribution.md §"The installer must refuse the shadow it
+ * documents"). Refuse rather than create it, and refuse LOUDLY: a refusal
+ * that exits 0 reads as success to every script above it. Reproduced live
+ * 2026-08-29: a bare `npx @ssheleg/telegram-dev` shipped three shadows past a
+ * marketplace-dir-only check while the plugin was enabled.
+ */
+function refuseIfPluginOwnsChannel(targetDir, force) {
+  const home = claudeHomeOf(targetDir);
+  if (!home || force) return;
+  const spec = installedPluginSpec(home);
+  const marketplaces = path.join(home, ".claude", "plugins", "marketplaces");
+  const mktDir = [SKILL_SLUG, "sheleg-design-skill"]
+    .map((n) => path.join(marketplaces, n))
+    .find((p) => fs.existsSync(p));
+  if (!spec && !mktDir) return;
+
+  const remedySpec = spec || "sheleg-design@sheleg-design-skill";
+  const remedyMarketplace = remedySpec.split("@")[1];
+  const found = spec
+    ? `installed as the Claude Code plugin ${spec}\n` +
+      `         (declared in ${path.join(home, ".claude", "plugins", "installed_plugins.json")})`
+    : `registered as a Claude Code marketplace\n         (${mktDir})`;
+  console.error(
+    c("yellow", `refused: ${SKILL_SLUG} is already ${found}.`) +
+      `\n         A plain copy in ${path.join(home, ".claude", "skills", SKILL_SLUG)}\n` +
+      `         would shadow the plugin and serve this frozen version forever.\n` +
+      `         Update the plugin channel instead:\n` +
+      `           ${c("bold", `claude plugin marketplace update ${remedyMarketplace}`)}\n` +
+      `           ${c("bold", `claude plugin update ${remedySpec}`)}\n` +
+      `         Family launcher (updates every member, prunes shadow copies):\n` +
+      `           ${c("bold", "npx --yes sshlg-skills@latest update")}\n` +
+      `         Pass --force to write the plain copy anyway — a deliberate choice\n` +
+      `         to run two channels, where the stale one wins.`,
+  );
+  // Offered on the refusal path too: the skill IS present on this machine —
+  // as the plugin — so the routing block is exactly as wanted as on the
+  // install path.
+  offerRouters();
+  process.exit(EXIT_PLUGIN_PRESENT);
+}
+
 function main() {
   const opts = parseArgs(process.argv.slice(2));
 
@@ -354,6 +467,10 @@ function main() {
 
   const targetDir = resolveTargetDir(opts, cwd);
 
+  // Before any write to a home's ~/.claude/skills/sheleg-design: if that
+  // home's plugin channel already owns this skill, refuse (exit 3).
+  refuseIfPluginOwnsChannel(targetDir, opts.force);
+
   // Verify the bundle is intact before touching the filesystem.
   for (const f of CORE_FILES) {
     if (!fs.existsSync(path.join(SKILL_DIR, f))) {
@@ -398,6 +515,16 @@ function main() {
   );
 
   offerRouters();
+
+  // The last line 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.
+  console.log(
+    `Updates: rerun ${c("bold", "npx sheleg-design-skill@latest --force")}, or refresh the\n` +
+      `whole family with ${c("bold", "npx --yes sshlg-skills@latest update")} (every channel,\n` +
+      `and it prunes plain copies that would shadow a plugin).\n`,
+  );
 }
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sheleg-design-skill",
-  "version": "1.54.0",
+  "version": "1.54.1",
   "description": "Design taste as an installable agent skill. Cinematic scroll-driven landing pages built on one scroll clock and layered degrade-to-calm motion, a motion doctrine that decides whether to animate before it decides how, three calibration dials, and thirty-eight locked style packs with ready-made design tokens — instrument-console, editorial-luxury, workbench, briefing-room, atrium, orchard, outrank, babylove, patchbay, nameplate, field-notes, cyclorama, showroom, blueprint, prism, maquette, scoreboard, datasheet, manpage, pigeonhole, roster, ora, tenor, paperclip, ledger, router, daylight, notation, almanac, vitrine, proscenium, awning, bulletin, rimlight, onionskin and deskmate, test-drive, surveyor. Colour, slop and fork-reciprocity gates run as scripts, not opinions. Works with Cursor, Claude Code and any agent that reads a SKILL.md.",
   "bin": {
     "sheleg-design-skill": "bin/cli.js"
@@ -19,7 +19,7 @@
     "node": ">=16"
   },
   "scripts": {
-    "test": "python3 test/validate.py && python3 test/validate_palette.py && python3 test/sloplint.py && node --check bin/cli.js && npm run selftest",
+    "test": "python3 test/validate.py && python3 test/validate_palette.py && python3 test/sloplint.py && node --check bin/cli.js && node test/installer_test.js && npm run selftest",
     "validate": "python3 test/validate.py && python3 test/validate_palette.py && python3 test/sloplint.py",
     "smoke": "node bin/cli.js --help",
     "palette": "python3 test/validate_palette.py",

package/plugins/sheleg-design/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "sheleg-design",
   "displayName": "SHELEG Design",
   "description": "SHELEG Design methodology: cinematic scroll-driven landing pages (single scroll clock, layered degrade-to-calm motion, WebGL particle formations), a motion doctrine that decides whether to animate before it decides how, and thirty-eight pluggable visual style packs — instrument-console (dark console), editorial-luxury (warm editorial), workbench (light/dark product UI for dashboards and tools), briefing-room (dark 16:9 deck), atrium (warm consumer health), orchard, outrank, babylove (friendly consumer biotech), patchbay (a dark live schematic: one mint-cyan, 8% hairlines and no shadow, and an architecture diagram whose cords carry SMIL particles), field-notes (warm paper for dev tools sold on auditability), cyclorama (a pastel field on a 32s cycle), showroom (the product as the exhibit), blueprint (a drawing sheet, zero radius), prism (one iridescent wash over mono body), maquette (cream axonometric models on a dark table), scoreboard (warm paper, pixel numerals, a dark ledger of results), datasheet (an off-white spec sheet whose live instrument goes dark when it detects the reader is hiding), manpage (a developer landing page set in the reader's own system monospace on cream paper, with coral label chips that are real headings and a dark code frame as the argument), pigeonhole (a white sorting wall whose nine pastel categories are a filing scheme rather than a mood, each a two-layer chip whose label word is mandatory), roster (a white field in a faint grid of squares whose argument is other people's marks — client logotypes in pill-labelled industry columns, an engine's wordmark inside the headline — where the proof is a name rather than a number), ora (a warm coal field with cream ink and no third hue — the accent is the inverted field — a serif carrying every human sentence over a monospace carrying every machine fact, a terminal surface cut below the page, and a six-step verdict ramp, for products whose output is a machine's verdict about the reader), tenor (warm paper with zero radius and zero shadow, one hairline weight, an orange that exists only on hover and on focus, a sans tracked negative against a mono tracked positive, display at a line-height below one in an eight-to-twelve-character measure, and product proof delivered as silent looping video, for products arguing that a new kind of thing must be managed like an existing organisation), paperclip (neutral coal with no functional colour at all — every control monochrome and elevation made of hairlines, with the whole chromatic budget spent on a curtain of gradient capsules and twelve gradient section badges that cannot be clicked — for products that ask a person to run something that runs itself: agent teams, autonomous back-office, schedulers and budget-governed compute), ledger (warm cream paper ruled by a hairline at 12% ink and no shadow on any card, radius 15 nested concentrically, an ink primary button and a terracotta accent that never fills a control — it labels, as a 10px monospace uppercase kicker — with a seal on every card stating how its number is known, for the console of a product that answers questions about data: AI analysts, BI surfaces, query workspaces), router (a near-white field with a trace of blue and white cards standing on it, hairline seams instead of shadows anywhere, body at 14px and weight 450, and a status triplet in which the colour you paint with is not the colour you write with, for product consoles and the landing pages that have to look like them), daylight (a cool near-white portal field with generous radii and one very large soft shadow spent on a single object per screen, for client portals), notation (a near-white page drawn entirely in hairlines with a light serif over a monospace, no bold anywhere and an ink primary, for developer products sold on restraint), almanac (oatmeal paper with 2px seams and no 1px anywhere, a display set below a line-height of one, and mono tags notched through drawn boxes, for pages that assert a category), vitrine (a white hairline field with a serif display, an ink primary and one framed record carrying the evidence, for the front door of a product sold on trust). Ships the sheleg-design skill, the architecture reference, the motion doctrine, the Figma and Claude Design bridges, AI-surface patterns, style packs with ready-made token CSS, and the /sheleg-design command, and awning (a white forecourt where the accent is black and no hue reaches the chrome at all, a pill whose radius is a declared component token, one variable grotesque at 420/550 with no 700, and a single three-layer shadow, for commerce and platform front doors), and proscenium (a white field carrying two cool acts and one deep indigo act at the middle, an electric violet filling a control that stays nearly square at 4px against cards at 16, one family at nine weights, and a framed product panel the fold cuts off, for product-led marketing front doors whose argument is a demonstration), and bulletin (warm cream paper cut by flat pastel bands, every card and control a 1px ink outline standing on a hard zero-blur ink offset it travels into when pressed, a display face at 800 inside controls and 700 in the headline, and no tracking at any size, for front doors whose argument is breadth), and nameplate (a cool near-white slab under a page that is square on 87% of its elements, where the one round shape is reserved for a white 1px-bordered pill carrying somebody else's publication name as type, one family with the body at weight 500, and two uppercase registers tracked 0.06em and 0.175em, for pages whose argument is that named third parties will vouch for you: press placement, trust marks, certification and review aggregation), and rimlight (a white field with a cool grey act separator and one near-black act, a grotesque for every sentence and a monospace for every piece of chrome, square on 84% of its elements and tracked negative at every size, whose only elevation is a sixteen-layer coloured light rig — six layers lit and ten held at alpha 0, thrown from below-left — for a studio's own front door and the pages that sell what it makes), and onionskin (a white technical sheet at 96.5% zero radius — the squarest page in the library — where two bases do all the work and everything quiet is one of them at an alpha: text dims through the ink, structure dims through a navy that is never a word, over a dot grid with dashed hairlines and three faces at an 11px working size, for developer and AI infrastructure whose front page is a working document), and deskmate, test-drive, surveyor (a warm beige working day lit from one source above the top edge, where a single four-stop ramp — peach, lilac, violet, deep navy — washes the field, fills a panel and fills one word of a heading, everything a hand touches is a pill at 56px and everything else a 32px slab, elevation is a field step with two shadows on a 10,211px page, and the set piece is a framed transcript whose quoted chat client keeps its own face, ink and status colours under a --quoted-* namespace, for products sold as a colleague rather than a tool: AI employees and chat-native agents).",
-  "version": "1.54.0",
+  "version": "1.54.1",
   "author": {
     "name": "ssheleg",
     "url": "https://x.com/sshlg93"

package/plugins/sheleg-design/skills/sheleg-design/SKILL.md

@@ -3,7 +3,7 @@ name: sheleg-design
 description: Use when deciding how something LOOKS or MOVES — cinematic landing pages and hero sections, particle/WebGL backgrounds, scroll-linked or scrubbed motion, layers that drift, dashboards, admin or internal tools, mobile screens, chat or agent interfaces, tokens, themes, palettes, typography and the Figma border. Triggers include "design a landing" / "дизайн лендинга", "build a landing page" / "сделай лендинг", "scroll animation" / "скролл-анимация", "dashboard style" / "стиль дашборда", "design tokens, style pack" / "дизайн-токены", "light/dark theme" / "светлая/тёмная тема", "figma variables" / "переменные фигмы, фигма в код", "mobile screen" / "мобильный экран", "palette, colors" / "палитра, цвета", "typography, font" / "типографика, шрифт", "how it looks, make it prettier" / "выглядит, красиво, красивее", "visual reference" / "визуальные референсы", "investor deck" / "презентация". Not for structure, copy or backend behavior.
 license: MIT
 metadata:
-  version: 1.54.0
+  version: 1.54.1
 ---
 
 # SHELEG Design