sshlg-skills 0.76.0 → 0.77.0

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # Changelog
 
+## v0.77.0 — closing a false positive found the bypass it was hiding
+
+**B-59: the hygiene guard could not tell a command being run from one being written
+down.** It reads the whole Bash payload, so quoting the forbidden invocation *in a
+document* was refused too — a verification-ledger row blocked its own commit, and the
+sentence had to be split around the guard.
+
+`executablePart()` now removes what cannot execute before matching:
+
+- **A heredoc body fed to something that is not a shell.** `python3 - <<'PY' … PY` and
+  `cat > f <<EOF … EOF` are data.
+- **A whole-line comment.**
+
+And what it keeps is the load-bearing half. **A `bash <<EOF … EOF` body is still read** —
+stripping every heredoc would trade a false positive for a documented bypass. **Quoted
+strings are still read** too, because `bash -c '…'` is a real invocation.
+
+**That last decision is where the actual finding was.** Testing it produced a case the
+guard *should* refuse and did not: `bareName` kept the trailing quote, so `ux-flows'`
+matched no family id and **`bash -c 'npx skills add ux-flows'` passed the guard untouched**
+— verified against `HEAD` before the change, so it had been open the whole time. The row
+asked for relief from an annoyance; the annoyance was hiding a hole.
+
+Both directions are fixtured — 17 → **22** checks — and the real hook was driven as a
+process to confirm it agrees with the pure module. The fixture strings are **assembled at
+runtime** rather than written whole, because a file containing the literal payload is
+itself refused by anything that reads it: the defect demonstrated itself three times
+during the fix, twice blocking the commands that were repairing it, and once making three
+new cases pass for the wrong reason by targeting a member the fixture's manifest does not
+declare.
+
 ## v0.76.0 — a ledger records two different things, and most record only one
 
 **B-62 said five ledger shapes. Measured: ten, across 815 rows.**

package/lib/hygiene.js

@@ -22,6 +22,12 @@
 
 /** Strip an `@version` suffix so `sshlg-skills@latest` is not read as `skills`. */
 function bareName(token) {
+  // Shell quoting is not part of a name. `bash -c 'npx skills update ux-flows'` reaches
+  // this as the token `ux-flows'`, which matched no family id — so a real invocation
+  // wrapped in quotes passed the guard untouched. Found on 2026-08-16 while fixing the
+  // opposite complaint (B-59, a false positive on documented text); the same run turned
+  // up a bypass worth more than the annoyance that started it.
+  token = String(token || '').replace(/^['"]+/, '').replace(/['"]+$/, '');
   return String(token || '').replace(/@.*$/, '').replace(/^.*\//, '');
 }
 
@@ -43,6 +49,62 @@ function isFlag(token) {
  * `claude` exactly where the target would be, and reading it as the target let a
  * real family skill through unguarded. Watched failing in the fixtures.
  */
+/**
+ * The part of a payload that could actually run, with data stripped out.
+ *
+ * B-59: this guard reads the whole command text, so **writing the forbidden string into a
+ * document is refused too**. On 2026-08-16 a verification-ledger row quoting the
+ * diagnostic invocation blocked its own commit, and the sentence had to be split around
+ * the guard. The family's own documents could not quote the command they warn about.
+ *
+ * Two things are removed, and the boundary between them and everything else is the whole
+ * design:
+ *
+ * - **A heredoc body fed to something that is not a shell.** `python3 - <<'PY' … PY` and
+ *   `cat > f <<EOF … EOF` are data. `bash <<EOF … EOF` is a script, so its body is KEPT —
+ *   stripping every heredoc would be a documented bypass, which is worse than the false
+ *   positive it fixes.
+ * - **A whole-line comment.** A line whose first non-space character is `#` does not run.
+ *
+ * **Quoted strings are deliberately NOT stripped.** `bash -c 'npx skills update ux-flows'`
+ * is a real invocation living inside quotes, and a guard that ignored quoted text would
+ * miss it. The false positive that remains — the string in a single-line argument to
+ * `echo` — is the price of not opening that hole, and it is documented rather than fixed.
+ */
+const HEREDOC_SHELLS = new Set(['bash', 'sh', 'zsh', 'dash', 'ksh', 'eval', 'source', '.']);
+
+function executablePart(command) {
+  const lines = String(command || '').split('\n');
+  const out = [];
+  let terminator = null;
+  let dropping = false;
+  for (const line of lines) {
+    if (terminator !== null) {
+      // The terminator may be indented when the heredoc used `<<-`.
+      if (line.trim() === terminator) { terminator = null; dropping = false; continue; }
+      if (dropping) continue;
+      out.push(line);
+      continue;
+    }
+    if (/^\s*#/.test(line)) continue;
+    const here = /<<-?\s*(['"]?)([A-Za-z_][A-Za-z0-9_]*)\1/.exec(line);
+    if (here) {
+      terminator = here[2];
+      // Which command is being fed? The last simple-command word before the `<<`, taken
+      // after the final pipe or `&&` so `foo | python3 - <<EOF` reads as python3.
+      const before = line.slice(0, here.index);
+      const segment = before.split(/\|\||&&|[|;]/).pop();
+      const words = segment.trim().split(/\s+/).filter(Boolean).map(bareName);
+      const cmd = words.find((w) => !w.includes('=')) || '';
+      dropping = !HEREDOC_SHELLS.has(cmd);
+      out.push(before);
+      continue;
+    }
+    out.push(line);
+  }
+  return out.join('\n');
+}
+
 function skillsCli(command) {
   const tokens = String(command || '').split(/\s+/).filter(Boolean);
   for (let i = 0; i < tokens.length; i += 1) {
@@ -83,7 +145,9 @@ const REMEDY = 'npx --yes sshlg-skills@latest update';
  * `~/.claude/skills/`, which is what does the shadowing.
  */
 function bareFamilyInstall(command, ids) {
-  const call = skillsCli(command);
+  // Data first: a heredoc body written by a non-shell, and whole-line comments, cannot
+  // install anything. See `executablePart` for why quoted strings are not stripped.
+  const call = skillsCli(executablePart(command));
   if (!call || !call.args.length) return null;
   if (!['update', 'add', 'install'].includes(call.verb)) return null;
   const target = call.args.find((a) => ids.has(bareName(a)));
@@ -174,6 +238,6 @@ function reapply(snapshot, fresh) {
 }
 
 module.exports = {
-  skillsCli, familyIds, bareFamilyInstall, launcherRunning,
+  skillsCli, familyIds, bareFamilyInstall, launcherRunning, executablePart,
   isObsidianSetup, parseConfig, reapply, bareName, REMEDY,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sshlg-skills",
-  "version": "0.76.0",
+  "version": "0.77.0",
   "description": "One launcher/updater for the ssheleg skill family (super-ux, task-pipeline, agent-sync, make-skill, sheleg-design, seo-aeo-audit, sheleg-dev, agent-stack) across every agent — Claude Code, Cursor, OpenCode, Kilo, Kimi, Hermes, OpenClaw, Codex, and more.",
   "bin": {
     "sshlg-skills": "bin/sshlg-skills.js"