@supersuit/superskill 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+## 0.1.0 (2026-09-28)
+
+- `reference-says-when`: a link from SKILL.md to an instruction file must say when to read it. Long-skill fixes now point at step files (`steps/<step>.md`).
+
+- Length is not a defect. The 500-line `body-lines` failure and the `body-tokens` warning are replaced by `body-size` (info), `rules-above-the-fold`, `navigable` and `no-repeated-paragraphs`, which check what goes wrong in a long skill rather than its length.
+
+First release of the standard ([SPEC.md](SPEC.md) v0.1.0) and its checker.
+
+- `doctor`: scores a skill, a folder of skills, or a plugin as skill / tested / superskill, with
+  the to-do list for the next level. `--level`, `--json`, `--changed`, `--base`,
+  `--baseline-json`.
+- `doctor --run`: runs evals with and without the skill through Claude Code or Codex and writes
+  `evals/results/latest.json`. Prints an estimate and asks before spending calls.
+- `init` (with `--from-session`), `miss`, `fix`, `approve`, `miss import --freedom-ledger`.
+- `collection`: listing budget, cut-off descriptions, overlapping skills, the plugin line.
+- `snippet`: agent-instructions block.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SupersuitUp
+
+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

@@ -0,0 +1,103 @@
+# superskill
+
+Score any agent skill folder as **skill**, **tested**, or **superskill**, and get the exact
+to-do list for the next level. Works on skills for Claude Code, Codex, or any harness that
+reads the [Agent Skills](https://agentskills.io) format. Zero dependencies, Node 20 or later.
+
+A superskill runs on frontier intelligence, is checked against examples you approved, and is
+fixed every time it gets something wrong. [What that means](https://supersuit.wiki/concepts/superskill);
+[the standard](SPEC.md).
+
+## 30 seconds
+
+```bash
+npx @supersuit/superskill doctor ./my-skill
+```
+
+```
+my-skill  level: skill
+  /path/to/my-skill
+  to reach tested:
+    - evals-present: 0 eval cases (need 3)
+      fix: Add real requests to evals/evals.json (`superskill init` writes an example).
+    - triggers-present: trigger set has 0 should-load and 0 should-not (need 10 total, at least 3 of each)
+      fix: Add realistic requests to evals/triggers.json, including near-misses that share words with the skill but need something else.
+
+1 skill: 1 skill. target skill: met
+```
+
+Point it at a folder of skills or a plugin and it scores every one. Exit code 0 means every
+skill met the target level (`--level`, default `skill`), 1 means one did not, 2 means a usage or
+file error. `--json` prints one JSON document and nothing else.
+
+## The levels
+
+1. **skill**: a valid `SKILL.md` (name matches the folder, description of 1024 characters or
+   fewer that says when to use it, hard rules above the compaction fold, headings in long bodies, nothing said twice), references one level deep, no
+   hard-coded machine paths, nothing that reads like a prompt injection.
+2. **tested**: at least three task evals with checks a machine can verify, and a trigger set of
+   at least ten requests, some that should load the skill and some near-misses that should not.
+3. **superskill**: a golden a person approved; no miss open longer than 14 days and every fixed
+   miss guarded by an eval; a recent `--run` on file where the skill beats the same task done
+   without it. "Recent" follows `metadata.cadence` (a weekly skill's proof lasts 30 days).
+
+Every rule and threshold is in [SPEC.md](SPEC.md).
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `superskill doctor <path...>` | Score skills. `--level`, `--json`. |
+| `superskill doctor <path> --changed [--base <ref>] [--baseline-json <file>]` | The update gate: score only skills a change touched, and refuse one whose level dropped against a previous `--json`. For CI or an agent revising a skill in a loop. |
+| `superskill doctor <skill> --run [--harness claude\|codex] [--repeat 3] [--yes]` | Run the evals for real, with and without the skill, and write `evals/results/latest.json`. **The only command that spends model calls**; it prints an estimate and asks first. |
+| `superskill init <skill>` | Add missing `evals/`, `goldens/`, `MISSES.md`. Never overwrites. |
+| `superskill init <skill> --from-session <transcript>` | Turn the session where you did the job by hand into the first eval and a golden candidate (Claude Code `.jsonl`, or any text file as the request). |
+| `superskill miss <skill> "<what happened>" [--expected "..."]` | Log a time the skill got it wrong. |
+| `superskill fix <skill> <miss-id> --eval <id> [--commit <sha>]` | Close a miss. Refuses without an eval that exists. |
+| `superskill approve <skill> <golden>` | A person signs off on a golden. Terminal only, asks for your name, so an agent cannot approve its own output. |
+| `superskill collection <folder...> [--budget <chars>] [--overlap 0.5]` | Listing budget used, descriptions that get cut off, pairs of skills an agent could confuse (with near-miss triggers to add). |
+| `superskill miss import <skill> --freedom-ledger [--ledger <file>]` | Import runs that needed correcting from Freedom's run ledger. |
+| `superskill snippet` | Print a block for `AGENTS.md` / `CLAUDE.md` that teaches any agent these habits. |
+
+Each command takes `--help`.
+
+## The files
+
+A superskill keeps its evidence in its own folder, so the proof moves with it:
+
+```
+my-skill/
+  SKILL.md
+  evals/evals.json          task evals (Anthropic skill-creator format)
+  evals/triggers.json       should / should-not load (skill-creator format)
+  goldens/<id>/             input.md, output.md, APPROVAL.json
+  MISSES.md                 every miss, open or fixed with its eval
+  evals/results/latest.json the last --run
+```
+
+Harnesses ignore folders they do not know, so none of this changes how the skill loads.
+
+## About `--run`
+
+- Claude Code: each run happens in a fresh folder with the skill linked at
+  `.claude/skills/<name>`; the baseline runs with no skill linked and `--disable-slash-commands`.
+- Codex: the skill is linked at `.agents/skills/<name>`. Codex cannot switch skills off, so a
+  copy installed in `~/.agents/skills` can leak into the baseline; move it aside while proving.
+- Machine checks (`contains:`, `regex:`, `file_exists:`) are free. Each plain-language expectation
+  and each golden costs one grader call per run.
+
+## Freedom
+
+Nothing here needs [Freedom](https://getfreedom.wiki). If a skill has Freedom's `HDSOP.md`, the
+doctor shows it as a bonus; `miss import --freedom-ledger` reads Freedom's run ledger as plain
+files. `superskill snippet` gives any agent the same habits with no Freedom installed.
+
+## Releasing
+
+Bump `version` in `package.json`, add a `CHANGELOG.md` entry, commit, then
+`git tag vX.Y.Z && git push origin vX.Y.Z`. `.github/workflows/publish.yml` publishes through npm
+trusted publishing. Never `npm publish` from a laptop.
+
+## License
+
+MIT

package/SPEC.md

@@ -0,0 +1,239 @@
+# The superskill standard
+
+**Version 0.1.0** (2026-09-28). The reference checker is `@supersuit/superskill`; where this
+document and the checker disagree, the checker has a bug.
+
+A **superskill** runs on frontier intelligence, is checked against examples a person approved,
+and is fixed every time it gets something wrong
+([definition](https://supersuit.wiki/concepts/superskill)). This standard turns each clause into
+a file in the skill's own folder, so the evidence travels with the skill wherever it is copied.
+
+## Contents
+
+- [The clauses and their evidence](#the-clauses-and-their-evidence)
+- [Compatibility](#compatibility)
+- [Levels and rules](#levels-and-rules)
+- [File formats](#file-formats)
+- [Collections and plugins](#collections-and-plugins)
+- [Freedom interop](#freedom-interop)
+- [Versioning](#versioning)
+
+## The clauses and their evidence
+
+| The clause | What proves it | Where it lives |
+|---|---|---|
+| A skill at all | A valid `SKILL.md` under the Agent Skills spec, plus the hygiene rules below | `SKILL.md` |
+| Checked against examples you approved | At least one golden: a real input, the output a person said was right, and a record of who approved it and when | `goldens/<id>/` |
+| Fixed every time it gets something wrong | A miss log where every miss is open (recently) or fixed with a regression eval that would catch it again | `MISSES.md` + `evals/evals.json` |
+| Runs on frontier intelligence | Its evals last passed on a current model, recently, and beat the same task run without the skill | `evals/results/latest.json` |
+
+```
+my-skill/
+  SKILL.md
+  references/ scripts/ ...          (as the Agent Skills spec allows)
+  evals/evals.json                  task evals        (level: tested)
+  evals/triggers.json               trigger evals     (level: tested)
+  goldens/<id>/input.md             approved examples (level: superskill)
+  goldens/<id>/output.md
+  goldens/<id>/APPROVAL.json
+  MISSES.md                         miss log          (level: superskill)
+  evals/results/latest.json         last --run        (level: superskill)
+```
+
+## Compatibility
+
+- **A superset of the Agent Skills spec** ([agentskills.io](https://agentskills.io)). Everything
+  beyond `SKILL.md` is optional to that spec, and harnesses ignore folders they do not know, so a
+  superskill loads everywhere a plain skill does.
+- **`evals/evals.json` and `evals/triggers.json` use the formats of Anthropic's skill-creator**
+  (`anthropics/skills`, `skills/skill-creator/references/schemas.md`, read 2026-09-28). Its tools
+  read these files and this checker reads theirs. The checker writes their field names
+  (`expectations`) and also accepts `assertions` on read.
+- **Unknown frontmatter is ignored**, as the spec allows (for example Freedom's `spans_turns` and
+  `analytics`).
+
+## Levels and rules
+
+A skill is at the highest level whose rules, and every lower level's rules, report no `fail`.
+Below `skill` it is `none`. `warn` and `info` never block a level. The doctor lists, for each
+skill, exactly which `fail`s stand between it and the next level.
+
+A line in a bundled file containing `superskill-ignore` is skipped by `no-absolute-paths` and
+`injection-scan`, for a deliberate example.
+
+### Level 1: skill
+
+| Rule | Severity | Threshold |
+|---|---|---|
+| `frontmatter-valid` | fail | `SKILL.md` exists and opens with a `---` fenced YAML block |
+| `name-format` | fail | `name` is 1-64 chars, `^[a-z0-9]+(-[a-z0-9]+)*$` (so no `--`) |
+| `name-matches-folder` | fail | `name` equals the folder name |
+| `name-reserved-words` | fail | `name` contains neither `anthropic` nor `claude` |
+| `description-length` | fail | `description` is 1-1024 characters |
+| `description-has-trigger` | warn | `description` says when to use it (`when`, `trigger`, `for requests`), or `when_to_use` is set |
+| `description-no-xml` | fail | no `<tag>` in `description`, placeholders like `<slug>` included (Anthropic's skill guidance forbids XML tags in the description) |
+| `compatibility-length` | fail | `compatibility`, if present, is at most 500 characters |
+| `metadata-string-map` | fail | `metadata`, if present, maps string keys to string values |
+| `body-size` | info | reports lines and estimated tokens (characters / 4) once the body passes about 5000 tokens. Length alone is never a defect. |
+| `rules-above-the-fold` | warn | in a body past about 5000 tokens, every hard rule (a shouted NEVER, ALWAYS, MUST, DO NOT, REFUSE, or a bolded **Never ...** command, outside code fences) appears in the first 5000 tokens, either there or restated there. After compaction Claude Code keeps only that much of each invoked skill. |
+| `reference-says-when` | warn | every link from SKILL.md to a markdown file sits on a line that says when to read it (before, when, if, for, read ...). Step files (`steps/<step>.md`) are the recommended way to keep a long skill's detail out of the always-loaded body: they are read fresh when the step comes up, so compaction does not lose them. |
+| `navigable` | warn | a body over 300 lines has no run of more than 150 lines without a heading |
+| `no-repeated-paragraphs` | warn | no paragraph of 100+ characters appears twice |
+| `references-one-deep` | fail | a markdown file linked from `SKILL.md` links on to no further local file |
+| `long-reference-toc` | warn | every markdown file over 100 lines (other than `SKILL.md` and Freedom's `HDSOP.md`) has a table of contents in its first 30 lines (a line matching `/contents/i`, or three or more `- [x](#anchor)` lines) |
+| `no-absolute-paths` | fail | no bundled text file (outside `evals/`, `goldens/` and test files such as `tests/`, `test_*.py`, `*.test.mjs`) contains a path starting `/Users/<name>`, `/home/<name>` or `C:\<name>` |
+| `injection-scan` | fail | no instruction file contains an override phrase ("ignore all previous instructions", "disregard the system prompt"), a download piped into a shell (`curl ... \| sh`), a base64-like run of 200+ characters, or an HTML comment that addresses the agent (`<!-- assistant: ...`) or pairs an action (send, read, upload, run...) with a secret or a URL |
+| `workflow-map` | info | a Freedom `HDSOP.md` is present (bonus, never required) |
+
+### Level 2: tested
+
+| Rule | Severity | Threshold |
+|---|---|---|
+| `evals-present` | fail | `evals/evals.json` parses and there are at least 3 cases (each golden with an input and an output counts as one) |
+| `evals-verifiable` | fail | every case in `evals.json` has a prompt and at least one expectation |
+| `triggers-present` | fail | `evals/triggers.json` has at least 10 queries, at least 3 that should load the skill and at least 3 near-misses that should not |
+
+### Level 3: superskill
+
+| Rule | Severity | Threshold |
+|---|---|---|
+| `golden-approved` | fail | at least one golden has an `APPROVAL.json` with non-empty `approved_by` and a valid `approved_at`; info when it was approved against an earlier `SKILL.md` |
+| `misses-log-present` | fail | `MISSES.md` exists (it may have no entries) |
+| `no-stale-open-miss` | fail | no miss has been open more than 14 days |
+| `fixed-miss-has-eval` | fail | every fixed miss names an eval id present in `evals.json` or `goldens/` |
+| `run-evidence` | fail | `evals/results/latest.json` exists and `with_skill.pass_rate` > `without_skill.pass_rate` |
+| `run-fresh` | fail / warn | the last run is younger than the cadence window: `daily` or `weekly` 30 days, `monthly` 60, `quarterly` 120, `yearly` 365, none declared 30 (info). A `yearly` skill always warns to `--run` before its next real use. An unknown cadence warns |
+
+`metadata.cadence` in `SKILL.md` frontmatter declares how often the skill really runs:
+
+```yaml
+metadata:
+  cadence: weekly
+```
+
+## File formats
+
+### `evals/evals.json` (skill-creator)
+
+```json
+{
+  "skill_name": "weekly-status",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Here are my finished tasks: ... Write my weekly status.",
+      "expected_output": "A note grouped by project",
+      "files": ["evals/files/tasks.csv"],
+      "expectations": ["contains:Atlas", "regex:(?i)^## ", "file_exists:out.md", "Every line is in the past tense"]
+    }
+  ]
+}
+```
+
+`id` is an integer or a string (misses and `init --from-session` use strings like `m1`, `s1`).
+`files` are paths relative to the skill, copied into the run folder. An expectation is either a
+machine check or a plain-language statement:
+
+| Form | Passes when |
+|---|---|
+| `contains:<text>` | the output contains `<text>` |
+| `regex:<pattern>` | the output matches (multiline; a leading `(?i)` makes it case-insensitive) |
+| `file_exists:<path>` | the run left `<path>` in its working folder |
+| anything else | a grader call answers `{"pass": true, ...}` |
+
+A bare array of cases is accepted on read, as is `assertions` for `expectations`.
+
+### `evals/triggers.json` (skill-creator)
+
+```json
+[
+  { "query": "write my weekly status from these tasks", "should_trigger": true },
+  { "query": "write a status page for our API uptime", "should_trigger": false }
+]
+```
+
+### `goldens/<id>/`
+
+- `input.md`: the real request.
+- `output.md` (or any other file that is not `input.*` or `APPROVAL.json`): the output a person
+  said was right.
+- `APPROVAL.json`, written only by `superskill approve` at an interactive terminal:
+
+```json
+{ "approved_by": "Ann Example", "approved_at": "2026-09-10T15:00:00.000Z", "skill_sha": "<sha256 of SKILL.md>", "note": "Exactly the shape I send my manager." }
+```
+
+A golden is also an eval: `--run` judges the skill's output for `input.md` against the approved
+output.
+
+### `MISSES.md`
+
+```markdown
+# Misses
+
+## m1 · 2026-09-20 · fixed
+- What happened: A task listed twice showed up twice in the note.
+- Should have: Merged duplicates into one line.
+- Fix: a1b2c3d
+- Eval: m1
+- Source: freedom-ledger inv_2026-09-20T10-00-00Z_ab12   (optional)
+```
+
+Headings are `## <id> · <YYYY-MM-DD> · <open|fixed>`; `|` or `-` also separate. Ids are `m1`,
+`m2`, ... Other headings are ignored.
+
+### `evals/results/latest.json`
+
+Written only by `superskill doctor --run`:
+
+```json
+{
+  "run_at": "2026-09-20T10:00:00.000Z",
+  "harness": "claude",
+  "model": "<model id the harness reported>",
+  "cases": 4,
+  "repeat": 3,
+  "with_skill": { "pass_rate": 1.0, "mean_ms": 21000, "mean_tokens": 4100 },
+  "without_skill": { "pass_rate": 0.33, "mean_ms": 18000, "mean_tokens": 3900 },
+  "per_case": [{ "id": "1", "with_skill": { "runs": 3, "passes": 3 }, "without_skill": { "runs": 3, "passes": 1 }, "failures": [] }]
+}
+```
+
+A run passes when every expectation of its case passes; `pass_rate` is passing runs over runs.
+
+## Collections and plugins
+
+`superskill collection` measures a set of skills together:
+
+- **Listing budget.** Each skill costs `name + ": " + description` (plus `when_to_use`) in the
+  listing a harness loads every turn, with the description part cut off at 1536 characters
+  (Claude Code's documented cap). The total is reported against a budget per harness: 8000
+  characters for Claude Code and Codex by default. Neither vendor published a whole-listing
+  figure as of 2026-09-28, so this default is deliberately conservative and `--budget` sets it.
+- **Cut-off entries.** Every skill whose `description` plus `when_to_use` exceeds 1536 characters.
+- **Overlap.** Pairs whose descriptions have a token Jaccard similarity of 0.5 or more after
+  stopwords. Each flagged pair yields a near-miss query for each skill's `triggers.json`, so the
+  fix is proven by the trigger evals rather than guessed.
+
+A **plugin** is a folder with `.claude-plugin/plugin.json` and `skills/<name>/`. Its line reports:
+a `version`; a `CHANGELOG.md` heading for that version; and files duplicated byte-for-byte across
+skills (a helper to share once). A plugin is a **superplugin** when every skill in it is a
+superskill and its own line has no fail.
+
+## Freedom interop
+
+Nothing here requires Freedom, and the checker never imports or runs it. Where Freedom's files
+exist they are read as plain files:
+
+- `HDSOP.md` beside `SKILL.md` (the workflow map) is shown as a bonus line.
+- `superskill miss import <skill> --freedom-ledger` reads `<skill>/invocations.jsonl` and
+  `~/.freedom/ledger/skills/<plugin>/<skill>.jsonl`. Records are
+  `{id, skill, started, outcome, interventions: [{kind, note|what}], errors}`. A record with an
+  intervention of kind `redirect`, `correction` or `rescue`, or with `outcome: "failed"`, becomes
+  an open miss dated from `started`; `taste` interventions are skipped; the ledger id is kept on
+  a `Source:` line so a record is never imported twice.
+
+## Versioning
+
+This standard is versioned with semver. Adding a rule that can fail a skill which passed before
+is a minor version before 1.0 and a major version after. Thresholds are part of the standard.

package/bin/superskill.mjs

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+// superskill: score agent skills as skill / tested / superskill. Zero dependencies.
+import { UsageError } from "../src/args.mjs";
+import { DoctorError } from "../src/doctor.mjs";
+
+const COMMANDS = {
+  doctor: "../src/commands/doctor.mjs",
+  init: "../src/commands/init.mjs",
+  miss: "../src/commands/miss.mjs",
+  misses: "../src/commands/miss.mjs",
+  fix: "../src/commands/fix.mjs",
+  approve: "../src/commands/approve.mjs",
+  collection: "../src/commands/collection.mjs",
+  snippet: "../src/commands/snippet.mjs",
+};
+
+const HELP = `superskill <command> [options]
+
+Commands:
+  doctor <path...>             score skills; exit 0 when the target level is met
+  init <path>                  add missing evals, triggers, goldens and MISSES.md
+  miss <path> "<what>"         log a miss
+  fix <path> <miss-id> --eval  close a miss with the regression eval that guards it
+  approve <path> <golden>      record a person's approval of a golden (terminal only)
+  collection <folder>          listing budget, cut-off descriptions, overlapping skills
+  snippet                      print a block for AGENTS.md / CLAUDE.md
+
+Run "superskill <command> --help" for details. Spec: SPEC.md.
+`;
+
+async function main(argv) {
+  const [cmd, ...rest] = argv;
+  if (!cmd || cmd === "--help" || cmd === "-h" || cmd === "help") { process.stdout.write(HELP); return 0; }
+  if (cmd === "--version") {
+    const { readFileSync } = await import("node:fs");
+    process.stdout.write(JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version + "\n");
+    return 0;
+  }
+  const mod = COMMANDS[cmd];
+  if (!mod) throw new UsageError(`unknown command "${cmd}". Run superskill --help.`);
+  const { run } = await import(mod);
+  return run(rest);
+}
+
+main(process.argv.slice(2)).then(
+  (code) => { process.exitCode = code; },
+  (e) => {
+    if (e instanceof UsageError || e instanceof DoctorError || e?.code === "SUPERSKILL") {
+      process.stderr.write(`superskill: ${e.message}\n`);
+      process.exitCode = 2;
+    } else {
+      process.stderr.write(`superskill: unexpected error: ${e?.stack || e}\n`);
+      process.exitCode = 2;
+    }
+  },
+);

package/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "@supersuit/superskill",
+  "version": "0.1.0",
+  "description": "Score any agent skill folder as skill, tested, or superskill. An open standard and a zero-dependency CLI.",
+  "type": "module",
+  "bin": { "superskill": "bin/superskill.mjs" },
+  "files": ["bin/", "src/", "SPEC.md", "README.md", "CHANGELOG.md", "LICENSE"],
+  "scripts": { "test": "node --test test/*.test.mjs" },
+  "engines": { "node": ">=20" },
+  "license": "MIT",
+  "repository": { "type": "git", "url": "git+https://github.com/SupersuitUp/superskill.git" },
+  "homepage": "https://supersuit.wiki/concepts/superskill",
+  "keywords": ["agent-skills", "skills", "claude-code", "codex", "evals", "superskill"],
+  "dependencies": {}
+}

package/src/args.mjs

@@ -0,0 +1,30 @@
+/**
+ * Minimal argv parser. `booleans` names flags that never take a value; every other
+ * `--flag` consumes the next argument (or `--flag=value`). Positionals land in `_`.
+ */
+export function parseArgs(argv, booleans = []) {
+  const out = { _: [], flags: {} };
+  const bools = new Set(["help", "json", ...booleans]);
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "-h") { out.flags.help = true; continue; }
+    if (!a.startsWith("--") || a === "--") { out._.push(a); continue; }
+    const eq = a.indexOf("=");
+    const key = a.slice(2, eq > 0 ? eq : undefined);
+    if (eq > 0) out.flags[key] = a.slice(eq + 1);
+    else if (bools.has(key)) out.flags[key] = true;
+    else if (i + 1 < argv.length) out.flags[key] = argv[++i];
+    else throw new UsageError(`--${key} needs a value`);
+  }
+  return out;
+}
+
+export class UsageError extends Error {}
+
+/** The clock every date rule reads. SUPERSKILL_NOW pins it for tests and reproducible reports. */
+export function clock(flags = {}) {
+  const v = flags.now || process.env.SUPERSKILL_NOW;
+  const d = v ? new Date(v) : new Date();
+  if (Number.isNaN(d.getTime())) throw new UsageError(`not a date: ${v}`);
+  return d;
+}

package/src/changed.mjs

@@ -0,0 +1,52 @@
+// The update gate: which skills did a change touch, and did any of them lose a level.
+import { spawnSync } from "node:child_process";
+import { join, resolve, sep } from "node:path";
+import { realpathSync } from "node:fs";
+import { DoctorError } from "./doctor.mjs";
+import { LEVELS } from "./levels.mjs";
+
+function git(cwd, args) {
+  const r = spawnSync("git", args, { cwd, encoding: "utf8" });
+  if (r.error) throw new DoctorError(`git is not available: ${r.error.message}`);
+  return r;
+}
+
+const real = (p) => { try { return realpathSync(p); } catch { return resolve(p); } };
+
+/** Absolute paths changed since `base` (committed) plus staged, unstaged and untracked. */
+export function changedFiles(path, base) {
+  const top = git(path, ["rev-parse", "--show-toplevel"]);
+  if (top.status !== 0) throw new DoctorError(`--changed needs a git repository: ${path} is not in one`);
+  const root = top.stdout.trim();
+  const files = new Set();
+  const add = (out) => out.split("\n").map((l) => l.trim()).filter(Boolean).forEach((f) => files.add(real(join(root, f))));
+  if (base) {
+    const d = git(root, ["diff", "--name-only", `${base}...HEAD`]);
+    if (d.status !== 0) throw new DoctorError(`git diff against ${base} failed: ${d.stderr.trim()}`);
+    add(d.stdout);
+  }
+  add(git(root, ["diff", "--name-only", "HEAD"]).stdout);
+  add(git(root, ["ls-files", "--others", "--exclude-standard"]).stdout);
+  return [...files];
+}
+
+/** Keep the skill dirs that contain at least one changed file. */
+export function touchedSkills(dirs, files) {
+  return dirs.filter((d) => {
+    const prefix = real(d) + sep;
+    return files.some((f) => f.startsWith(prefix));
+  });
+}
+
+/** Compare against a previous `doctor --json`: every skill whose level went down. */
+export function levelDrops(current, baseline) {
+  const rank = (l) => (l === "none" ? -1 : LEVELS.indexOf(l));
+  const before = new Map();
+  for (const s of baseline.skills || []) { before.set(s.path, s); before.set(`name:${s.name}`, s); }
+  const drops = [];
+  for (const s of current.skills) {
+    const b = before.get(s.path) || before.get(`name:${s.name}`);
+    if (b && rank(s.level) < rank(b.level)) drops.push({ name: s.name, path: s.path, from: b.level, to: s.level });
+  }
+  return drops;
+}