sshlg-skills 0.22.2 → 0.23.0

package/CHANGELOG.md

@@ -1,5 +1,76 @@
 # Changelog
 
+## v0.23.0 — 2026-08-06
+
+### Fixed
+
+- **The second `routers` run destroyed the block the first one wrote.** The
+  block's own heading is `## Роутинг работы — семья ssheleg`; migration's
+  pattern for the hand-written rule is `## Роутинг работы`. On the second run
+  it took the block's heading for a hand-written rule and cut from there to the
+  next H1 or end of file — carrying the closing sentinel, and every rule the
+  operator kept below it, out of `~/.claude/CLAUDE.md`. The command then
+  reported the block malformed and refused to touch it again. Shipped in
+  v0.22.0 and reproduced against it.
+
+  It hid because idempotence was proven on `upsert`, which is pure, while the
+  damage happened one layer up in the command that runs migration first. On
+  this machine it cost nothing only because the block had never been written.
+  Migration now never reads inside the managed block, and **skips past it
+  rather than stopping at it**, so a hand-written rule *below* the block is
+  still found.
+
+- **A section ended at the next `## `, and an `# ` heading did not stop it.**
+  In the operator's real file the section to be cut is followed by exactly
+  that, so the cut ran to end of file. A `### ` subheading still does not end
+  its parent.
+
+- **`npm test` did not exist.** Eight suites and two validators ran only in
+  CI; locally the standard command failed with `Missing script: "test"`.
+
+### Added
+
+- **Eight routers, declared once each.** A router used to be written twice —
+  its text in `router-texts.js`, its table row in `routers.js` — with nothing
+  comparing the halves. One registry entry now carries what a router is: the
+  members it needs, its two table cells, its text. Key order is table order.
+  - New: `sheleg-design` (how it looks and moves), `make-skill` (how the skill
+    itself is built), `agent-sync` (who is holding this file).
+  - New and backed by **no skill at all**: `seo-llmo` and `evidence-docs` are
+    rules rather than tools, so they hold whether or not anything is
+    installed. That is why a router stopped being a property of a member.
+  - `task-pipeline`'s text now claims **planning** as its own stages 2–4,
+    which retires the competing planning rule beside it: a superseded heading
+    is removed only when the router replacing it is actually written, and its
+    body is kept rather than dropped.
+- **`sshlg-skills config`** — every router on or off by name. Switching one
+  off removes its section and its table row; switching it back on restores the
+  **exact bytes**, including wording of the operator's that migration had
+  moved in. `~/.claude/CLAUDE.md` has no version control behind it, so a
+  toggle that regenerated the packaged text would erase a person's words
+  silently.
+  - Settings store **deviations only**, so a router added in a later release
+    arrives switched on rather than silently off.
+- Sections are kept in registry order, so the block's reading order cannot
+  drift from the table it renders.
+
+### Changed
+
+- `npm test` is the one entry point, and it **discovers** `test/*_test.js`
+  instead of listing them. An empty run fails rather than reporting green, and
+  `validate.py` fails if CI stops calling `npm test` — a guard that shipped
+  wrong the first time (it matched the substring anywhere in the workflow,
+  which the negative self-tests satisfy) and was tightened after being planted
+  and watched.
+- `node --check` on the launcher is replaced by running the launcher, per the
+  retrospective's first standing instruction.
+- **179 fixtures across eight suites, up from 75 across five** — both numbers
+  counted by running the suites, not carried over. The previous release notes
+  claimed 71 and its acceptance record claimed 74; the count at that commit is
+  75. Three numbers, one measurement, and the two that were restated are the
+  two that were wrong. That is the `evidence-docs` router's entire argument,
+  arriving from this repository's own paperwork.
+
 ## v0.22.2 — 2026-08-05
 
 ### Fixed

package/README.md

@@ -117,6 +117,59 @@ installed, so it takes no `--agent`.
 > plugin. The launcher passes the agent list explicitly and prunes those copies
 > after every run.
 
