skilltrigger 0.0.0-stage → 0.0.2

package/CHANGELOG.md

@@ -0,0 +1,86 @@
+# Changelog
+
+All notable changes to skilltrigger. The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/);
+versions follow [SemVer](https://semver.org/). Items reference their `ST-n` backlog id.
+
+## [Unreleased]
+
+## [0.0.2] — 2026-10-01
+
+Tested only against the fake `claude` the tests use, never against a live CLI — the
+first live run is the gate on 0.1.0 (ST-11, ST-12). The first version on npm, published
+by hand so that trusted publishing can be configured (ST-13); it carries 0.0.1, which was
+never released, and the entries below.
+
+### Added
+- The report records what `compare` needs to tell two environments apart: the roster's
+  members beside its counts, each as the first 12 hex digits of its name's SHA-256 — a
+  roster names private skills, and a report is meant to be shared; the model each run's `init` event
+  reported, per run and counted in `runModels`; and a count of what the inherited
+  environment contributed — memory files for the temporary project and for the user,
+  hooks configured, MCP servers in the `init` event — never their contents, paths or
+  names (ST-20).
+- A re-enable reminder. The toggles the conflict gate prints are remembered in
+  `.skilltrigger-toggles` under the `--out` directory, never under `~/.claude`; every
+  `preflight` that sees such a plugin still disabled, and the end of every `run`, prints
+  its `claude plugin enable …` command, until a preflight sees it enabled again or
+  uninstalled. `preflight` takes `--out` for it, defaulting to `./skilltrigger-results`
+  as `run` does. Nothing is enabled or disabled by skilltrigger itself (ST-21).
+
+### Changed
+- The backlog check, the roadmap, the issue sync and the release-drift check are
+  [backlogsync](https://github.com/Allan-Nava/backlogsync), pinned by commit;
+  `scripts/backlog.mjs` and its test are gone, and `npm run roadmap` regenerates
+  `ROADMAP.md` (ST-22).
+- `compare` warns when roster members differ, counting the members added and removed by hash, not
+  only when the counts differ; and when the models the runs reported or the inherited
+  environment's counts differ. Reports without the new fields compare as before (ST-20).
+
+### Fixed
+- A verdict no longer survives losing whole queries. The 10% rule counts runs, so two
+  positive queries could lose every run to timeouts or errors and the report still gave
+  a verdict on a smaller positives total. A query that was run and measured nothing is
+  now no verdict, exit 3, with the lost queries named in the headline and recorded as
+  `lostQueries`; a query that lost some but not all of its runs keeps the verdict and is
+  flagged, in `partialQueries`, in its row and under the table (ST-19).
+- The conflict gate no longer passes when it cannot read the plugin list. Output from
+  `claude plugin list --json` in a shape the parser does not know used to read as zero
+  plugins and the gate said `ok` with nothing checked; it now fails, quoting the first
+  line of what it got, truncated. A valid empty JSON array, or a human-form list that
+  says no plugins are installed, is still zero plugins and passes; the human-form
+  fallback for an older CLI without `--json` stays. `--allow-conflict` lets an
+  unreadable list through as a recorded warning (ST-18).
+- `release.yml` closes only the milestone titled `v<version>`, alone or followed by a
+  space and a subtitle. It matched any title starting with `v<version>`, so a 0.0.2 tag
+  could have closed a `v0.0.20` milestone, and 0.1.1 one called `v0.1.10` (ST-13).
+
+## [0.0.1] — 2026-10-01 — not released
+
+The first version, in the repository only: the gates, the runner, the report and their
+tests against a fake `claude`. Nothing has been measured with a real model yet; the
+first version on npm is 0.1.0, after that measurement (ST-11).
+
+### Added
+- `skilltrigger preflight`: six gates — `cli` (on PATH, version recorded), `auth`
+  (`claude auth status`), `round-trip` (`claude -p "Reply with exactly: pong"` with the
+  chosen model), `conflict` (an enabled plugin or visible skill of the same name; the
+  disable and enable commands printed, never run; `--allow-conflict` records it),
+  `sleep` (`caffeinate -i -s -w <pid>` on macOS, a warning elsewhere) and `roster`
+  (slash commands and skills from the `init` event). Exit 2 on any failure (ST-2 to ST-5).
+- `skilltrigger run`: strictly serial; one temporary project and one stub command per
+  run, removed afterwards; detection from the partial stream events, the process
+  stopped at the decision; four outcomes — `triggered`, `not-triggered`, `timeout`,
+  `error` — with an authentication or API error never scored as a miss, and a run whose
+  `init` event does not list the stub scored as an error (ST-6).
+- The verdict rule: more than 10% of runs timing out or failing is no verdict, exit 3,
+  and the run stops as soon as that share is passed. Reports in JSON and Markdown that
+  carry the queries, the counts and the versions, and no description text, path or stub
+  name (ST-7).
+- `skilltrigger compare`: per query and total differences over the shared queries, a
+  warning when model, CLI version or roster differ, ±1 per query at two runs labelled
+  noise (ST-8).
+- A fake `claude` driven by environment variables, and tests for every gate, every
+  outcome, the no-verdict rule, compare's drift warning and the removal of the
+  temporary project (ST-9).
+- `skilltrigger check`, CI on Node 18/20/22/24, the release workflow over npm trusted
+  publishing, the site, the backlog and its generated roadmap (ST-10).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Allan Nava
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,110 @@
-# Temporary Holding Version
+<p align="center"><img src="https://raw.githubusercontent.com/Allan-Nava/skilltrigger/main/assets/logo.svg" width="72" height="72" alt=""></p>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# skilltrigger — skill trigger rates you can trust
+
+**skilltrigger measures how often a Claude Code skill's `description` makes the model load it** — on prompts that should trigger it and on near-misses that should not — and refuses to report a number it cannot trust. Six things have been seen to turn that measurement into a clean-looking zero that means nothing; each one is a gate it must pass first or a field recorded beside the result.
+
+**Status:** 0.0.2, on npm — an early version that **has not yet been run against a live `claude` CLI**. Every number skilltrigger has produced so far came from the fake `claude` its tests use, and the stream shapes it reads are unconfirmed on a real run. The gate on 0.1.0 is one real measurement: the maintainer runs skilltrigger on the three skills of the [qrspi](https://github.com/Allan-Nava/qrspi) plugin, with their `evals/trigger/*.json` sets, and the result is recorded, dated, beside the 2026-09-18 numbers in qrspi's CONTRIBUTING.
+
+## What it measures
+
+A skill's description sits in the model's context permanently; the model reads it and decides whether to load the skill. Whether a rewrite helps is an empirical question, and the answer is a pair of rates:
+
+- **positives triggered** — of the runs on prompts that should load the skill, how many did;
+- **negatives fired** — of the runs on near-misses that should not, how many loaded it anyway.
+
+Each run is one `claude -p` in a fresh temporary project that holds a single stub command whose frontmatter `description` is the text under test. The stub is **loaded** when the model's first decisive message carries a tool call that names it — `Skill` or `SlashCommand` with the stub's name in its input, or a `Read` of the stub file. A first message that only fetches tool schemas (`ToolSearch`) does not decide; the next one does. Anything else first — a text answer, another tool, another skill — is a run that did **not** trigger. Detection happens on the partial stream events, and the process is stopped at the decision.
+
+Each run ends in one of four outcomes: `triggered`, `not-triggered`, `timeout`, `error`. Only the first two are measurements. A timeout or an error is never counted as "did not trigger", and when more than 10% of the runs are either, there is **no verdict**: the report says so and the command exits 3. The share counts runs, so it is not the only rule: a query that lost *every* run to timeouts or errors is also no verdict, with the lost queries named — otherwise two positives could vanish inside the 10% and the positives total would quietly leave them out. A query that lost some of its runs but not all keeps the verdict, and the report flags it as measured on fewer runs than planned.
+
+## The six traps
+
+Each was hit in practice, with skill-creator's harness, between 2026-09-09 and 2026-09-18. Each produced a number that looked like a result.
+
+1. **Parallel workers.** The old harness injects one stub per worker, all with the same description and names that differ only by a hash. The model invokes whichever stub it likes, and only the worker whose stub was picked counts the hit — so ten workers, the default, measure about a tenth of the true rate. *skilltrigger is strictly serial and has no workers option*; `--workers` is rejected as an unknown option rather than ignored. A detected run ends in seconds; serial is fast enough.
+2. **An installed plugin shadowing the stub.** If a plugin that carries a skill of the same name is enabled, the model loads the real skill and the stub is never seen: the rate reads zero. *The conflict gate* reads `claude plugin list --json`, looks for the skill's `name` among each enabled plugin's skills, and cross-checks the roster the model actually sees for a same-named entry. On a hit it refuses and prints the exact `claude plugin disable …` and `claude plugin enable …` commands, scope included — and runs neither. A list it cannot read is not an empty list: output in a shape it does not know — not a JSON array, not the human form an older CLI prints, not a line saying no plugins are installed — fails the gate with the first line of what it got, because "which plugins are enabled" is then unknown. `--allow-conflict` measures anyway and records in the report that it did. Because a plugin disabled as asked is no longer a conflict, the toggles the gate printed are remembered in a small file, `.skilltrigger-toggles`, under the `--out` directory — never under `~/.claude` — and every `preflight` that sees the plugin still disabled, and the end of every `run`, prints its `claude plugin enable …` command again, until a preflight sees it enabled or uninstalled. Independently, every run checks that the stub is in the roster its `init` event lists; a run where it is not is an `error`.
+3. **An outdated CLI.** An old `claude` answers 400 for a model it does not know, and the old harness scored that as "did not trigger". *The round-trip gate* runs `claude -p "Reply with exactly: pong"` with the chosen `--model` and requires the answer `pong`; the CLI version is recorded in the report, and in every run an API error line is an `error`.
+4. **An expired login.** An expired OAuth session makes every `claude -p` answer "Failed to authenticate", and a harness that discards stderr scores all forty runs as misses: 0/18 positives and 0/22 negatives, which is not a measurement. *The auth gate* requires `claude auth status` to say logged in, and the round trip catches the expired token that `auth status` can miss. In a run, an authentication failure is an `error`, never a miss.
+5. **A machine that sleeps.** Each run has a timeout, and a laptop that sleeps mid-eval turns runs into timeouts — once 5/18 for a description measured 17/18 a week earlier. *The sleep gate* starts `caffeinate -i -s -w <pid>` on macOS, which holds off idle and system sleep until skilltrigger exits; elsewhere it prints a warning and the advice. Timeouts are counted apart, and they count towards the no-verdict rule.
+6. **The skill roster changing the number.** The stub competes with every other description the model can see. A byte-identical description measured 17/18 one week and 10/18 the next because a synced folder had added 24 skills to the machine, from 59 to 83. *The roster gate* reads the `init` event of a stub-less `claude -p --output-format stream-json --verbose` and records how many slash commands and skills the model sees and their names, and `compare` warns when two reports differ in roster — by its members, not only its size — model or CLI version.
+
+## Install
+
+skilltrigger needs Node 18 or later and a logged-in [Claude Code](https://code.claude.com/docs) CLI on `PATH`. It has no runtime dependencies.
+
+From npm, without installing:
+
+```bash
+npx skilltrigger preflight
+```
+
+or installed, so the `skilltrigger` command is on `PATH`:
+
+```bash
+npm install -g skilltrigger
+skilltrigger preflight
+```
+
+From a checkout:
+
+```bash
+git clone https://github.com/Allan-Nava/skilltrigger && cd skilltrigger
+node bin/skilltrigger.mjs preflight
+```
+
+## Usage
+
+```bash
+skilltrigger preflight [--model M] [--skill <dir>] [--out <dir>] [--allow-conflict]
+skilltrigger run --skill <dir> --eval <file> [--runs 2] [--model M] [--timeout 30] \
+                 [--description "<override>"] [--out <dir>] [--allow-conflict]
+skilltrigger compare <a.json> <b.json>
+skilltrigger check
+```
+
+`preflight` runs every gate and prints each as `ok`, `warn`, `fail` or `skip`, with the reason and, for anything not ok, the fix. It exits 2 on any failure. Without `--skill` it has no name to look for, so the conflict gate only lists the enabled plugins. `--out` is where the re-enable reminder is kept (below); it defaults to `./skilltrigger-results`, as for `run`.
+
+`run` runs the preflight first and refuses on a failure, then runs every query `--runs` times (default 2), round-robin, serially, with a `--timeout` in seconds per run (default 30). `--description` measures an override instead of the text in `SKILL.md`, so a rewrite can be tried without editing the skill. Reports go to `--out` (default `./skilltrigger-results`). Exit codes: 0 a verdict, 1 a usage or input error, 2 a failed gate, 3 no verdict.
+
+The eval set is skill-creator's format — a JSON array of `{ "query": string, "should_trigger": boolean }` — and any other field, a `note` for instance, is carried through to the report:
+
+```json
+[
+  { "query": "summarise this session into HANDOFF.md before I clear it", "should_trigger": true },
+  { "query": "why is cache_read_input_tokens 0 on every call", "should_trigger": false, "note": "the neighbouring skill's territory" }
+]
+```
+
+`compare` sets two reports side by side: per query and in total, over the queries both share. It warns first when the model, the models the runs reported, the CLI version, the roster or the inherited environment differ, because the number is a property of the text *and* the roster. Two rosters of the same size with different members are a warning that counts the members added and removed, by hash. Two runs per query resolve to ±1 per query, so a difference of one hit at two runs is labelled noise, and so is a total difference of up to two.
+
+To judge a rewrite, measure the baseline the same day, in the same environment, then the rewrite with `--description`, and compare the two.
+
+## The report
+
+Each run writes `<out>/<date>-<skill>.json` and a Markdown rendering beside it (a second report the same day gets `-2`). It holds the date, the skilltrigger and CLI versions, the model, the model each run's `init` event reported (per run, and counted in `runModels`), the roster — its counts and a hash of each member, sorted — a count of what the inherited environment contributed (memory files for the temporary project and for the user, hooks configured, MCP servers in the `init` event), runs per query, the timeout, the pass threshold (a trigger rate of 0.5) and the no-verdict threshold (10%), each query with every outcome and its hits/runs, and the totals — positives triggered, negatives fired, timeouts and errors counted apart — plus the queries that lost every run (`lostQueries`, which make it no verdict) and those measured on fewer runs than planned (`partialQueries`).
+
+Nothing else is in it: no description text (a byte count and a SHA-256 stand in for it, so `compare` can tell two texts apart), no paths, no command, skill or stub names, no stderr, and of the environment only counts — never a memory file's contents, a hook command or a server name. The roster's members are the commands and skills installed on the machine that measured, private ones included, so each is recorded as the first 12 hex digits of its name's SHA-256: enough for `compare` to see that a member moved, not to say which. A hash hides a name from a reader, not from someone guessing it — a name anyone could guess is still guessable.
+
+## What it never does
+
+- **It never touches `~/.claude`.** Every run happens in its own temporary directory, removed afterwards; nothing is written under the user's configuration, and every `claude -p` gets `--no-session-persistence`, so the runs are not saved as sessions either. The conflict gate reads a plugin's install directory and writes nothing there.
+- **It never runs in parallel.** See the first trap.
+- **It never reports a number through a failed gate.** A failed gate refuses the run; more than 10% of runs timing out or failing is no verdict, and so is a query that lost every run; the run stops as soon as that share is passed, because every further run would be spent on a number that will not be reported.
+- **It never disables or enables a plugin itself.** It prints the commands, and reminds you of the enable command until the plugin is back.
+- It never sends anything anywhere but through the `claude` CLI it is measuring with.
+
+## Design notes
+
+**Why the first decisive message.** A skill is useful when the model loads it before doing the work. A model that goes exploring first and loads the skill three tool calls later has, for the purpose of a description, missed — and an open-ended wait would turn every such run into a timeout. skill-creator stops at the first tool call of any other kind; skilltrigger reads the whole first message, so a `Bash` call listed before the `Skill` call in the same message still counts as a load.
+
+**A known limit of the method.** `claude -p` starts from nothing, so a positive that presupposes session history — "dump the state of this refactor" — measures whether the model loads the skill *before* going to look for the material. In a real session the material is already in context. Annotate such prompts in the eval set rather than dropping them, so the number stays honest about what it covers.
+
+**Why exit 3 is not a failure of the description.** No verdict means the environment broke, not that the text is bad. The report is still written, so the outcomes can be read, and it says at the top that they are not a measurement.
+
+## Prior art
+
+The mechanism — a stub command carrying the description, `claude -p --output-format stream-json --include-partial-messages`, and early detection from the stream events — comes from `scripts/run_eval.py` in the `skill-creator` skill of [Anthropic's skills repository](https://github.com/anthropics/skills), Apache-2.0. skilltrigger is a separate implementation that copies no code from it, reads the same eval-set format, and adds the gates, the four outcomes and the no-verdict rule. The six traps are documented, with the numbers above, in [qrspi's CONTRIBUTING](https://github.com/Allan-Nava/qrspi/blob/main/CONTRIBUTING.md).
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/bin/lib/args.mjs

@@ -0,0 +1,37 @@
+// A small argument parser: `util.parseArgs` arrived in Node 18.3 and the floor is 18.0.
+//
+// spec: { name: 'string' | 'boolean' }. Unknown options are errors, not ignored — a
+// `--workers 4` that was silently dropped would look like it had been honoured.
+
+export class UsageError extends Error {}
+
+export function parseArgs(argv, spec) {
+  const opts = {}
+  const positional = []
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (!a.startsWith('--')) {
+      positional.push(a)
+      continue
+    }
+    let [name, inline] = a.slice(2).split(/=(.*)/s)
+    const type = spec[name]
+    if (!type) throw new UsageError(`unknown option --${name}`)
+    if (type === 'boolean') {
+      if (inline !== undefined) throw new UsageError(`--${name} takes no value`)
+      opts[name] = true
+      continue
+    }
+    const value = inline ?? argv[++i]
+    if (value === undefined || (inline === undefined && value.startsWith('--'))) throw new UsageError(`--${name} needs a value`)
+    opts[name] = value
+  }
+  return { opts, positional }
+}
+
+export function number(opts, name, { fallback, min, integer = false }) {
+  if (opts[name] === undefined) return fallback
+  const n = Number(opts[name])
+  if (!Number.isFinite(n) || n < min || (integer && !Number.isInteger(n))) throw new UsageError(`--${name} must be ${integer ? 'an integer' : 'a number'} of at least ${min}, got "${opts[name]}"`)
+  return n
+}

package/bin/lib/changelog.mjs

@@ -0,0 +1,37 @@
+// The CHANGELOG, read. Two pure functions: the section a release's notes open
+// with, and the rule that a Breaking entry is the first one under its heading — so the
+// line an upgrader most needs is the first line they read, in the file and in the notes.
+// No filesystem here; `check` and `scripts/release-notes.mjs` pass the text in.
+
+const esc = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+
+// The body of `## [version] — date`: everything after its heading line up to the next
+// `## [`, trimmed; null when the version has no section. A prefix is not a match
+// ("0.2" does not find "0.2.0").
+export function changelogSection(text, version) {
+  const lines = String(text).split('\n')
+  const start = lines.findIndex((l) => new RegExp(`^## \\[${esc(version)}\\](?:\\s|$)`).test(l))
+  if (start < 0) return null
+  let end = lines.findIndex((l, i) => i > start && l.startsWith('## ['))
+  if (end < 0) end = lines.length
+  return lines.slice(start + 1, end).join('\n').trim()
+}
+
+// Every `### Heading` block, in every `## [...]` section, whose Breaking entry (a bullet
+// starting `- **Breaking`) is not its first bullet: [{ section, heading }].
+export function breakingOutOfPlace(text) {
+  const out = []
+  let section = null
+  let heading = null
+  let bullets = 0
+  for (const line of String(text).split('\n')) {
+    const s = line.match(/^## \[([^\]]+)\]/)
+    if (s) { section = s[1]; heading = null; bullets = 0; continue }
+    const h = line.match(/^### (.+?)\s*$/)
+    if (h) { heading = h[1]; bullets = 0; continue }
+    if (!section || !heading || !line.startsWith('- ')) continue
+    bullets++
+    if (bullets > 1 && line.startsWith('- **Breaking')) out.push({ section, heading })
+  }
+  return out
+}

package/bin/lib/check.mjs

@@ -0,0 +1,106 @@
+// `skilltrigger check` — the repository's own invariants, run by `npm test`.
+//
+//   - package.json and CHANGELOG.md agree on the version; [Unreleased] exists; a
+//     Breaking entry leads its heading; release.yml builds its notes from the CHANGELOG
+//   - zero runtime dependencies, and package.json#files ships what the CLI needs
+//   - the README names each of the six traps by its phrase (bin/lib/traps.mjs)
+//   - no tracked file carries a home-directory path or an email address
+import { execFileSync } from 'node:child_process'
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs'
+import { join, relative } from 'node:path'
+import { breakingOutOfPlace } from './changelog.mjs'
+import { TRAPS } from './traps.mjs'
+
+// skilltrigger:allow-private-shapes — this file defines the patterns it forbids.
+// A home path: /Users/<name> or /home/<name>, the name a real one (a placeholder in
+// angle brackets does not match). An email: any address but git's SSH user.
+const SHAPES = [
+  [/(?:^|[\s"'`(=:])\/(?:Users|home)\/[A-Za-z0-9._-]+/m, 'a home directory path'],
+  [/\b(?!git@)[A-Za-z0-9._%+-]+@[A-Za-z0-9-]+(?:\.[A-Za-z0-9-]+)*\.[A-Za-z]{2,}\b/, 'an email address'],
+]
+export const ALLOW_SHAPES = 'skilltrigger:allow-private-shapes'
+
+// → ["path:line looks like <kind> …"] — the finding names the file and the kind, never
+// the match: an error message is printed, logged by CI and pasted into issues.
+export function privateFindings(files) {
+  const out = []
+  for (const { path, text } of files) {
+    if (text.includes(ALLOW_SHAPES)) continue
+    for (const [re, what] of SHAPES) {
+      const m = text.match(re)
+      if (!m) continue
+      const line = text.slice(0, m.index + (m[0].startsWith('/') ? 0 : 1)).split('\n').length
+      out.push(`${path}:${line} looks like ${what} — this repository is public`)
+      break
+    }
+  }
+  return out
+}
+
+const SKIP_DIRS = new Set(['.git', 'node_modules', 'dist'])
+const BINARY = /\.(png|jpe?g|gif|ico|webp|woff2?|tgz|gz|zip|pdf)$/i
+
+function* walk(root, dir = root) {
+  for (const name of readdirSync(dir).sort()) {
+    if (SKIP_DIRS.has(name)) continue
+    const p = join(dir, name)
+    const st = statSync(p)
+    if (st.isDirectory()) yield* walk(root, p)
+    else yield relative(root, p)
+  }
+}
+
+// Tracked files plus untracked ones git would add (so a check before the first commit
+// sees the tree); outside a git checkout, the tree walked.
+function trackedFiles(root) {
+  try {
+    const out = execFileSync('git', ['ls-files', '--cached', '--others', '--exclude-standard'], { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] })
+    const top = execFileSync('git', ['rev-parse', '--show-toplevel'], { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim()
+    if (relative(top, root) === '') return out.split('\n').filter(Boolean)
+  } catch {}
+  return [...walk(root)]
+}
+
+export function checkRepo(root) {
+  const errors = []
+  const fail = (m) => errors.push(m)
+  const read = (f) => readFileSync(join(root, f), 'utf8')
+  const has = (f) => existsSync(join(root, f))
+
+  let pkg = {}
+  try {
+    pkg = JSON.parse(read('package.json'))
+  } catch (e) {
+    fail(`package.json: ${e.message}`)
+  }
+  if (pkg.name !== 'skilltrigger') fail('package.json#name must be skilltrigger')
+  if (!/^\d+\.\d+\.\d+$/.test(pkg.version ?? '')) fail(`package.json#version is not x.y.z: ${pkg.version}`)
+  if (pkg.dependencies && Object.keys(pkg.dependencies).length) fail('no runtime dependencies — package.json#dependencies must be empty')
+  for (const f of ['bin', 'README.md', 'CHANGELOG.md', 'LICENSE']) if (!pkg.files?.includes(f)) fail(`package.json#files is missing ${f}`)
+  if (!/^(?:git\+)?https:\/\/github\.com\/Allan-Nava\/skilltrigger(?:\.git)?$/.test(pkg.repository?.url ?? pkg.repository ?? '')) fail('package.json#repository must be the GitHub repository URL')
+
+  if (!has('CHANGELOG.md')) fail('CHANGELOG.md is missing')
+  else {
+    const log = read('CHANGELOG.md')
+    if (!/^## \[Unreleased\]/m.test(log)) fail('CHANGELOG.md needs an [Unreleased] section')
+    if (pkg.version && !log.includes(`## [${pkg.version}]`)) fail(`CHANGELOG.md has no section for ${pkg.version}, the version in package.json`)
+    for (const b of breakingOutOfPlace(log)) fail(`CHANGELOG.md [${b.section}] ### ${b.heading}: a **Breaking** entry must be the first under its heading`)
+  }
+  if (has('.github/workflows/release.yml') && !read('.github/workflows/release.yml').includes('scripts/release-notes.mjs')) fail('release.yml must build the notes from the CHANGELOG with scripts/release-notes.mjs')
+
+  if (!has('README.md')) fail('README.md is missing')
+  else {
+    const readme = read('README.md').toLowerCase()
+    for (const t of TRAPS) if (!readme.includes(t.phrase.toLowerCase())) fail(`README.md must name the trap "${t.phrase}" (bin/lib/traps.mjs)`)
+  }
+
+  const files = []
+  for (const f of trackedFiles(root)) {
+    if (BINARY.test(f) || !existsSync(join(root, f))) continue
+    const st = statSync(join(root, f))
+    if (!st.isFile() || st.size > 4 * 1024 * 1024) continue
+    files.push({ path: f, text: read(f) })
+  }
+  errors.push(...privateFindings(files))
+  return errors
+}

package/bin/lib/claude.mjs

@@ -0,0 +1,106 @@
+// Spawning `claude`. Two shapes: run to completion and collect the output (the
+// gates), or stream newline-delimited JSON and stop the process the moment a caller
+// has what it needs (the round trip, every run).
+//
+// Every spawn gets the environment minus CLAUDECODE, which a parent Claude Code
+// session sets and which makes a nested `claude -p` refuse to start.
+import { spawn } from 'node:child_process'
+import { lineSplitter } from './stream.mjs'
+
+export const claudeBin = (env = process.env) => env.SKILLTRIGGER_CLAUDE || 'claude'
+
+export function childEnv(env = process.env) {
+  const out = { ...env }
+  delete out.CLAUDECODE
+  return out
+}
+
+// Kill the whole group: the CLI starts helpers (MCP servers, a shell) that would
+// otherwise outlive it and hold the temporary directory open.
+function killTree(child) {
+  if (child.exitCode !== null || child.signalCode !== null) return
+  try {
+    process.kill(-child.pid, 'SIGTERM')
+  } catch {
+    child.kill('SIGTERM')
+  }
+  const hard = setTimeout(() => {
+    try {
+      process.kill(-child.pid, 'SIGKILL')
+    } catch {
+      try {
+        child.kill('SIGKILL')
+      } catch {}
+    }
+  }, 2000)
+  hard.unref()
+}
+
+function start(args, { cwd, env }) {
+  return spawn(claudeBin(env), args, { cwd, env: childEnv(env), stdio: ['ignore', 'pipe', 'pipe'], detached: process.platform !== 'win32' })
+}
+
+// → { code, stdout, stderr, timedOut, notFound }
+export function execClaude(args, { cwd = process.cwd(), env = process.env, timeoutMs = 20000 } = {}) {
+  return new Promise((resolve) => {
+    let stdout = ''
+    let stderr = ''
+    let timedOut = false
+    let settled = false
+    const child = start(args, { cwd, env })
+    const finish = (r) => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      resolve(r)
+    }
+    const timer = setTimeout(() => {
+      timedOut = true
+      killTree(child)
+    }, timeoutMs)
+    child.stdout.on('data', (d) => (stdout += d))
+    child.stderr.on('data', (d) => (stderr = (stderr + d).slice(-65536)))
+    child.on('error', (e) => finish({ code: null, stdout, stderr: stderr || e.message, timedOut, notFound: e.code === 'ENOENT' }))
+    child.on('close', (code) => finish({ code, stdout, stderr, timedOut, notFound: false }))
+  })
+}
+
+// onEvent(event) returns a truthy value to stop: the process is killed and that value
+// comes back as `stopped`. → { stopped, code, stderr, timedOut, notFound, ms }
+export function streamClaude(args, { cwd, env = process.env, timeoutMs, onEvent }) {
+  return new Promise((resolve) => {
+    const t0 = Date.now()
+    let stderr = ''
+    let stopped = null
+    let timedOut = false
+    let settled = false
+    const child = start(args, { cwd, env })
+    const finish = (r) => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      resolve({ ...r, ms: Date.now() - t0 })
+    }
+    const timer = setTimeout(() => {
+      if (stopped) return
+      timedOut = true
+      killTree(child)
+    }, timeoutMs)
+    const lines = lineSplitter((ev) => {
+      if (stopped || timedOut) return
+      const r = onEvent(ev)
+      if (r) {
+        stopped = r
+        killTree(child)
+      }
+    })
+    child.stdout.setEncoding('utf8')
+    child.stdout.on('data', (d) => lines.push(d))
+    child.stderr.on('data', (d) => (stderr = (stderr + d).slice(-65536)))
+    child.on('error', (e) => finish({ stopped, code: null, stderr: stderr || e.message, timedOut, notFound: e.code === 'ENOENT' }))
+    child.on('close', (code) => {
+      lines.end()
+      finish({ stopped, code, stderr, timedOut, notFound: false })
+    })
+  })
+}

package/bin/lib/compare.mjs

@@ -0,0 +1,102 @@
+// Two reports side by side. The number is a property of the description AND of the
+// environment it was measured in — the model, the CLI, and above all the roster: the
+// stub competes with every other description the model can see, and one synced
+// folder of 24 skills moved a byte-identical description from 18/18 to 10/18. So a
+// difference in any of the three is printed as a warning before any delta is — the
+// roster by its members as well as its counts, since two rosters of one size can differ
+// (ST-20), and so is a difference in the models the runs reported or in what the
+// inherited environment contributed.
+//
+// Two runs per query resolve to ±1 per query; a difference of one hit at two runs is
+// labelled noise, and so is a total difference of up to two hits.
+
+const rosterSize = (r) => (r?.roster ? r.roster.slashCommands : null)
+const fmtRoster = (r) => (r?.roster ? `${r.roster.slashCommands} slash commands${r.roster.skills == null ? '' : `, ${r.roster.skills} skills`}` : 'unknown')
+
+// Added and removed members, per kind, by hash — the report carries no names. Skipped
+// when either report predates the hashes.
+function memberDiff(a, b) {
+  const parts = []
+  for (const [key, label] of [['commandHashes', 'slash commands'], ['skillHashes', 'skills']]) {
+    const na = a.roster?.[key]
+    const nb = b.roster?.[key]
+    if (!Array.isArray(na) || !Array.isArray(nb)) continue
+    const sa = new Set(na)
+    const sb = new Set(nb)
+    const added = nb.filter((n) => !sa.has(n))
+    const removed = na.filter((n) => !sb.has(n))
+    if (added.length || removed.length) parts.push(`${label}: ${[added.length ? `${added.length} added (${added.join(', ')})` : '', removed.length ? `${removed.length} removed (${removed.join(', ')})` : ''].filter(Boolean).join('; ')}`)
+  }
+  return parts
+}
+
+const sameKeys = (x, y) => JSON.stringify(Object.keys(x).sort()) === JSON.stringify(Object.keys(y).sort())
+
+function environmentDiff(ea, eb) {
+  if (!ea || !eb) return []
+  const out = []
+  const mem = (e) => `${e.memoryFiles?.project}+${e.memoryFiles?.user}`
+  if (mem(ea) !== mem(eb)) out.push(`memory files (project+user) ${mem(ea)} vs ${mem(eb)}`)
+  if (ea.hooks !== eb.hooks) out.push(`hooks ${ea.hooks} vs ${eb.hooks}`)
+  if (ea.mcpServers !== eb.mcpServers) out.push(`MCP servers ${ea.mcpServers} vs ${eb.mcpServers}`)
+  return out
+}
+
+export function compare(a, b) {
+  const warnings = []
+  if (a.model !== b.model) warnings.push(`model differs: ${a.model} vs ${b.model}`)
+  if (a.runModels && b.runModels && Object.keys(a.runModels).length && Object.keys(b.runModels).length && !sameKeys(a.runModels, b.runModels)) {
+    warnings.push(`the models the runs reported differ: ${Object.keys(a.runModels).sort().join(', ')} vs ${Object.keys(b.runModels).sort().join(', ')}`)
+  }
+  if (a.cliVersion !== b.cliVersion) warnings.push(`CLI version differs: ${a.cliVersion} vs ${b.cliVersion}`)
+  if (rosterSize(a) !== rosterSize(b) || a.roster?.skills !== b.roster?.skills) warnings.push(`roster differs: ${fmtRoster(a)} vs ${fmtRoster(b)} — the number is a property of the text and the roster; re-measure the baseline in the same environment before judging a rewrite`)
+  const members = memberDiff(a, b)
+  if (members.length) warnings.push(`roster members differ (a → b) — ${members.join(' · ')}`)
+  const env = environmentDiff(a.environment, b.environment)
+  if (env.length) warnings.push(`inherited environment differs: ${env.join(', ')} — memory files, hooks and MCP servers reach the model too`)
+  for (const [k, r] of [['a', a], ['b', b]]) if (r.verdict !== 'ok') warnings.push(`report ${k} (${r.date}) has no verdict — its counts are not a measurement`)
+  if (a.conflictAllowed || b.conflictAllowed) warnings.push('a report was measured with --allow-conflict — a same-named skill was visible')
+
+  const noiseAt = Math.min(a.runsPerQuery ?? 2, b.runsPerQuery ?? 2) <= 2
+  const byQuery = new Map(b.queries.map((q) => [q.query, q]))
+  const seen = new Set()
+  const rows = []
+  for (const qa of a.queries) {
+    const qb = byQuery.get(qa.query)
+    seen.add(qa.query)
+    if (!qb) {
+      rows.push({ query: qa.query, should_trigger: qa.should_trigger, a: qa, b: null, only: 'a' })
+      continue
+    }
+    const delta = qb.hits - qa.hits
+    rows.push({ query: qa.query, should_trigger: qa.should_trigger, a: qa, b: qb, delta, noise: delta !== 0 && Math.abs(delta) <= 1 && noiseAt })
+  }
+  for (const qb of b.queries) if (!seen.has(qb.query)) rows.push({ query: qb.query, should_trigger: qb.should_trigger, a: null, b: qb, only: 'b' })
+
+  // Totals over the queries both reports share, so a query added on one side does not
+  // pass for a change in the description.
+  const shared = rows.filter((r) => !r.only)
+  const total = (pred) => {
+    const pick = (side) => shared.filter((r) => pred(r.should_trigger)).reduce((acc, r) => ({ hits: acc.hits + r[side].hits, runs: acc.runs + r[side].runs }), { hits: 0, runs: 0 })
+    const ta = pick('a')
+    const tb = pick('b')
+    return { a: ta, b: tb, delta: tb.hits - ta.hits }
+  }
+  const totals = { positives: total((s) => s), negatives: total((s) => !s) }
+
+  const lines = [`skilltrigger compare — ${a.skill} ${a.date} (a) vs ${b.skill} ${b.date} (b)`, '']
+  for (const w of warnings) lines.push(`warning: ${w}`)
+  if (warnings.length) lines.push('')
+  if (a.description?.sha256 && b.description?.sha256) lines.push(a.description.sha256 === b.description.sha256 ? 'description: identical in both' : `description changed: ${a.description.bytes} → ${b.description.bytes} bytes`, '')
+  const sign = (n) => (n > 0 ? `+${n}` : String(n))
+  for (const r of rows) {
+    const tag = r.should_trigger ? 'pos' : 'neg'
+    if (r.only) lines.push(`  ${tag}  only in ${r.only}: ${r[r.only].hits}/${r[r.only].runs}  ${r.query}`)
+    else lines.push(`  ${tag}  ${r.a.hits}/${r.a.runs} → ${r.b.hits}/${r.b.runs}  ${r.delta === 0 ? ' 0' : sign(r.delta)}${r.noise ? ' (noise)' : ''}  ${r.query}`)
+  }
+  lines.push('')
+  const totalNoise = (d) => (d !== 0 && Math.abs(d) <= 2 && noiseAt ? ' (within noise)' : '')
+  lines.push(`positives triggered ${totals.positives.a.hits}/${totals.positives.a.runs} → ${totals.positives.b.hits}/${totals.positives.b.runs} (${sign(totals.positives.delta)})${totalNoise(totals.positives.delta)}`)
+  lines.push(`negatives fired ${totals.negatives.a.hits}/${totals.negatives.a.runs} → ${totals.negatives.b.hits}/${totals.negatives.b.runs} (${sign(totals.negatives.delta)})${totalNoise(totals.negatives.delta)}`)
+  return { warnings, rows, totals, text: lines.join('\n') }
+}