@supersuit/superskill 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,40 @@
 # Changelog
 
+## 0.6.0 (2026-10-06)
+
+**A skill's embodiment is what it has absorbed, not one run of it.** 0.5.0 made a golden from a
+real run the top-level requirement. Its first real test reversed it: nine harvested candidates,
+each a real accepted run, and none was the standard the skill should be held to. The tests and
+fixes a skill has absorbed are. **Breaking for anyone at superskill today:** the top level now
+needs a real-run record and a 0.6.0 `--run` (one that records its `skill_sha` and the triggers).
+
+- **Superskill is now** every miss closed with a regression eval (`misses-closed`, which replaces
+  `no-stale-open-miss`: an open miss fails however recent it is), and `evals-pass`: the last
+  `--run` was against the current `SKILL.md`, the suite passed (default 90% of runs), every fixed
+  miss's regression eval passed every run, and the trigger evals were right (default 90%).
+  `run-evidence` and `run-fresh` stand.
+- **`real-runs`:** a real-run record where one model+harness pair, alone, has at least 5 real runs
+  at 80% one-shot (no correction). Every pair is reported; pairs are never pooled, and a pair that
+  says `unknown` never counts. The record is a harness-neutral file, `superskill-real-runs/1`, read
+  from `--real-runs <dir>` / `SUPERSKILL_REAL_RUNS`, then `evals/real-runs.json`, then Freedom's
+  skill ledger live. It replaces `real-use`.
+- **Configurable bar:** `--min-real-runs`, `--min-one-shot`, `--min-pass-rate`,
+  `--min-trigger-rate` (and `SUPERSKILL_MIN_*`). Never frontmatter: a skill cannot lower its own bar.
+- **Goldens are optional evidence.** `golden-approved` never fails. A golden is an eval graded on
+  `goldens/<id>/expectations.json`, a checklist of expected behavior (grade outcomes, not paths);
+  `output.md` is the reference that proves the task solvable. Provenance rules still say which
+  goldens are real runs.
+- **`doctor --run` runs the trigger evals** (did the harness load the skill exactly when it
+  should) and writes `skill_sha` and `triggers` into `latest.json`.
+- **`history-in-skill` (warn, level skill):** a dated incident story in `SKILL.md` ("Earned
+  2026-09-08", "(Gary, 2026-09-16: ...)", "on 2026-09-13 a session ...") belongs in `MISSES.md`,
+  which now holds a story's full entry: id, date, what happened, fix, eval, optional `Quote:`, with
+  indented continuation lines. Tuned on Freedom's 103 shipped skills. Still no line-count rule.
+- `superskill miss` takes `--quote` and `--date`.
+- Tests: 17 new; each guard broken on purpose and seen red (a stale-sha pass counting, pooled pairs
+  counting, an unknown pair counting, an open miss passing, a half-passing regression eval passing,
+  examples and provenance stamps flagged as history).
+
 ## 0.5.0 (2026-10-06)
 
 **Superskill needs a golden from a real run.** Before, any golden a person approved counted, so a

package/README.md

@@ -4,8 +4,9 @@ Score any agent skill folder as **skill**, **tested**, or **superskill**, and ge
 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);
+A superskill is fixed every time it gets something wrong, with a test that keeps each fix fixed;
+passes its whole eval suite on a current model; and does the job for real people without a
+correction, often enough to count. [What that means](https://supersuit.wiki/concepts/superskill);
 [the standard](SPEC.md).
 
 ## 30 seconds
@@ -34,12 +35,17 @@ file error. `--json` prints one JSON document and nothing else.
 
 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.
+   hard-coded machine paths, nothing that reads like a prompt injection. It warns on dated
+   incident stories in `SKILL.md`, which belong in `MISSES.md`.
 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 from a real run, accepted when it ran and approved by a person; 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).