+## Routing — making the family engage by default
+
+A skill's `description` influences whether a model reaches for it. It does not
+oblige. So the pack writes a **managed routing block** into your global agent
+instructions (`~/.claude/CLAUDE.md`, `~/.codex/AGENTS.md`), and the rules
+engage in every project instead of only when someone remembers to ask.
+
+```bash
+npx sshlg-skills routers              # write it (asks once)
+npx sshlg-skills routers --dry-run    # show the diff, change nothing
+npx sshlg-skills routers --update     # refresh an existing block, never create one
+```
+
+Eight routers, and they are **different axes rather than competing
+priorities** — a landing page passes several, an internal script passes none:
+
+| Router | Answers | When | Needs installed |
+|---|---|---|---|
+| `super-ux` | what the interface must do | there is user-facing behaviour | super-ux |
+| `sheleg-design` | how it looks and moves | there is a visual layer | sheleg-design |
+| `copywriting` | how it sounds | text a product user will read | super-ux |
+| `seo-llmo` | whether a machine will find it | a logged-out reader can see it | — |
+| `evidence-docs` | what proves it | something is stated as true | — |
+| `task-pipeline` | how the change reaches the repo | the repository changes | task-pipeline |
+| `make-skill` | how the skill itself is built | a skill or plugin changes shape | make-skill |
+| `agent-sync` | who is holding this file | the project has coordination on | agent-sync |
+
+Two of them need no skill behind them. `seo-llmo` and `evidence-docs` are
+rules, not tools, so they hold whether or not anything is installed.
+
+**Your own wording wins.** Where you already wrote a rule by hand, migration
+moves *your* text in verbatim — asides included — and the packaged default is
+used only for a router you never wrote.
+
+**Consent is asked once**, recorded, and never asked again. Declining leaves an
+`SSHLG:ROUTERS:OPTOUT` marker, which the block's own header names as the way
+out and which survives a reinstall and a restored dotfile. Everything outside
+the sentinels is preserved byte for byte.
+
+### Turning routers off
+
+```bash
+npx sshlg-skills config                                  # what this machine wants
+npx sshlg-skills config set routers.seo-llmo off
+npx sshlg-skills routers --update                        # apply it
+```
+
+Switching a router off **removes its section** and drops its table row.
+Switching it back on restores the exact bytes that were there — including
+wording of yours that migration had moved in. Settings live in
+`~/.sshlg-skills/config.json` (mode 0600) and store deviations only, so a
+router added in a later release arrives switched on rather than silently off.
+
 ## Other commands
 
 ```bash
@@ -136,8 +189,14 @@ get wrong: one channel per agent, exact agent ids, repeated `--agent` flags, ful
 ```
 skills.json                  registry — repos, plugin ids, skill names, pins
 skills/*                     the six skills as pinned git submodules
-bin/sshlg-skills.js          the launcher (install / update / list / agents)
+bin/sshlg-skills.js          the launcher (install / update / routers / config / list / agents)
+lib/routers-registry.js      the eight routers — text, table row and required members, in one entry
+lib/routers.js               block parsing and rendering; touches no file, by construction
+lib/apply.js                 the only module that writes to the instruction files
+lib/migrate.js               moves hand-written rules in; never reads inside the block
+lib/config.js, lib/store.js  the pack's settings, and the 0600 discipline they share
 install.sh                   POSIX fallback (macOS/Linux; use npx on Windows)
+test/run.js                  `npm test` — the validator, then every discovered suite
 test/validate.py             registry / submodules / version validation
 .github/workflows            validation on push and PR + tag-driven release
 ```
@@ -150,13 +209,22 @@ commit installs exactly the skill versions that commit was tested with.
 ## Development
 
 ```bash
-python3 test/validate.py
+npm test
 ```
 
+One entry point: it runs the structural validator, then **discovers** every
+`test/*_test.js` rather than listing them — a list would live in
+`package.json` and in the workflow at once, and drift the first time a suite
+was added to one side. An empty run fails rather than reporting green, and
+`validate.py` fails if CI stops calling `npm test`.
+
 ```bash
-node --check bin/sshlg-skills.js
+python3 test/check_pins.py
 ```
 
+Kept out of `npm test` on purpose: it queries the npm registry, and the rest
+must work offline.
+
 Releases are tag-driven: bump `skills.json`, `package.json` and the top
 `CHANGELOG.md` entry together, tag `vX.Y.Z`, and the release workflow cuts the
 GitHub release from the matching changelog section.

package/bin/sshlg-skills.js

@@ -92,6 +92,9 @@ Skills: ${SKILLS.map(s => s.name).join(', ')}
 Usage:
   npx sshlg-skills install [--agent a,b | --all] [--no-claude] [--claude-only]
   npx sshlg-skills update  [--agent a,b | --all] [--no-claude] [--claude-only] [--bump-pins]
+  npx sshlg-skills routers [--member <name>] [--update] [--dry-run]
+  npx sshlg-skills config  [list]
+  npx sshlg-skills config  set routers.<name> on|off
   npx sshlg-skills list
   npx sshlg-skills agents
 
@@ -208,7 +211,8 @@ function cmdAgents() {
  * worse than no table.
  */
 function cmdRouters(f) {
-  const routersLib = require('../lib/router-texts.js');
+  const registry = require('../lib/routers-registry.js');
+  const configLib = require('../lib/config.js');
   const apply = require('../lib/apply.js');
   const consent = require('../lib/consent.js');
   const migrate = require('../lib/migrate.js');
@@ -216,9 +220,31 @@ function cmdRouters(f) {
   const path = require('path');
   const home = process.env.HOME || require('os').homedir();
 
-  const members = f.member ? [f.member] : manifest.skills.map((s) => s.name);
-  const packaged = routersLib.forMembers(members);
-  if (!Object.keys(packaged).length) {
+  // The settings decide which routers this machine wants; the registry decides
+  // which ones it may speak for. With --member, only that member's own — a
+  // lone installer speaks for itself and never for the family's rules.
+  const config = configLib.readConfig(home);
+  const isEnabled = (n) => configLib.isEnabled(config, n);
+  const scopeOpts = f.member
+    ? { member: f.member, isEnabled }
+    : { installed: manifest.skills.map((s) => s.name), isEnabled };
+
+  const packaged = registry.resolve(scopeOpts);
+  const remove = registry.disabled(scopeOpts);
+
+  // A stashed body outranks the packaged text: it is what was in the block
+  // before the router was switched off, which on this machine may be the
+  // operator's own wording that migration moved in.
+  const restored = [];
+  for (const name of Object.keys(packaged)) {
+    const stashed = configLib.stashGet(config, name);
+    if (stashed !== undefined) {
+      packaged[name] = stashed;
+      restored.push(name);
+    }
+  }
+
+  if (!Object.keys(packaged).length && !remove.length) {
     log('routers: ни один установленный участник не даёт роутера — нечего писать');
     return true;
   }
@@ -243,6 +269,8 @@ function cmdRouters(f) {
 
   // Hand-written rules win over the packaged text, so migration runs first and
   // its result is what gets written.
+  const superseded = {};
+  const sources = {};
   for (const t of apply.TARGETS) {
     const file = path.join(home, t.dir, t.file);
     if (!fs.existsSync(file)) continue;
@@ -251,18 +279,103 @@ function cmdRouters(f) {
     if (moved.text !== src && decision === 'yes' && !f.dryRun) {
       fs.writeFileSync(file, moved.text, 'utf8');
     }
+    // Hand the migrated text on rather than letting apply re-read the file:
+    // on a dry run nothing was written, and re-reading would preview the
+    // additions without the removals that come with them.
+    sources[file] = decision === 'yes' ? moved.text : src;
     Object.assign(packaged, moved.routers);
+    Object.assign(superseded, moved.superseded);
+  }
+
+  const res = apply.apply({
+    home, mode, consent: decision, routers: packaged,
+    remove, sources, dryRun: f.dryRun, log,
+  });
+
+  // Whatever left the block is kept, not dropped. A switch that loses the
+  // operator's wording on the way out is a switch nobody dares use twice, and
+  // the file it was taken from has no version control behind it.
+  if (!f.dryRun && decision === 'yes') {
+    for (const r of res.targets) {
+      for (const [name, body] of Object.entries(r.removed || {})) {
+        configLib.stashSet(home, name, body);
+      }
+    }
+    for (const [id, body] of Object.entries(superseded)) {
+      configLib.stashSet(home, 'superseded:' + id, body);
+    }
+    // A restored section is live again, so its copy in the settings is now a
+    // stale duplicate of text that has a home.
+    for (const name of restored) configLib.stashClear(home, name);
   }
 
-  const res = apply.apply({ home, mode, consent: decision, routers: packaged, dryRun: f.dryRun, log });
   for (const r of res.targets) {
     if (r.action === 'agent-absent') continue;
     log(`routers: ${r.file} — ${r.action}`);
     if (r.diff) log(r.diff);
   }
+  if (remove.length) log(`routers: выключены настройкой — ${remove.join(', ')}`);
+  for (const id of Object.keys(superseded)) {
+    log(`routers: вытеснен рукописный раздел "${id}" — тело сохранено в ${configLib.configPath(home)}`);
+  }
   return true;
 }
 
+/**
+ * `config` — the pack's settings.
+ *
+ * Kept out of `parseFlags` on purpose: its arguments are positional, and that
+ * parser exits on anything that is not a known flag.
+ */
+function cmdConfig(argv) {
+  const registry = require('../lib/routers-registry.js');
+  const configLib = require('../lib/config.js');
+  const home = process.env.HOME || require('os').homedir();
+  const [sub, key, value] = argv;
+
+  if (!sub || sub === 'list') {
+    const config = configLib.readConfig(home);
+    log(`Настройки пака — ${configLib.configPath(home)}\n`);
+    for (const name of registry.order()) {
+      log(`  routers.${name.padEnd(16)} ${configLib.isEnabled(config, name) ? 'on' : 'off'}`);
+    }
+    log('\nПоменять:  npx sshlg-skills config set routers.<имя> on|off');
+    return 0;
+  }
+
+  if (sub !== 'set') {
+    log(`config: неизвестная подкоманда "${sub}" — есть list и set`);
+    return 2;
+  }
+
+  if (!key || key.indexOf('routers.') !== 0) {
+    log('config set: ключ должен начинаться с "routers." — других разделов пока нет');
+    return 2;
+  }
+
+  const name = key.slice('routers.'.length);
+  if (!Object.prototype.hasOwnProperty.call(registry.REGISTRY, name)) {
+    log(`config set: роутера "${name}" нет. Валидные имена:`);
+    for (const n of registry.order()) log(`  routers.${n}`);
+    return 2;
+  }
+
+  if (configLib.STATES.indexOf(value) === -1) {
+    log(`config set: состояние должно быть on или off — получено "${value === undefined ? '' : value}"`);
+    return 2;
+  }
+
+  const was = configLib.isEnabled(configLib.readConfig(home), name) ? 'on' : 'off';
+  if (was === value) {
+    log(`routers.${name}: ${value} (без изменений)`);
+    return 0;
+  }
+  configLib.setRouter(home, name, value);
+  log(`routers.${name}: ${was} → ${value}`);
+  log('Запусти `npx sshlg-skills routers --update`, чтобы применить.');
+  return 0;
+}
+
 function readLineSync() {
   const fs = require('fs');
   const buf = Buffer.alloc(1024);
@@ -279,6 +392,9 @@ function main(argv) {
   if (!cmd || cmd === 'help' || cmd === '--help' || cmd === '-h') { usage(); return 0; }
   if (cmd === 'list' || cmd === 'ls') { cmdList(); return 0; }
   if (cmd === 'agents') { cmdAgents(); return 0; }
+  // Before parseFlags: `config` takes positional arguments, and that parser
+  // exits on any token it does not recognise as a flag.
+  if (cmd === 'config') return cmdConfig(rest);
   const f = parseFlags(rest);
   if (cmd === 'install' || cmd === 'i') return cmdInstall(f) ? 0 : 1;
   if (cmd === 'update' || cmd === 'up') return cmdUpdate(f) ? 0 : 1;

package/lib/apply.js

@@ -53,9 +53,30 @@ function writeOptOut(file) {
 }
 
 
+/**
+ * `opts.sources[file]` is the text to work FROM, when the caller already has
+ * a version the disk does not.
+ *
+ * Migration runs before this module and, on a dry run, deliberately does not
+ * write. Re-reading the file then showed a preview of the block being added
+ * with none of the hand-written sections being removed — +361 lines against
+ * -1, where the real run removes about a hundred and thirty. A preview that
+ * under-reports its own removals is worse than no preview: it is read as
+ * permission.
+ *
+ * Passing the source in also makes the dry and the wet path compute from the
+ * same bytes, rather than agreeing because the wet one happened to write
+ * first.
+ */
 function applyOne(file, routers, opts) {
   const exists = fs.existsSync(file);
-  const before = exists ? fs.readFileSync(file, 'utf8') : '';
+  // Two different texts, and conflating them is the bug this exists to fix.
+  // `onDisk` is what the operator has right now and the only honest baseline
+  // for a diff. `before` is what to compute from — the migrated text on a dry
+  // run, where migration deliberately wrote nothing.
+  const onDisk = exists ? fs.readFileSync(file, 'utf8') : '';
+  const supplied = opts.sources && Object.prototype.hasOwnProperty.call(opts.sources, file);
+  const before = supplied ? opts.sources[file] : onDisk;
   const parsed = R.parse(before);
 
   if (parsed.state === R.STATE.OPTED_OUT) return { file, action: 'opted-out' };
@@ -75,14 +96,17 @@ function applyOne(file, routers, opts) {
     source = before + gap + EMPTY_BLOCK;
   }
 
-  const result = R.upsert(source, routers);
+  const result = R.upsert(source, routers, { remove: opts.remove || [] });
   const next = result.text;
-  if (next === before) return { file, action: 'unchanged' };
+  const removed = result.removed || {};
+  if (next === onDisk) return { file, action: 'unchanged', removed };
 
-  if (opts.dryRun) return { file, action: 'would-write', diff: R.diff(before, next) };
+  if (opts.dryRun) {
+    return { file, action: 'would-write', diff: R.diff(onDisk, next), removed };
+  }
 
   fs.writeFileSync(file, next, 'utf8');
-  return { file, action: exists ? 'updated' : 'created' };
+  return { file, action: exists ? 'updated' : 'created', removed };
 }
 
 /**
@@ -102,6 +126,7 @@ function apply(opts) {
       continue;
     }
     const record = applyOne(path.join(dir, t.file), opts.routers || {}, opts);
+    record.agent = t.agent;
     targets.push(record);
 
     if (record.action === 'malformed') {

package/lib/config.js

@@ -0,0 +1,81 @@
+'use strict';
+/**
+ * The pack's settings — which routers this machine wants.
+ *
+ * Shape:
+ *
+ *   {
+ *     "routers": { "seo-llmo": "off" },
+ *     "stash":   { "task-pipeline": "…the section body that was removed…" }
+ *   }
+ *
+ * **Only deviations are stored.** A router absent from `routers` is on. That
+ * is what lets a new family member's router appear on its own: a file listing
+ * every router as "on" would freeze today's list, and the next release's
+ * router would arrive switched off by a file nobody remembered writing.
+ *
+ * **The stash is not a cache.** Migration moves the operator's own wording
+ * into the block, asides and all. Switching a router off and back on would
+ * otherwise return the packaged default, silently replacing text a person
+ * wrote — against `~/.claude/CLAUDE.md`, which is not under version control
+ * and has nothing to roll back to.
+ */
+
+const path = require('path');
+const store = require('./store.js');
+
+const STATES = ['on', 'off'];
+
+function configPath(home) {
+  return path.join(home, '.sshlg-skills', 'config.json');
+}
+
+/** The settings, or `{}`. A file we cannot read falls back to the defaults. */
+function readConfig(home) {
+  return store.readJson(configPath(home));
+}
+
+/** Absent means on. Only an explicit "off" disables a router. */
+function isEnabled(config, name) {
+  const routers = (config && config.routers) || {};
+  return routers[name] !== 'off';
+}
+
+/**
+ * Record a router's state. `on` DELETES the key rather than writing it, so
+ * the file keeps holding deviations only.
+ */
+function setRouter(home, name, state) {
+  if (!STATES.includes(state)) {
+    throw new Error(`state must be one of on, off — got "${state}"`);
+  }
+  const config = readConfig(home);
+  const routers = Object.assign({}, config.routers);
+  if (state === 'off') routers[name] = 'off';
+  else delete routers[name];
+  return store.writeJson(configPath(home), { routers });
+}
+
+function stashGet(config, name) {
+  const stash = (config && config.stash) || {};
+  return Object.prototype.hasOwnProperty.call(stash, name) ? stash[name] : undefined;
+}
+
+function stashSet(home, name, body) {
+  const config = readConfig(home);
+  const stash = Object.assign({}, config.stash);
+  stash[name] = body;
+  return store.writeJson(configPath(home), { stash });
+}
+
+function stashClear(home, name) {
+  const config = readConfig(home);
+  const stash = Object.assign({}, config.stash);
+  delete stash[name];
+  return store.writeJson(configPath(home), { stash });
+}
+
+module.exports = {
+  configPath, readConfig, isEnabled, setRouter,
+  stashGet, stashSet, stashClear, STATES,
+};

package/lib/consent.js

@@ -11,8 +11,8 @@
  * against a temp directory and cannot reach the real state file.
  */
 
-const fs = require('fs');
 const path = require('path');
+const store = require('./store.js');
 
 function statePath(home) {
   return path.join(home, '.sshlg-skills', 'state.json');
@@ -20,25 +20,18 @@ function statePath(home) {
 
 /** The recorded state, or `{}`. A file we cannot parse is not consent. */
 function readState(home) {
-  try {
-    const raw = fs.readFileSync(statePath(home), 'utf8');
-    const parsed = JSON.parse(raw);
-    return parsed && typeof parsed === 'object' ? parsed : {};
-  } catch (e) {
-    return {};
-  }
+  return store.readJson(statePath(home));
 }
 
-/** Merge `patch` into the recorded state. Owner-only, like anything else here. */
+/**
+ * Merge `patch` into the recorded state. Owner-only, like anything else here.
+ *
+ * The reading, the merge and the 0600 now live in `store.js`, shared with the
+ * settings file — one implementation of the permission rule instead of two
+ * that agree today.
+ */
 function writeState(home, patch) {
-  const file = statePath(home);
-  fs.mkdirSync(path.dirname(file), { recursive: true });
-  const next = Object.assign(readState(home), patch);
-  fs.writeFileSync(file, JSON.stringify(next, null, 2) + '\n', { mode: 0o600 });
-  // writeFileSync's mode is subject to umask on create and ignored entirely on
-  // an existing file, so the permission is set rather than requested.
-  fs.chmodSync(file, 0o600);
-  return next;
+  return store.writeJson(statePath(home), patch);
 }
 
 function defaultPrompt() {