sshlg-skills: Instructions file for Claude Code

CLAUDE.md — sshlg-skills

House rules for this repository only. Global doctrine (language, quality bar, ops autonomy, skill routing) already loads from ~/.claude/CLAUDE.md in the same session; repeating it here would create a second source of truth that drifts. What follows is what is true here and nowhere else.

What this repo is

The umbrella of the ssheleg skill family: a zero-dependency Node launcher plus eight skills as pinned git submodules. It ships no doctrine of its own — each member carries its own — but it owns the family's routing block, the one piece of the family that writes into a file the operator owns and did not write.

That last sentence is the whole risk profile. ~/.claude/CLAUDE.md has no version control behind it. Everything below exists because of it.

The gate

npm test          # test/validate.py, then every discovered test/*_test.js

Ratchets live in docs/DOCMAP.md and are counted by running that command, never carried across from a previous edit. python3 test/check_pins.py is deliberately outside it: it queries the npm registry, and npm test must work offline.

Invariants — each one has a check, and the check has been watched failing

• One channel per agent. A plain copy under ~/.claude/skills/<id> shadows the plugin of the same name and serves its frozen version forever. install and update prune those copies after every skills-CLI run.
• An address a live document claims resolves, or the commit does not land. This repository's README is an argument about evidence carrying its own receipt, and it told a reader to run a test:negatives script — task-pipeline's, and Missing script here — beside a convergence file naming a scripts/ check that has never existed in this tree (UM-03, requirement M-07). Name a dead command, never claim it: a document that quotes one as runnable is refused by this guard, correctly, and both repairs above are written that way. Neither was found by reading them; both were found by resolving all 83 addresses in the five live documents at once. test/doc_refs.py extracts and resolves, test/validate.py owns the corpus, and four plants in CI cover the three claim classes plus the empty corpus that would pass everything. The dated records are counted, not gated, and the count prints on every run — their rows cite member repositories and states that were true at a commit, and rewriting those is a thing this repository has already decided against.
• Submodule urls are HTTPS. gh repo create --source . sets an SSH remote and git submodule add inherits it; everything stays green on the machine that has the key and the release smoke test exits 128 everywhere else. test/validate.py refuses a non-HTTPS url, with a negative self-test in CI.
• The pin is the promise. A checkout of any hub commit must install exactly the versions skills.json advertises, so the validator reads the version out of the submodule rather than trusting .gitmodules. Three places move together: skills.json, the submodule pointer, the README table.
• The operator's wording wins — and now says when it has diverged. authored entries take precedence over the packaged text on every run. Since that means a reworded router never arrives, routers reports drift and --adopt is the only path that replaces a person's words, one router at a time, parking what it replaced.
• A guard reads what would RUN, not what a payload contains. The hygiene guard refused any Bash text carrying skills update <member> — including a document quoting it, which blocked a verification-ledger row from being committed. executablePart() now drops heredoc bodies fed to a non-shell and whole-line comments, and keeps everything else: a bash <<EOF body still runs, and quoted strings are still read, because bash -c '…' is a real invocation. Closing the false positive turned up the matching bypass — bareName kept the trailing quote, so a genuine quoted invocation had been passing untouched.
• A guard decides in a pure module; the hook only moves bytes. Every refusal this pack can make is a function of a payload (lib/guard.js, lib/hygiene.js, lib/repogate.js), fixtured without a HOME, and the filesystem appears only where a backup is actually taken. Nothing depends on a hook entry's if filter: the reference states it is best-effort and fails open on a command it cannot parse, so a guard resting on it ships with a documented bypass.
• A hook fails silent, and a refusal names its remedy. A guard that throws breaks every turn in every session, including sessions of packs that never asked for this one; a refusal with no next step is how an operator learns to switch a hook off. Both are asserted in test/hooks_e2e_test.js, which runs the real scripts as processes.