+3. **superskill**: no open miss, and every fixed miss guarded by a regression eval; a recent
+   `--run` against the `SKILL.md` that is there now, where the suite passes (90%), every
+   regression eval passes every run, the trigger set is 90% right, and the skill beats the same
+   task done without it; and a real-run record where one model+harness has at least 5 real runs
+   at 80% one-shot (no correction). Pairs are never pooled. "Recent" follows `metadata.cadence`
+   (a weekly skill's proof lasts 30 days). Goldens are optional evidence. Every threshold is a
+   flag (`--min-real-runs`, `--min-one-shot`, `--min-pass-rate`, `--min-trigger-rate`).
 
 Every rule and threshold is in [SPEC.md](SPEC.md).
 
@@ -52,7 +58,7 @@ Every rule and threshold is in [SPEC.md](SPEC.md).
 | `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 miss <skill> "<what happened>" [--expected "..."] [--quote "..."] [--date YYYY-MM-DD]` | Log a time the skill got it wrong, or the story behind a rule it learned. |
 | `superskill fix <skill> <miss-id> --eval <id> [--commit <sha>]` | Close a miss. Refuses without an eval that exists. |
 | `superskill approve <skill> <golden> [--basis judgment\|outcome] [--rationale ...] [--evidence ...]` | A person signs off on a golden, saying why and what it rests on: `judgment` (it reads right) or `outcome` (it produced a checkable result, with evidence). At a terminal it asks for your name; from your phone, an agent records your tap with `--approved-by` and `--via`. Approvals accumulate. |
 | `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). |
@@ -70,9 +76,10 @@ 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, PROVENANCE.json, APPROVAL.json
-  MISSES.md                 every miss, open or fixed with its eval
-  evals/results/latest.json the last --run
+  goldens/<id>/             optional: input.md, expectations.json, output.md, PROVENANCE.json, APPROVAL.json
+  MISSES.md                 every miss and its story, open or fixed with its eval
+  evals/results/latest.json the last --run (which SKILL.md it proved, suite and triggers)
+  evals/real-runs.json      real uses per model+harness, one-shot or not (or --real-runs <dir>)
 ```
 
 Harnesses ignore folders they do not know, so none of this changes how the skill loads.
@@ -84,13 +91,16 @@ Harnesses ignore folders they do not know, so none of this changes how the skill
 - 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.
+  costs one grader call per run.
+- Trigger evals run each query in `evals/triggers.json` with the skill installed and record
+  whether the harness loaded it (Claude Code: a `Skill` call or a read of its `SKILL.md`; Codex:
+  a read of its `SKILL.md`).
 
 ## 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.
+files, and with no `evals/real-runs.json` the doctor reads the real-run record from it too. `superskill snippet` gives any agent the same habits with no Freedom installed.
 
 ## Releasing
 

package/SPEC.md

@@ -1,13 +1,21 @@
 # The superskill standard
 
-**Version 0.5.0** (2026-10-06). The reference checker is `@supersuit/superskill`; where this
+**Version 0.6.0** (2026-10-06). 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
+A **superskill** runs on frontier intelligence, is fixed every time it gets something wrong, and
+does the job for real people without a correction
 ([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.
 
+**What a skill has absorbed is its embodiment, not one run of it (0.6.0).** Until 0.5.0 the top
+level required a golden: one real run a person approved as the standard. A random accepted run
+is not the ultimate embodiment of a skill; the misses it was fixed for, and the evals that keep
+each fix fixed, are. This follows Anthropic's guidance on agent evals: build the suite from real
+failures, hold regression evals near 100%, grade outcomes rather than paths, and use a reference
+solution to prove a task is solvable, not as the answer to match. Goldens remain, as optional
+evidence.
+
 ## Contents
 
 - [The clauses and their evidence](#the-clauses-and-their-evidence)
@@ -23,9 +31,10 @@ a file in the skill's own folder, so the evidence travels with the skill whereve
 | 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 from a real run: the real input, the output the person accepted when it ran, where it came from, and a record of who approved it as a golden and when | `goldens/<id>/` (or a private folder, see below) |
-| 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` |
+| Fixed every time it gets something wrong | A miss log where every miss is fixed, each with a regression eval that would catch it again, and the story of each fix | `MISSES.md` + `evals/evals.json` |
+| Runs on frontier intelligence | Its whole suite and trigger set last passed against the current `SKILL.md`, on a current model, recently, and beat the same task run without the skill | `evals/results/latest.json` |
+| Does the job for real | Enough real runs on one model+harness, enough of them one-shot (no correction) | `evals/real-runs.json` (or an operator's export, see below) |
+| Optional: an example a person approved | A golden: a real input, the checklist a right answer meets, a reference output, where it came from | `goldens/<id>/` (or a private folder) |
 
 ```
 my-skill/
@@ -33,12 +42,14 @@ my-skill/
   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)
+  MISSES.md                         miss log + history (level: superskill)
+  evals/results/latest.json         last --run        (level: superskill)
+  evals/real-runs.json              real-run record   (level: superskill)
+  goldens/<id>/input.md             optional evidence
+  goldens/<id>/expectations.json
   goldens/<id>/output.md
   goldens/<id>/PROVENANCE.json
   goldens/<id>/APPROVAL.json
-  MISSES.md                         miss log          (level: superskill)
-  evals/results/latest.json         last --run        (level: superskill)
 ```
 
 ## Compatibility
@@ -78,6 +89,7 @@ A line in a bundled file containing `superskill-ignore` is skipped by `no-absolu
 | `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. |
+| `history-in-skill` | warn | no dated incident story in the body outside code: "Earned 2026-09-08", "(Gary, 2026-09-16: ...)", "Wilson, 2026-09-05: \*"..."\*", "on 2026-09-13 a session ...", "until 2026-09-21 the flag ...", "measured 2026-09-20", "(2026-09-30, #324)", "- 2026-09-15 (#147): ...". Matched per paragraph, since a line wrap can split a name from its date. Not flagged: a line with "e.g." or "example", a date in a code span or fence, a heading, an HTML comment (a generator's provenance stamp), "as of <date>". The story goes in `MISSES.md` (below); `SKILL.md` keeps the rule and a one-line why. There is deliberately no line-count rule (retired 2026-09-28): length alone is never a defect. |
 | `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 |
@@ -99,13 +111,20 @@ A line in a bundled file containing `superskill-ignore` is skipped by `no-absolu
 
 | Rule | Severity | Threshold |
 |---|---|---|
-| `golden-approved` | fail | at least one golden **from a real run** (its `PROVENANCE.json` says `source: real-run`, names the run, and names who accepted it and when; an anonymized twin also carries `ANONYMIZED.json`) has an approval with non-empty `approved_by` and a valid `approved_at`. An approved golden without that provenance is named and does not count. Info when it was approved against an earlier `SKILL.md`; info naming the weight (judgment and outcome approvals per golden), and saying so plainly when no golden has an outcome yet |
-| `real-use` | info | when the run ledger records what the person's next message made of each run (Freedom's `next_turn`), the share of those runs in the last 30 days they accepted; sandbox runs are never counted |
 | `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 |
+| `misses-closed` | fail | no miss is open. A miss is a known way the skill fails; a skill that still fails a known way is not at the top level, however recent the miss |
 | `fixed-miss-has-eval` | fail | every fixed miss names an eval id present in `evals.json` or `goldens/` |
+| `evals-pass` | fail | the last `--run` was against the current `SKILL.md` (`skill_sha` equals the sha256 of `SKILL.md`); its suite passed at least the minimum share of runs with the skill (default 90%); every fixed miss's regression eval passed every run; and it ran the trigger evals and got at least the minimum share right (default 90%) |
 | `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 |
+| `real-runs` | fail | a real-run record (below) in which at least one model+harness pair, on its own, has at least the minimum runs (default 5) and one-shot share (default 80%). Each pair is reported as info; **pairs are never pooled**, since a clean record on one model in one harness proves nothing about another. A pair whose model or harness is `unknown` is reported and never counts |
+| `golden-approved` | info / warn | never fails. Reports each golden that is approved and from a real run (with its approval weight), names approved goldens that are not from a real run and why, names a golden with no `expectations.json`, and warns on an `APPROVAL.json` or `PROVENANCE.json` that does not parse |
+
+**The thresholds are configurable, never by the skill itself.** A skill cannot lower its own bar,
+so they are not frontmatter. `doctor` takes `--min-real-runs <n>`, `--min-one-shot <0..1>`,
+`--min-pass-rate <0..1>` and `--min-trigger-rate <0..1>`, or the environment variables
+`SUPERSKILL_MIN_REAL_RUNS`, `SUPERSKILL_MIN_ONE_SHOT`, `SUPERSKILL_MIN_PASS_RATE` and
+`SUPERSKILL_MIN_TRIGGER_RATE`. A report scored with non-default thresholds should say so.
 
 `metadata.cadence` in `SKILL.md` frontmatter declares how often the skill really runs:
 
@@ -155,11 +174,18 @@ A bare array of cases is accepted on read, as is `assertions` for `expectations`
 ]
 ```
 
-### `goldens/<id>/`
+### `goldens/<id>/` (optional evidence)
+
+**A golden is an eval whose grading is a checklist of expected behavior (0.6.0).** It is never
+required for any level. Grade the outcome, not the path: the checklist says what a right answer
+does, and the reference output proves the task is solvable and calibrates the grader. A golden
+that exists is still held to the provenance rules below, because "a person accepted this when
+it ran" is a claim that has to be true.
 
 - `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.
+- `expectations.json`: an array of expectations (the same forms as `evals.json`), graded by
+  `--run`. Without it, `--run` grades by likeness to the reference output.
+- `output.md` (or any other file that is not `input.*` or a metadata file): the reference output.
 - `APPROVAL.json`, written only by `superskill approve`: at an interactive terminal, or relayed by an agent with `--approved-by` and `--via` after the person approved with a tap (the `via` field records where):
 
 ```json
@@ -184,11 +210,9 @@ approval whose `note` is its rationale.
 A golden is also an eval: `--run` judges the skill's output for `input.md` against the approved
 output.
 
-**`PROVENANCE.json` says where the example came from (0.5.0).** Only a golden from a real run
-counts toward superskill. An invented input with an invented output puts "a person said this was
-right" on something no person's work produced, and a skill could then reach the top level on its
-author's fiction. Invented cases still belong in `evals/evals.json`, where they hold a skill at
-`tested`.
+**`PROVENANCE.json` says where the example came from (0.5.0).** Only a golden from a real run is
+reported as real evidence. An invented input with an invented output puts "a person said this
+was right" on something no person's work produced. Invented cases belong in `evals/evals.json`.
 
 ```json
 {
@@ -208,13 +232,12 @@ author's fiction. Invented cases still belong in `evals/evals.json`, where they
   anonymizer's receipt (`checker`, `checked_at`, `counts` by kind, `fingerprint`, never the
   mapping). Without the receipt the twin does not count.
 - `superskill init --from-session` writes `source: real-run` with `accepted` empty, so the golden
-  cannot count until someone records who accepted it.
+  is not reported as real until someone records who accepted it.
 
 **Private goldens.** A real run's input and output are usually about real people and should not
 travel with a skill that is shared. `--private-goldens <dir>` (or `SUPERSKILL_PRIVATE_GOLDENS`)
 makes `doctor`, `approve` and `doctor --run` also read `<dir>/<skill-name>/<id>/`, laid out exactly
-like `goldens/<id>/`. A private golden counts for the operator who holds it. A miss is closed only
-by an eval or golden that ships with the skill.
+like `goldens/<id>/`. A miss is closed only by an eval or golden that ships with the skill.
 
 ### `MISSES.md`
 
@@ -226,11 +249,29 @@ by an eval or golden that ships with the skill.
 - Should have: Merged duplicates into one line.
 - Fix: a1b2c3d
 - Eval: m1
+- Quote: "why is Atlas in here twice"     (optional)
 - 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.
+`m2`, ... Other headings are ignored. A field runs on over indented lines that follow it.
+
+**`MISSES.md` is where a skill's history lives (0.6.0).** `SKILL.md` is instructions, loaded on
+every run; the story of the incident that earned a rule is history, and Anthropic's authoring
+guidance is to keep time-sensitive content out of instructions. So a story becomes a miss entry:
+
+| Field | Holds |
+|---|---|
+| id, date | `m<N>`, and the date the incident happened (not the date it was written down) |
+| What happened | the incident, in full: what the skill did, what it cost, what was noticed |
+| Should have | what the skill should have done |
+| Fix | the commit, or the rule now in `SKILL.md` that the incident earned |
+| Eval | the regression eval that would catch it again. Empty until one exists, and the doctor says so (`fixed-miss-has-eval`): a story with no eval is a fix nothing guards yet |
+| Quote | optional: what the person said, verbatim |
+| Source | optional: where it was recorded (a ledger id, an issue) |
+
+`SKILL.md` keeps the rule and a one-line why. `superskill miss <skill> "<what>" --date <d> --quote
+"<q>"` writes one.
 
 ### `evals/results/latest.json`
 
@@ -241,15 +282,53 @@ Written only by `superskill doctor --run`:
   "run_at": "2026-09-20T10:00:00.000Z",
   "harness": "claude",
   "model": "<model id the harness reported>",
+  "skill_sha": "<sha256 of the SKILL.md the run proved>",
   "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": [] }]
+  "per_case": [{ "id": "1", "with_skill": { "runs": 3, "passes": 3 }, "without_skill": { "runs": 3, "passes": 1 }, "failures": [] }],
+  "triggers": { "cases": 12, "runs": 36, "passes": 35, "pass_rate": 0.972,
+    "per_query": [{ "query": "write my weekly status", "should_trigger": true, "runs": 3, "passes": 3 }] }
 }
 ```
 
 A run passes when every expectation of its case passes; `pass_rate` is passing runs over runs.
+A trigger run passes when the harness loaded the skill exactly when `should_trigger` says
+(Claude Code: a `Skill` tool call naming it or a read of its `SKILL.md`; Codex: a read of its
+`SKILL.md`). A golden with `expectations.json` is graded on that checklist; one without is graded
+by likeness to its reference output.
+
+### `evals/real-runs.json` (the real-run record)
+
+Harness-neutral: any harness, ledger or script may write it, and the doctor only reads it.
+
+```json
+{
+  "format": "superskill-real-runs/1",
+  "skill": "weekly-status",
+  "generated_at": "2026-10-06T12:00:00Z",
+  "source": "freedom-skill-ledger",
+  "pairs": [
+    { "model": "claude-opus-5-5", "harness": "claude-code", "runs": 12, "one_shot": 11,
+      "first_at": "2026-09-01T09:00:00Z", "last_at": "2026-10-05T18:00:00Z" }
+  ]
+}
+```
+
+- A **run** is one real use of the skill by a person. Never a sandbox run (`doctor --run`), never
+  a test.
+- It is **one-shot** when the person needed no correction, rescue or redirect, it did not fail or
+  get abandoned, and it was not corrected after it handed back. A taste note is the person's
+  preference, not the skill's defect, and does not break one-shot.
+- `model` is the model id the harness ran (as the transcript or environment reports it);
+  `harness` is `claude-code`, `codex`, or another harness's name. A writer that cannot tell
+  writes `unknown`, never a guess. Counts only: the file carries no input, output or names, so it
+  can ship with the skill.
+
+**Where the doctor reads it**, first found wins: `<dir>/<skill-name>.json` where `<dir>` is
+`--real-runs` or `SUPERSKILL_REAL_RUNS` (an operator's own export, kept out of the skill); then
+`evals/real-runs.json` in the skill; then Freedom's skill ledger, read live (below).
 
 ## Collections and plugins
 
@@ -285,6 +364,11 @@ exist they are read as plain files:
   sandbox run) is skipped. A record corrected after it handed back (`corrected_after`, with
   `next_turn_ref`) gets a "Should have" that points at the person's correction: the session and
   the time, never their words.
+- **The real-run record.** Freedom's skill ledger records, on every run, the `model` id and the
+  `harness` (`claude-code`, `codex`, ...), read from the session transcript or the environment and
+  `unknown` when neither says. Freedom exports it in the `superskill-real-runs/1` format above,
+  one file per skill, for `--real-runs`. With no export and no `evals/real-runs.json`, the doctor
+  reads the same ledger files live and counts them the same way (sandbox runs skipped).
 - **`doctor --run` is never recorded as a use.** Every harness spawns its child with
   `FREEDOM_SKILL_LEDGER=off` and `SUPERSKILL_SANDBOX=1`, in a folder named `superskill-run-*`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supersuit/superskill",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Score any agent skill folder as skill, tested, or superskill. An open standard and a zero-dependency CLI.",
   "type": "module",
   "bin": {

package/src/commands/doctor.mjs

@@ -9,8 +9,9 @@ export const help = `superskill doctor <path...> [options]
 
 Score one skill, a folder of skills, or a plugin (skills/*/SKILL.md).
 Levels: skill (spec-valid, hygienic) < tested (real evals + triggers) < superskill
-(an approved golden from a real run a person accepted, misses fixed with evals, a fresh
---run that beats no-skill).
+(every miss fixed with a regression eval; the suite and triggers pass against this SKILL.md
+in a fresh --run that beats no-skill; and a real-run record: at least 5 real runs, 80%
+one-shot, on one model+harness). Goldens are optional evidence.
 
 Options:
   --level <skill|tested|superskill>  target level for the exit code (default skill)
@@ -23,6 +24,13 @@ Options:
                                      model calls; see "superskill doctor --run --help")
   --private-goldens <dir>            also read goldens from <dir>/<skill-name>/<id>/ (or set
                                      SUPERSKILL_PRIVATE_GOLDENS): real runs kept out of the skill
+  --real-runs <dir>                  read the real-run record from <dir>/<skill-name>.json (or
+                                     set SUPERSKILL_REAL_RUNS); else evals/real-runs.json, else
+                                     Freedom's skill ledger
+  --min-real-runs <n>                real runs one model+harness needs (default 5)
+  --min-one-shot <0..1>              one-shot share that pair needs (default 0.8)
+  --min-pass-rate <0..1>             suite pass rate the last --run needs (default 0.9)
+  --min-trigger-rate <0..1>          trigger evals right in the last --run (default 0.9)
   --now <iso date>                   evaluate dates as of this moment
   --help                             this text
 
@@ -37,7 +45,7 @@ export async function run(argv) {
   const level = a.flags.level || "skill";
   if (!LEVELS.includes(level)) throw new UsageError(`--level must be one of ${LEVELS.join(", ")}`);
   if (!a._.length) throw new UsageError("doctor needs a path");
-  const opts = { level, now: clock(a.flags), privateGoldens: a.flags["private-goldens"] || process.env.SUPERSKILL_PRIVATE_GOLDENS || null };
+  const opts = { level, now: clock(a.flags), privateGoldens: a.flags["private-goldens"] || process.env.SUPERSKILL_PRIVATE_GOLDENS || null, ...thresholds(a.flags) };
   if (a.flags.changed) {
     const all = a._.flatMap((p) => findSkills(p));
     const files = a._.flatMap((p) => changedFiles(p, a.flags.base));
@@ -64,3 +72,21 @@ export async function run(argv) {
   }
   return result.ok ? 0 : 1;
 }
+
+/** The superskill bar's thresholds, from flags then environment. Unset means the documented default. */
+export function thresholds(flags, env = process.env) {
+  const pick = (flag, envName, lo, hi) => {
+    const raw = flags[flag] ?? env[envName];
+    if (raw === undefined || raw === "") return undefined;
+    const n = Number(raw);
+    if (!Number.isFinite(n) || n < lo || (hi !== null && n > hi)) throw new UsageError(`--${flag} must be a number${hi === null ? ` of at least ${lo}` : ` from ${lo} to ${hi}`}`);
+    return n;
+  };
+  return {
+    realRuns: flags["real-runs"] || env.SUPERSKILL_REAL_RUNS || null,
+    minRealRuns: pick("min-real-runs", "SUPERSKILL_MIN_REAL_RUNS", 1, null),
+    minOneShot: pick("min-one-shot", "SUPERSKILL_MIN_ONE_SHOT", 0, 1),
+    minPassRate: pick("min-pass-rate", "SUPERSKILL_MIN_PASS_RATE", 0, 1),
+    minTriggerRate: pick("min-trigger-rate", "SUPERSKILL_MIN_TRIGGER_RATE", 0, 1),
+  };
+}

package/src/commands/miss.mjs

@@ -2,11 +2,12 @@ import { parseArgs, clock, UsageError } from "../args.mjs";
 import { skillDir, today } from "./common.mjs";
 import { readMisses, appendMisses, nextMissId } from "../misses.mjs";
 
-export const help = `superskill miss <skill> "<what happened>" [--expected "<what should have>"]
+export const help = `superskill miss <skill> "<what happened>" [--expected "<what should have>"] [--quote "<what they said>"] [--date YYYY-MM-DD]
 superskill miss import <skill> --freedom-ledger [--ledger <file>]
 
-Log a time the skill got something wrong. The entry opens today; an open miss older than
-14 days blocks the superskill level. Close it with \`superskill fix\`.
+Log a time the skill got something wrong. The entry opens today (or on --date, for a story
+from the past); an open miss blocks the superskill level. Close it with \`superskill fix\`.
+This is also where the story behind a rule goes: SKILL.md keeps the rule and a one-line why.
 `;
 
 export async function run(argv) {
@@ -18,7 +19,9 @@ export async function run(argv) {
   if (!what) throw new UsageError('miss needs a description: superskill miss <skill> "<what happened>"');
   const misses = readMisses(dir) || [];
   const id = nextMissId(misses);
-  appendMisses(dir, [{ id, date: today(clock(a.flags)), status: "open", what, expected: a.flags.expected || "" }]);
+  const date = a.flags.date || today(clock(a.flags));
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(date)) throw new UsageError("--date must be YYYY-MM-DD");
+  appendMisses(dir, [{ id, date, status: "open", what, expected: a.flags.expected || "", quote: a.flags.quote || "" }]);
   process.stdout.write(`${id} logged (open). Close it with: superskill fix ${a._[0]} ${id} --eval <id>\n`);
   return 0;
 }

package/src/goldens.mjs

@@ -1,4 +1,5 @@
-// goldens/<id>/: input.md, the approved output (output.md, or any other non-input file),
+// goldens/<id>/: input.md, expectations.json (0.6.0: the checklist a right answer meets,
+// graded by --run), the reference output (output.md, or any other non-input file),
 // APPROVAL.json written by a person: { approvals: [{approved_by, approved_at, skill_sha,
 // rationale, basis, evidence}] } (or the single-approval shape from before 0.3.0),
 // PROVENANCE.json saying where the example came from (0.5.0), and, for an anonymized twin of a
@@ -11,7 +12,7 @@ import { readdirSync, readFileSync, existsSync, statSync } from "node:fs";
 import { join } from "node:path";
 
 /** Files in a golden folder that describe it rather than being its input or output. */
-export const META_FILES = new Set(["APPROVAL.json", "PROVENANCE.json", "ANONYMIZED.json"]);
+export const META_FILES = new Set(["APPROVAL.json", "PROVENANCE.json", "ANONYMIZED.json", "expectations.json"]);
 
 /** Where goldens are read from: the skill's own goldens/, then the private folder for its name. */
 export function goldenRoots(dir, { privateGoldens = null, name = null } = {}) {
@@ -40,6 +41,8 @@ export function readGoldens(dir, opts = {}) {
       const prov = readJsonFile(join(gdir, "PROVENANCE.json"));
       const anon = readJsonFile(join(gdir, "ANONYMIZED.json"));
       const provenance = prov.value;
+      const exp = readJsonFile(join(gdir, "expectations.json"));
+      const expList = Array.isArray(exp.value) ? exp.value : Array.isArray(exp.value?.expectations) ? exp.value.expectations : [];
       out.push({
         id,
         dir: gdir,
@@ -54,6 +57,10 @@ export function readGoldens(dir, opts = {}) {
         provenanceError: prov.error,
         anonymized: anon.value,
         origin: originOf(provenance, anon.value),
+        // 0.6.0: what a right answer does, graded by --run. output.md is the reference that
+        // proves the task is solvable; it is no longer what the output has to look like.
+        expectations: expList.filter((x) => typeof x === "string" && x.trim()),
+        expectationsError: exp.error,
       });
     }
   }

package/src/misses.mjs

@@ -1,41 +1,49 @@
-// MISSES.md: one dated entry per time the skill got something wrong.
+// MISSES.md: one dated entry per time the skill got something wrong. It is also where a
+// skill's history lives (0.6.0): the story of the incident that earned a rule goes here, and
+// SKILL.md keeps only the rule and a one-line why.
 //
 //   ## m1 · 2026-09-20 · fixed
-//   - What happened: ...
+//   - What happened: ...                (an indented line under a field continues it)
 //   - Should have: ...
-//   - Fix: <commit sha or note>
+//   - Fix: <commit sha or note: the rule now in SKILL.md>
 //   - Eval: m1
+//   - Quote: "what the person said"     (optional)
 //   - Source: freedom-ledger <id>      (optional)
 import { readFileSync, existsSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 
 export const MISSES_HEADER = `# Misses
 
-Every time this skill got something wrong. An open miss older than 14 days blocks the
-superskill level; a fixed miss must name the eval that would catch it again.
+Every time this skill got something wrong, and the story behind each rule it learned. An open
+miss blocks the superskill level; a fixed miss must name the eval that would catch it again.
 Written by \`superskill miss\` and \`superskill fix\`, and readable by hand.
 `;
 
 const HEAD_RE = /^##\s+(m\d+)\s*[·|\-–]\s*(\d{4}-\d{2}-\d{2})\s*[·|\-–]\s*(open|fixed)\s*$/i;
-const FIELDS = { "what happened": "what", "should have": "expected", fix: "fix", eval: "eval", source: "source" };
+const FIELDS = { "what happened": "what", "should have": "expected", fix: "fix", eval: "eval", quote: "quote", source: "source" };
 
 export function parseMisses(text) {
   const out = [];
   let cur = null;
+  let last = null;
   const lines = String(text).replace(/\r\n?/g, "\n").split("\n");
   lines.forEach((line, i) => {
     const h = line.match(HEAD_RE);
     if (h) {
-      cur = { id: h[1].toLowerCase(), date: h[2], status: h[3].toLowerCase(), what: "", expected: "", fix: "", eval: "", source: "", line: i + 1 };
+      cur = { id: h[1].toLowerCase(), date: h[2], status: h[3].toLowerCase(), what: "", expected: "", fix: "", eval: "", quote: "", source: "", line: i + 1 };
+      last = null;
       out.push(cur);
       return;
     }
-    if (/^##\s/.test(line)) { cur = null; return; }
-    const f = cur && line.match(/^\s*[-*]\s*([A-Za-z ]+?)\s*:\s*(.*)$/);
-    if (f) {
-      const key = FIELDS[f[1].toLowerCase()];
-      if (key) cur[key] = f[2].trim();
-    }
+    if (/^##\s/.test(line)) { cur = null; last = null; return; }
+    if (!cur) return;
+    const f = line.match(/^\s*[-*]\s*([A-Za-z ]+?)\s*:\s*(.*)$/);
+    const key = f && FIELDS[f[1].toLowerCase()];
+    if (key) { cur[key] = f[2].trim(); last = key; return; }
+    // A story rarely fits on one line: an indented line continues the field above it.
+    if (last && /^\s{2,}\S/.test(line)) { cur[last] = `${cur[last]} ${line.trim()}`.trim(); return; }
+    if (!line.trim()) return;
+    last = null;
   });
   return out;
 }
@@ -50,6 +58,7 @@ export function formatMiss(m) {
   const lines = [`## ${m.id} · ${m.date} · ${m.status}`, `- What happened: ${m.what}`];
   if (m.expected) lines.push(`- Should have: ${m.expected}`);
   lines.push(`- Fix: ${m.fix || ""}`, `- Eval: ${m.eval || ""}`);
+  if (m.quote) lines.push(`- Quote: ${m.quote}`);
   if (m.source) lines.push(`- Source: ${m.source}`);
   return lines.join("\n") + "\n";
 }

package/src/realruns.mjs

@@ -0,0 +1,122 @@
+// The real-run record (0.6.0): how often the skill did the job for a real person with no
+// correction, counted separately for every model and harness it ran on.
+//
+// Harness-neutral on purpose. Any harness, ledger or script can write the file; the doctor only
+// reads it. Format `superskill-real-runs/1`:
+//
+//   {
+//     "format": "superskill-real-runs/1",
+//     "skill": "weekly-status",
+//     "generated_at": "2026-10-06T12:00:00Z",
+//     "source": "freedom-skill-ledger",
+//     "pairs": [
+//       { "model": "claude-opus-5-5", "harness": "claude-code", "runs": 12, "one_shot": 11,
+//         "first_at": "2026-09-01T09:00:00Z", "last_at": "2026-10-05T18:00:00Z" }
+//     ]
+//   }
+//
+// A run is one real use: never a sandbox run (`doctor --run`), never a test. It is one-shot when
+// the person needed no correction, rescue or redirect, it did not fail or get abandoned, and it
+// was not corrected after it handed back. A taste note is the person's preference, not a defect,
+// and does not break one-shot.
+//
+// Where the doctor reads it, first found wins:
+//   1. <dir>/<skill-name>.json, where <dir> is --real-runs or SUPERSKILL_REAL_RUNS (an
+//      operator's own export, kept out of the skill);
+//   2. <skill>/evals/real-runs.json (counts only, so it can travel with the skill);
+//   3. Freedom's skill ledger, read as plain files, when neither exists.
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { ledgerPaths } from "./ledger.mjs";
+
+export const FORMAT = "superskill-real-runs/1";
+export const UNKNOWN = "unknown";
+/** The defaults the real-runs rule holds a skill to. `--min-real-runs` / `--min-one-shot` change them. */
+export const MIN_REAL_RUNS = 5;
+export const MIN_ONE_SHOT = 0.8;
+
+const MISS_KINDS = new Set(["redirect", "correction", "rescue"]);
+
+/** Is this a known model+harness pair? A record that could not say proves nothing about either. */
+export const knownPair = (p) => Boolean(p.model && p.harness && p.model !== UNKNOWN && p.harness !== UNKNOWN);
+
+function normalize(doc, where) {
+  if (!doc || typeof doc !== "object") return { error: `${where} is not a JSON object` };
+  if (doc.format && doc.format !== FORMAT) return { error: `${where} has format ${JSON.stringify(doc.format)}, not ${FORMAT}` };
+  if (!Array.isArray(doc.pairs)) return { error: `${where} has no pairs array` };
+  const pairs = doc.pairs
+    .filter((p) => p && typeof p === "object")
+    .map((p) => ({
+      model: String(p.model || UNKNOWN),
+      harness: String(p.harness || UNKNOWN),
+      runs: Math.max(0, Number(p.runs) || 0),
+      one_shot: Math.max(0, Number(p.one_shot) || 0),
+      first_at: p.first_at || null,
+      last_at: p.last_at || null,
+    }))
+    .map((p) => ({ ...p, one_shot: Math.min(p.one_shot, p.runs) }));
+  return { pairs, generated_at: doc.generated_at || null, source: doc.source || null, where };
+}
+
+function readFile(p, where) {
+  try { return normalize(JSON.parse(readFileSync(p, "utf8")), where); }
+  catch (e) { return { error: `${where} is not valid JSON: ${e.message}` }; }
+}
+
+/** Is a ledger record a one-shot run? Exported so a writer can count the same way the reader does. */
+export function isOneShot(rec) {
+  const kinds = (Array.isArray(rec?.interventions) ? rec.interventions : []).filter((i) => i && MISS_KINDS.has(i.kind));
+  return !kinds.length && !["failed", "abandoned"].includes(rec?.outcome) && !rec?.corrected_after;
+}
+
+/** Summarize ledger records (Freedom's shape, or any with model/harness/started) per model+harness. */
+export function pairsFromRecords(records, skillName = null) {
+  const by = new Map();
+  for (const rec of records) {
+    if (!rec || rec.synthetic) continue;
+    if (skillName && rec.skill && bare(rec.skill) !== bare(skillName)) continue;
+    const model = String(rec.model || UNKNOWN), harness = String(rec.harness || UNKNOWN);
+    const k = `${model}\u0000${harness}`;
+    const p = by.get(k) || { model, harness, runs: 0, one_shot: 0, first_at: null, last_at: null };
+    p.runs++;
+    if (isOneShot(rec)) p.one_shot++;
+    const t = typeof rec.started === "string" ? rec.started : null;
+    if (t && (!p.first_at || t < p.first_at)) p.first_at = t;
+    if (t && (!p.last_at || t > p.last_at)) p.last_at = t;
+    by.set(k, p);
+  }
+  return [...by.values()].sort((a, b) => b.runs - a.runs || a.model.localeCompare(b.model));
+}
+
+const bare = (name) => String(name || "").split(":").pop();
+
+function fromLedger(dir, name) {
+  const paths = ledgerPaths(dir, name);
+  if (!paths.length) return null;
+  const recs = [];
+  for (const p of paths) {
+    let text = "";
+    try { text = readFileSync(p, "utf8"); } catch { continue; }
+    for (const line of text.split("\n")) {
+      if (!line.trim()) continue;
+      try { recs.push(JSON.parse(line)); } catch {}
+    }
+  }
+  return { pairs: pairsFromRecords(recs, name), generated_at: null, source: "freedom-skill-ledger (read live)", where: "Freedom's skill ledger" };
+}
+
+/** The real-run record for one skill, or null when nothing records any. */
+export function readRealRuns(dir, { name, realRunsDir = null } = {}) {
+  if (realRunsDir && name) {
+    const p = join(realRunsDir, `${name}.json`);
+    if (existsSync(p)) return readFile(p, `${realRunsDir}/${name}.json`);
+  }
+  const local = join(dir, "evals", "real-runs.json");
+  if (existsSync(local)) return readFile(local, "evals/real-runs.json");
+  return fromLedger(dir, name);
+}
+
+/** Does any single pair clear the bar? Never pooled: each pair stands or falls on its own runs. */
+export function meetsBar(pairs, { minRuns = MIN_REAL_RUNS, minOneShot = MIN_ONE_SHOT } = {}) {
+  return pairs.filter(knownPair).filter((p) => p.runs >= minRuns && p.one_shot / p.runs >= minOneShot);
+}

package/src/rules/skill.mjs

@@ -26,6 +26,63 @@ function proseLines(body) {
     return { line, fenced };
   });
 }
+// A dated incident story, as written in real skills: "Earned 2026-09-08", "(Gary, 2026-09-16:
+// ...)", "Wilson, live, 2026-09-05: *"...", "on 2026-09-13 the in-process version sat...",
+// "until 2026-09-21 the flag...", "measured on 2026-09-20", "(2026-09-30, #324)",
+// "- 2026-09-15 (#147): ...". Matched per paragraph, because hard-wrapped prose puts the name on
+// one line and its date on the next. Tuned against Freedom's 103 shipped skills (2026-10-06): a
+// date in an example, a template, a code span, a fence, or a provenance line ending at the date
+// ("vendored ... on 2026-09-19.") is not a story.
+const D = "20\\d\\d-\\d\\d-\\d\\d";
+const HISTORY = [
+  new RegExp(`\\bearned\\b[^.]{0,24}?\\b(${D})`, "gi"),
+  new RegExp(`\\([^()\\n]{0,80}?\\b(${D})\\s*[:),.;—]`, "g"),
+  new RegExp(`(?:\\b[A-Z][\\w'-]+|\\b(?:operator|owner|maintainer|client|teammate)),\\s*(?:[a-z]+,\\s*)?(${D})\\s*[,:]`, "g"),
+  new RegExp(`\\b(?:on|until|since|before|after)\\s+(${D})\\b`, "gi"),
+  new RegExp(`\\bfrom\\s+(${D})\\s+\\(`, "gi"),
+  new RegExp(`\\b(?:measured|reported|found|caught|hit|corrected|retired|aligned|renamed|refused|broke|failed|observed|verified|watched|fixed|softened|flipped|restored|removed|changed|added|introduced)\\s+(?:[a-z]+\\s+)?(?:on\\s+|in\\s+)?(${D})`, "gi"),
+  new RegExp(`\\b(?:rule|ruling|default|correction|incident|reversal)\\s+(?:of|from)\\s+(${D})`, "gi"),
+  new RegExp(`\\bthe\\s+(${D})\\b`, "gi"),
+  new RegExp(`(${D})'s\\b`, "g"),
+  new RegExp(`^\\s*[-*]\\s+[*_]*(${D})[*_]*\\s*[(:]`, "gm"),
+];
+const EXAMPLE = /\b(e\.g\.|example|for instance|such as)\b/i;
+
+/**
+ * Body lines that narrate a dated incident, outside code fences and inline code: one entry per
+ * line that carries the date of a story.
+ */
+export function historyLines(body) {
+  const lines = proseLines(body);
+  const hit = new Map();
+  let para = [];
+  const flush = () => {
+    if (!para.length) return;
+    // Join the paragraph, remembering where each line starts, so a match maps back to its line.
+    let text = "";
+    const starts = [];
+    for (const { i, line } of para) { starts.push({ i, at: text.length }); text += line.replace(/`[^`]*`/g, "``") + "\n"; }
+    for (const re of HISTORY) {
+      re.lastIndex = 0;
+      for (const m of text.matchAll(re)) {
+        const at = m.index + m[0].lastIndexOf(m[1]);
+        const owner = [...starts].reverse().find((s) => s.at <= at);
+        const raw = lines[owner.i].line;
+        if (EXAMPLE.test(raw)) continue;
+        if (!hit.has(owner.i)) hit.set(owner.i, raw.trim());
+      }
+    }
+    para = [];
+  };
+  lines.forEach(({ line, fenced }, i) => {
+    // A heading, an HTML comment (a generator's provenance stamp) and a fence are not prose.
+    if (fenced || !line.trim() || /^\s*(#|<!--)/.test(line)) { flush(); return; }
+    para.push({ i, line });
+  });
+  flush();
+  return [...hit.entries()].sort((a, b) => a[0] - b[0]).map(([i, text]) => ({ lineNo: i + 1, text }));
+}
+
 const normRule = (line) => line.toLowerCase().replace(/[*_`>#-]/g, "").replace(/\s+/g, " ").trim();
 const broken = (ctx) => Boolean(ctx.error || ctx.parseError);
 const str = (v) => (typeof v === "string" ? v : "");
@@ -194,6 +251,20 @@ export const skillRules = defineRules([
       return [f("warn", `${late.length} hard rule(s) sit past the first ~${FOLD_TOKENS} tokens and would not survive compaction (${shown})`, "Restate them in a short Rules section near the top, or move them up. Length is fine; the rules just need to be above the fold. Step-specific detail can move into step files (steps/<step>.md) that are read fresh when the step comes up.")];
     },
   },
+  {
+    // 0.6.0: SKILL.md is instructions, read on every run. The story of the incident that earned
+    // a rule is history: it belongs in MISSES.md, under the miss it records, and SKILL.md keeps
+    // the rule and a one-line why. Anthropic's authoring guidance: avoid time-sensitive content.
+    id: "history-in-skill",
+    level: "skill",
+    check(ctx) {
+      if (broken(ctx)) return [];
+      const hits = historyLines(ctx.body);
+      if (!hits.length) return [];
+      const shown = hits.slice(0, 3).map((h) => `line ${h.lineNo + ctx.bodyStartLine - 1}: ${h.text.slice(0, 70)}`).join("; ");
+      return [f("warn", `${hits.length} dated incident stor${hits.length === 1 ? "y" : "ies"} in SKILL.md (${shown})`, "Move each story into MISSES.md as a miss entry (id, date, what happened, fix, eval, optional quote) and leave the rule plus a one-line why in SKILL.md.")];
+    },
+  },
   {
     id: "navigable",
     level: "skill",

package/src/rules/superskill.mjs

@@ -1,16 +1,19 @@
-// Level 3, "superskill": checked against examples a person approved, fixed every time it
-// got something wrong, and proven recently on a current model against the no-skill baseline.
+// Level 3, "superskill" (0.6.0): fixed every time it got something wrong, with a regression eval
+// for each fix; its whole suite and trigger set pass against the SKILL.md that is here now, on a
+// current model and better than no skill; and it did the job for real people, one-shot, often
+// enough on at least one model+harness. Goldens are optional evidence.
 import { createHash } from "node:crypto";
 import { defineRules } from "./define.mjs";
 import { readGoldens, isApproved, isRealApproved, weightOf, goldenOpts } from "../goldens.mjs";
-import { ledgerPaths, acceptedRate } from "../ledger.mjs";
+import { readRealRuns, meetsBar, knownPair, MIN_REAL_RUNS, MIN_ONE_SHOT } from "../realruns.mjs";
 import { readMisses } from "../misses.mjs";
 import { readEvals, readLatestRun } from "../evals.mjs";
 
 const f = (severity, message, fix) => ({ severity, message, fix });
 const DAY = 86400000;
-export const OPEN_MISS_DAYS = 14;
-export const REAL_USE_DAYS = 30;
+/** Defaults for evals-pass; `--min-pass-rate` / `--min-trigger-rate` change them. */
+export const MIN_PASS_RATE = 0.9;
+export const MIN_TRIGGER_RATE = 0.9;
 /** How long a --run stays fresh, by metadata.cadence. */
 export const FRESH_DAYS = { daily: 30, weekly: 30, monthly: 60, quarterly: 120, yearly: 365 };
 const DEFAULT_FRESH = 30;
@@ -19,55 +22,57 @@ const days = (now, date) => Math.floor((now.getTime() - new Date(date).getTime()
 
 export const superskillRules = defineRules([
   {
+    // 0.6.0: a golden is optional evidence, never the bar. A random accepted run is not the
+    // embodiment of a skill; the misses it absorbed and the evals that hold them are. A golden
+    // that exists is still an eval (its checklist is graded by --run), so its files are checked.
     id: "golden-approved",
     level: "superskill",
     check(ctx, opts = {}) {
       if (ctx.error) return [];
       const goldens = readGoldens(ctx.dir, goldenOpts(ctx, opts));
-      const approvedAny = goldens.filter(isApproved);
-      // 0.5.0: only a golden from a real run a person accepted counts. An invented example, however
-      // careful, puts "a person said this was right" on something no person's work produced, and a
-      // skill could then reach the top level on its author's fiction.
-      const approved = goldens.filter(isRealApproved);
+      if (!goldens.length) return [];
       const out = [];
       const where = (g) => (g.private ? `private golden ${g.id}` : `goldens/${g.id}`);
       for (const g of goldens.filter((x) => x.approvalError))
-        out.push(f("fail", `${where(g)}/APPROVAL.json is not valid JSON`, `Re-record it with \`superskill approve . ${g.id}\`.`));
+        out.push(f("warn", `${where(g)}/APPROVAL.json is not valid JSON`, `Re-record it with \`superskill approve . ${g.id}\`.`));
       for (const g of goldens.filter((x) => x.provenanceError))
-        out.push(f("fail", `${where(g)}/PROVENANCE.json is not valid JSON`, "Rewrite it: source, run, accepted (see SPEC.md, goldens)."));
-      if (!approved.length) {
-        if (approvedAny.length) {
-          const why = approvedAny.map((g) => `${g.id} ${g.origin.why}`).join("; ");
-          out.push(f("fail", `${approvedAny.length} approved golden${approvedAny.length === 1 ? "" : "s"}, none from a real run a person accepted (${why})`, "A golden counts toward superskill only when goldens/<id>/PROVENANCE.json says source: real-run, names the run (session, commit, ledger id, or derived_from for an anonymized twin) and who accepted it and when. Invented examples belong in evals/evals.json, where they hold the skill at tested."));
-        } else {
-          out.push(f("fail", goldens.length ? `${goldens.length} golden${goldens.length === 1 ? "" : "s"}, none approved by a person` : "no goldens", goldens.length ? "A person runs `superskill approve <skill> <golden>` at a terminal (or relays a tap with --approved-by and --via) after checking the output." : "Save a real run's input and the output a person accepted under goldens/<id>/ with PROVENANCE.json, then `superskill approve`."));
-        }
-        return out;
-      }
+        out.push(f("warn", `${where(g)}/PROVENANCE.json is not valid JSON`, "Rewrite it: source, run, accepted (see SPEC.md, goldens)."));
+      for (const g of goldens.filter((x) => !x.expectations.length))
+        out.push(f("info", `${where(g)} has no expectations.json, so --run grades it by likeness to output.md`, "Write goldens/<id>/expectations.json: the behaviors a right answer shows (grade the outcome, not the path). output.md then stays as the reference that proves the task is solvable."));
+      const approved = goldens.filter(isApproved);
+      const real = goldens.filter(isRealApproved);
+      const unreal = approved.filter((g) => !real.includes(g));
+      if (unreal.length) out.push(f("info", `approved golden${unreal.length === 1 ? "" : "s"} not from a real run a person accepted: ${unreal.map((g) => `${g.id} ${g.origin.why}`).join("; ")}`, "Only a golden whose PROVENANCE.json names a real run and who accepted it is evidence of real use; an invented one is an ordinary eval."));
+      if (!real.length) return out;
       const sha = createHash("sha256").update(ctx.raw).digest("hex");
-      const stale = approved.filter((g) => g.approval.skill_sha && g.approval.skill_sha !== sha).map((g) => g.id);
+      const stale = real.filter((g) => g.approval.skill_sha && g.approval.skill_sha !== sha).map((g) => g.id);
       if (stale.length) out.push(f("info", `golden${stale.length === 1 ? "" : "s"} ${stale.join(", ")} approved against an earlier SKILL.md`, "Re-run the golden and re-approve if the output still holds."));
-      // Liked is not proven. Say which weight the approvals carry, so "a person approved it" is
-      // never read as "it worked in the world".
-      const w = approved.map((g) => ({ id: g.id, ...weightOf(g) }));
-      const proven = w.filter((x) => x.outcome > 0);
-      const summary = w.map((x) => `${x.id}: ${x.judgment} judgment, ${x.outcome} outcome`).join("; ");
-      if (!proven.length) out.push(f("info", `approved on judgment only, no outcome recorded yet (${summary})`, "When a golden produces a real result, record it: `superskill approve <skill> <golden> --basis outcome --evidence \"<what happened, where to check>\"`."));
-      else out.push(f("info", `approval weight: ${summary}`, ""));
+      const w = real.map((g) => ({ id: g.id, ...weightOf(g) }));
+      out.push(f("info", `real goldens (optional evidence): ${w.map((x) => `${x.id}: ${x.judgment} judgment, ${x.outcome} outcome`).join("; ")}`, ""));
       return out;
     },
   },
   {
-    // The real number beside the level: of the runs whose next message is recorded, how many did
-    // the person accept. Info only. A level is evidence about examples; this is evidence about use.
-    id: "real-use",
+    // The record from real use, per model and harness. A clean record on one model in one harness
+    // proves nothing about another, so pairs are never pooled: one pair has to clear the bar alone.
+    id: "real-runs",
     level: "superskill",
-    check(ctx, { now = new Date() } = {}) {
+    check(ctx, opts = {}) {
       if (ctx.error) return [];
       const name = (typeof ctx.data?.name === "string" && ctx.data.name) || ctx.folderName;
-      const r = acceptedRate(ledgerPaths(ctx.dir, name), { now, days: REAL_USE_DAYS });
-      if (!r.judged) return [];
-      return [f("info", `real use, last ${REAL_USE_DAYS} days: ${r.accepted} of ${r.judged} judged runs accepted (${pct(r.accepted / r.judged)})${r.synthetic ? `; ${r.synthetic} sandbox run${r.synthetic === 1 ? "" : "s"} not counted` : ""}`, "")];
+      const minRuns = num(opts.minRealRuns, MIN_REAL_RUNS), minOneShot = num(opts.minOneShot, MIN_ONE_SHOT);
+      const bar = `at least ${minRuns} real runs and ${pct(minOneShot)} one-shot on one model+harness`;
+      const realRunsDir = opts.realRuns ?? ctx.realRuns ?? process.env.SUPERSKILL_REAL_RUNS ?? null;
+      const rec = readRealRuns(ctx.dir, { name, realRunsDir });
+      const how = "Export the run record (format superskill-real-runs/1, SPEC.md) to evals/real-runs.json or --real-runs <dir>; Freedom's skill ledger exports it.";
+      if (!rec) return [f("fail", `no real-run record (needs ${bar})`, how)];
+      if (rec.error) return [f("fail", rec.error, how)];
+      const out = rec.pairs.map((p) => f("info", `real runs, ${p.model} / ${p.harness}: ${p.one_shot} of ${p.runs} one-shot${p.runs ? ` (${pct(p.one_shot / p.runs)})` : ""}${knownPair(p) ? "" : ", not counted: the record does not say which model or harness"}`, ""));
+      if (!meetsBar(rec.pairs, { minRuns, minOneShot }).length) {
+        const best = rec.pairs.filter(knownPair)[0];
+        out.push(f("fail", `real-run record below the bar (${bar}; ${rec.where})${best ? `: best is ${best.model} / ${best.harness}, ${best.one_shot} of ${best.runs}` : ": no run names its model and harness"}`, "Use the skill for real and fix what it gets wrong; every correction is a miss to close with an eval."));
+      }
+      return out;
     },
   },
   {
@@ -79,18 +84,17 @@ export const superskillRules = defineRules([
     },
   },
   {
-    id: "no-stale-open-miss",
+    // 0.6.0: every miss is closed. An open miss is a known way the skill fails today, and a skill
+    // that still fails a known way is not at the top level, however recent the miss is.
+    id: "misses-closed",
     level: "superskill",
     check(ctx, { now = new Date() } = {}) {
       if (ctx.error) return [];
       const misses = readMisses(ctx.dir) || [];
-      const out = [];
-      for (const m of misses.filter((x) => x.status === "open")) {
+      return misses.filter((x) => x.status === "open").map((m) => {
         const age = days(now, m.date);
-        if (age > OPEN_MISS_DAYS) out.push(f("fail", `miss ${m.id} open ${age} days (limit ${OPEN_MISS_DAYS}): ${m.what.slice(0, 80)}`, `Fix it, add an eval that catches it, then \`superskill fix <skill> ${m.id} --eval <id>\`.`));
-        else out.push(f("info", `miss ${m.id} open ${age} day${age === 1 ? "" : "s"}`, `Fix within ${OPEN_MISS_DAYS} days of ${m.date}.`));
-      }
-      return out;
+        return f("fail", `miss ${m.id} is open (${age} day${age === 1 ? "" : "s"}): ${m.what.slice(0, 80)}`, `Fix it, add an eval that catches it, then \`superskill fix <skill> ${m.id} --eval <id>\`.`);
+      });
     },
   },
   {
@@ -108,6 +112,39 @@ export const superskillRules = defineRules([
         .map((m) => f("fail", m.eval ? `miss ${m.id} names eval "${m.eval}", which is not in evals.json or goldens/` : `miss ${m.id} is fixed with no regression eval`, `Add a case to evals/evals.json that would catch ${m.id} again, and name its id on the Eval line.`));
     },
   },
+  {
+    // The suite and the trigger set pass against the SKILL.md that is here now. A pass recorded
+    // against an earlier SKILL.md proves the earlier skill.
+    id: "evals-pass",
+    level: "superskill",
+    check(ctx, opts = {}) {
+      if (ctx.error) return [];
+      const r = readLatestRun(ctx.dir);
+      if (!r.run) return [];
+      const run = r.run;
+      const out = [];
+      const sha = createHash("sha256").update(ctx.raw).digest("hex");
+      if (!run.skill_sha) out.push(f("fail", "latest.json does not say which SKILL.md it ran against (no skill_sha)", "Re-run `superskill doctor <skill> --run` with superskill 0.6.0 or later."));
+      else if (run.skill_sha !== sha) out.push(f("fail", "the last --run was against an earlier SKILL.md", "Re-run `superskill doctor <skill> --run`; a change to the skill needs its evals re-run."));
+      const minPass = num(opts.minPassRate, MIN_PASS_RATE), minTrig = num(opts.minTriggerRate, MIN_TRIGGER_RATE);
+      const w = Number(run.with_skill?.pass_rate);
+      if (Number.isFinite(w) && w < minPass) out.push(f("fail", `the suite passed ${pct(w)} of runs with the skill (needs ${pct(minPass)})`, "Read the failures in latest.json per_case, fix the skill, re-run."));
+      // Every fixed miss's regression eval passes every run: a regression that comes back half the
+      // time has come back.
+      const fixed = (readMisses(ctx.dir) || []).filter((m) => m.status === "fixed" && m.eval);
+      const cases = new Map((Array.isArray(run.per_case) ? run.per_case : []).map((c) => [String(c.id), c]));
+      for (const m of fixed) {
+        const c = cases.get(String(m.eval)) || cases.get(`golden:${m.eval}`);
+        if (!c) { if (run.skill_sha) out.push(f("fail", `regression eval ${m.eval} (miss ${m.id}) is not in the last --run`, "Re-run `superskill doctor <skill> --run`.")); continue; }
+        const ws = c.with_skill || {};
+        if (!(ws.runs > 0 && ws.passes === ws.runs)) out.push(f("fail", `regression eval ${m.eval} (miss ${m.id}) passed ${ws.passes || 0} of ${ws.runs || 0} runs`, `Miss ${m.id} is back: fix the skill until its eval passes every run.`));
+      }
+      const t = run.triggers;
+      if (!t || !Number.isFinite(Number(t.pass_rate))) out.push(f("fail", "the last --run did not run the trigger evals", "Re-run `superskill doctor <skill> --run` with superskill 0.6.0 or later; it runs evals/triggers.json too."));
+      else if (Number(t.pass_rate) < minTrig) out.push(f("fail", `trigger evals ${pct(Number(t.pass_rate))} right (needs ${pct(minTrig)})`, "Read triggers.per_query in latest.json: sharpen the description so it loads when it should and not otherwise."));
+      return out;
+    },
+  },
   {
     id: "run-evidence",
     level: "superskill",
@@ -146,3 +183,4 @@ export const superskillRules = defineRules([
 ]);
 
 const pct = (x) => `${Math.round(x * 100)}%`;
+const num = (v, d) => (v === undefined || v === null || v === "" || !Number.isFinite(Number(v)) ? d : Number(v));

package/src/run/claude.mjs

@@ -35,3 +35,32 @@ export function ask(prompt, { model } = {}) {
   if (model) args.push("--model", model);
   return call(args, cwd).output;
 }
+
+/**
+ * Did Claude Code load the skill for this query? Run headless with the skill installed and read
+ * the stream: a Skill tool call naming it, or a Read of its SKILL.md, is a load.
+ */
+export function loadedSkill(stream, skillName) {
+  for (const line of String(stream).split("\n")) {
+    if (!line.trim().startsWith("{")) continue;
+    let ev; try { ev = JSON.parse(line); } catch { continue; }
+    const content = ev?.message?.content;
+    if (!Array.isArray(content)) continue;
+    for (const c of content) {
+      if (c?.type !== "tool_use") continue;
+      const input = c.input || {};
+      if (c.name === "Skill" && [input.skill, input.command, input.name].some((v) => typeof v === "string" && v.split(":").pop() === skillName)) return true;
+      if (typeof input.file_path === "string" && input.file_path.endsWith(`/${skillName}/SKILL.md`)) return true;
+    }
+  }
+  return false;
+}
+
+export function triggerCase({ skillDir, skillName, query, model }) {
+  const cwd = prepareWorkspace({ skillDir, skillName, linkAt: ".claude/skills" });
+  const args = ["-p", query, "--output-format", "stream-json", "--verbose", "--add-dir", cwd];
+  if (model) args.push("--model", model);
+  const r = spawnSync("claude", args, { cwd, env: sandboxEnv(), encoding: "utf8", maxBuffer: 64 * 1024 * 1024, timeout: 15 * 60 * 1000 });
+  if (r.error) throw Object.assign(new Error(`claude failed to start: ${r.error.message}`), { code: "SUPERSKILL" });
+  return { triggered: loadedSkill(r.stdout, skillName), failed: r.status !== 0 && !r.stdout, cwd };
+}

package/src/run/codex.mjs

@@ -31,3 +31,17 @@ export function ask(prompt, { model } = {}) {
   const cwd = prepareWorkspace({ skillDir: null, skillName: null });
   return call(prompt, cwd, model).output;
 }
+
+/**
+ * Did Codex load the skill for this query? Codex reads a skill's SKILL.md when it uses it, so the
+ * JSON event stream mentioning <name>/SKILL.md is a load.
+ */
+export function triggerCase({ skillDir, skillName, query, model }) {
+  const cwd = prepareWorkspace({ skillDir, skillName, linkAt: ".agents/skills" });
+  const args = ["exec", "--json", "--skip-git-repo-check", "-C", cwd];
+  if (model) args.push("-m", model);
+  args.push(query);
+  const r = spawnSync("codex", args, { cwd, env: sandboxEnv(), encoding: "utf8", maxBuffer: 64 * 1024 * 1024, timeout: 15 * 60 * 1000 });
+  if (r.error) throw Object.assign(new Error(`codex failed to start: ${r.error.message}`), { code: "SUPERSKILL" });
+  return { triggered: String(r.stdout).includes(`${skillName}/SKILL.md`), failed: r.status !== 0 && !r.stdout, cwd };
+}

package/src/run/fake.mjs

@@ -1,6 +1,6 @@
 // A stand-in harness for tests: SUPERSKILL_FAKE_HARNESS names a node script that reads one
-// JSON request on stdin ({mode: "case"|"ask", prompt, withSkill, cwd}) and prints
-// {output, tokens?, model?}. Never calls a model.
+// JSON request on stdin ({mode: "case"|"ask"|"trigger", prompt|query, withSkill, cwd}) and
+// prints {output, tokens?, model?} (or {triggered} for a trigger). Never calls a model.
 import { spawnSync } from "node:child_process";
 import { prepareWorkspace } from "./workspace.mjs";
 import { sandboxEnv } from "./env.mjs";
@@ -22,6 +22,11 @@ export function create(script) {
       const cwd = prepareWorkspace({ skillDir, skillName, files, linkAt: withSkill ? ".claude/skills" : null });
       return { ...call(script, { mode: "case", prompt, withSkill, cwd }), cwd };
     },
+    triggerCase({ skillDir, skillName, query }) {
+      const cwd = prepareWorkspace({ skillDir, skillName, linkAt: ".claude/skills" });
+      const doc = JSON.parse(spawnSync(process.execPath, [script], { input: JSON.stringify({ mode: "trigger", query, cwd }), env: sandboxEnv(), encoding: "utf8" }).stdout || "{}");
+      return { triggered: Boolean(doc.triggered), failed: false, cwd };
+    },
     ask(prompt) {
       return call(script, { mode: "ask", prompt }).output;
     },

package/src/run/index.mjs

@@ -8,7 +8,8 @@ import { createInterface } from "node:readline/promises";
 import { clock, UsageError } from "../args.mjs";
 import { findSkills } from "../doctor.mjs";
 import { parseSkillFile } from "../frontmatter.mjs";
-import { readEvals } from "../evals.mjs";
+import { readEvals, readTriggers } from "../evals.mjs";
+import { createHash } from "node:crypto";
 import { readGoldens } from "../goldens.mjs";
 import { grade, isMachineCheck } from "./grade.mjs";
 import * as claude from "./claude.mjs";
@@ -18,7 +19,9 @@ import { create as createFake } from "./fake.mjs";
 export const help = `superskill doctor <skill> --run [--harness claude|codex] [--repeat 3] [--model <id>] [--yes]
 
 Run the skill's evals for real: every case in evals/evals.json and every golden, --repeat
-times with the skill and --repeat times without it, through a headless harness. Machine
+times with the skill and --repeat times without it, and every query in evals/triggers.json
+--repeat times with the skill installed (did it load when it should, and not otherwise),
+through a headless harness. Machine
 checks (contains:, regex:, file_exists:) are free; each plain-language expectation costs
 one grader call per run. Prints the estimated number of model calls first, and asks
 before starting (or needs --yes when there is no terminal). Writes
@@ -45,15 +48,51 @@ export function collectCases(skillDir, { privateGoldens = process.env.SUPERSKILL
   if (e.error) throw new UsageError(e.error);
   const cases = e.cases.filter((c) => c.prompt.trim()).map((c) => ({ id: String(c.id), prompt: c.prompt, files: c.files, assertions: c.assertions.length ? c.assertions : [c.expected_output].filter(Boolean) }));
   for (const g of readGoldens(skillDir, { privateGoldens, name })) {
-    if (!g.input || !g.output || !g.output.trim()) continue;
-    cases.push({ id: `golden:${g.id}`, prompt: g.input, files: [], assertions: [`The output matches this approved output in substance (same facts, same shape; wording may differ):\n${g.output}`] });
+    if (!g.input || !((g.output && g.output.trim()) || g.expectations?.length)) continue;
+    // 0.6.0: grade the outcome, not the path. A golden with a checklist is graded on it; one
+    // without falls back to likeness with its reference output.
+    const assertions = g.expectations?.length ? g.expectations : [`The output matches this approved output in substance (same facts, same shape; wording may differ):\n${g.output}`];
+    cases.push({ id: `golden:${g.id}`, prompt: g.input, files: [], assertions });
   }
   return cases;
 }
 
-export function estimateCalls(cases, repeat) {
+export function estimateCalls(cases, repeat, triggers = 0) {
   const graded = cases.reduce((n, c) => n + c.assertions.filter((a) => !isMachineCheck(a)).length, 0);
-  return { runs: cases.length * repeat * 2, grader: graded * repeat * 2, total: cases.length * repeat * 2 + graded * repeat * 2 };
+  const runs = cases.length * repeat * 2 + triggers * repeat;
+  return { runs, grader: graded * repeat * 2, triggers: triggers * repeat, total: runs + graded * repeat * 2 };
+}
+
+/** The trigger queries the run will check, from evals/triggers.json. */
+export function collectTriggers(skillDir) {
+  const t = readTriggers(skillDir);
+  if (t.error) throw new UsageError(t.error);
+  return t.triggers;
+}
+
+/**
+ * Run every trigger query `repeat` times with the skill installed and record whether the harness
+ * loaded it. A query passes a run when loading matched should_trigger.
+ */
+export function runTriggers(skillDir, { harness, repeat, model, log = () => {} }) {
+  const skillName = parseSkillFile(readFileSync(join(skillDir, "SKILL.md"), "utf8")).data.name || "";
+  const queries = collectTriggers(skillDir);
+  if (!queries.length) return null;
+  if (typeof harness.triggerCase !== "function") throw new UsageError(`harness ${harness.name} cannot run trigger evals`);
+  let runs = 0, passes = 0;
+  const per_query = [];
+  for (const q of queries) {
+    const row = { query: q.query, should_trigger: q.should_trigger, runs: 0, passes: 0 };
+    for (let i = 0; i < repeat; i++) {
+      log(`trigger "${q.query.slice(0, 40)}", run ${i + 1}/${repeat}`);
+      const r = harness.triggerCase({ skillDir, skillName, query: q.query, model });
+      if (r.cwd) rmSync(r.cwd, { recursive: true, force: true });
+      const ok = !r.failed && Boolean(r.triggered) === q.should_trigger;
+      row.runs++; row.passes += ok ? 1 : 0; runs++; passes += ok ? 1 : 0;
+    }
+    per_query.push(row);
+  }
+  return { cases: queries.length, runs, passes, pass_rate: runs ? round(passes / runs) : 0, per_query };
 }
 
 export function runEvals(skillDir, { harness, repeat = 3, now = new Date(), model, log = () => {} }) {
@@ -84,7 +123,10 @@ export function runEvals(skillDir, { harness, repeat = 3, now = new Date(), mode
     per_case.push(row);
   }
   const summary = (t) => ({ pass_rate: t.runs ? round(t.passes / t.runs) : 0, mean_ms: t.runs ? Math.round(t.ms / t.runs) : 0, mean_tokens: t.tokenRuns ? Math.round(t.tokens / t.tokenRuns) : null });
-  const result = { run_at: now.toISOString(), harness: harness.name, model: seenModel, cases: cases.length, repeat, with_skill: summary(totals.with_skill), without_skill: summary(totals.without_skill), per_case };
+  const triggers = runTriggers(skillDir, { harness, repeat, model, log });
+  // 0.6.0: the run says which SKILL.md it proved, so a later edit cannot ride on an old pass.
+  const skill_sha = createHash("sha256").update(readFileSync(join(skillDir, "SKILL.md"), "utf8")).digest("hex");
+  const result = { run_at: now.toISOString(), harness: harness.name, model: seenModel, skill_sha, cases: cases.length, repeat, with_skill: summary(totals.with_skill), without_skill: summary(totals.without_skill), per_case, ...(triggers ? { triggers } : {}) };
   mkdirSync(join(skillDir, "evals", "results"), { recursive: true });
   writeFileSync(join(skillDir, "evals", "results", "latest.json"), JSON.stringify(result, null, 2) + "\n");
   return result;
@@ -100,11 +142,11 @@ export async function runCommand(a) {
   const harness = pickHarness(a.flags.harness);
   const dirs = a._.flatMap((p) => findSkills(p));
   if (!dirs.length) throw new UsageError(`no skills found under ${a._.join(", ")}`);
-  const plan = dirs.map((d) => ({ dir: d, cases: collectCases(d) }));
-  const calls = plan.reduce((n, p) => n + estimateCalls(p.cases, repeat).total, 0);
+  const plan = dirs.map((d) => ({ dir: d, cases: collectCases(d), triggers: collectTriggers(d).length }));
+  const calls = plan.reduce((n, p) => n + estimateCalls(p.cases, repeat, p.triggers).total, 0);
   for (const p of plan) {
-    const e = estimateCalls(p.cases, repeat);
-    process.stderr.write(`${p.dir}: ${p.cases.length} cases x ${repeat} x 2 = ${e.runs} runs + ${e.grader} grader calls\n`);
+    const e = estimateCalls(p.cases, repeat, p.triggers);
+    process.stderr.write(`${p.dir}: ${p.cases.length} cases x ${repeat} x 2 + ${p.triggers} triggers x ${repeat} = ${e.runs} runs + ${e.grader} grader calls\n`);
   }
   process.stderr.write(`estimated model calls: ${calls} through ${harness.name}\n`);
   if (!a.flags.yes) {
@@ -122,7 +164,7 @@ export async function runCommand(a) {
   for (const p of plan) {
     const r = runEvals(p.dir, { harness, repeat, now, model: a.flags.model, log: (m) => process.stderr.write(`  ${m}\n`) });
     results.push({ path: p.dir, ...r });
-    if (!a.flags.json) process.stdout.write(`${p.dir}\n  with skill ${pct(r.with_skill.pass_rate)}  without ${pct(r.without_skill.pass_rate)}  (${r.cases} cases x ${repeat})\n  wrote evals/results/latest.json\n`);
+    if (!a.flags.json) process.stdout.write(`${p.dir}\n  with skill ${pct(r.with_skill.pass_rate)}  without ${pct(r.without_skill.pass_rate)}  (${r.cases} cases x ${repeat})${r.triggers ? `\n  triggers ${pct(r.triggers.pass_rate)} right (${r.triggers.cases} queries x ${repeat})` : ""}\n  wrote evals/results/latest.json\n`);
   }
   if (a.flags.json) process.stdout.write(JSON.stringify({ results }, null, 2) + "\n");
   return results.every((r) => r.with_skill.pass_rate > r.without_skill.pass_rate) ? 0 : 1;

package/src/snippet.md

@@ -5,12 +5,14 @@ Skills in this project are held to the superskill standard: https://supersuit.wi
 - **After doing a job by hand once, propose a skill for it.** If the person agrees, write the
   skill, then seed its evidence from this session:
   `npx @supersuit/superskill init <skill-folder> --from-session <this session's transcript>`
-  The golden it creates waits for the person to approve it; never approve it yourself.
+  The golden it creates is optional evidence and waits for the person; never approve it yourself.
 - **Whenever a skill needed correcting** (the person redirected you, fixed its output, or you
   worked around it), log it before moving on:
   `npx @supersuit/superskill miss <skill-folder> "<what happened>" --expected "<what should have>"`
   When you fix it, add an eval that would catch it again and close it with
   `npx @supersuit/superskill fix <skill-folder> <miss-id> --eval <eval-id>`.
+- **The story goes in MISSES.md, never in SKILL.md.** SKILL.md holds the rule and a one-line
+  why; what happened, when, and what the person said go on the miss entry (`--quote`).
 - **Before calling a skill done**, run
   `npx @supersuit/superskill doctor <skill-folder>`
   and fix everything it lists for the level the skill is meant to reach.