sheleg-design-skill 1.61.3 → 1.63.0

package/CHANGELOG.md

@@ -1,3 +1,151 @@
+## 1.63.0 — the director record is a file with a validator, and a flagship is scored on a rubric that says where it came from
+
+The director's output was a prose block at the end of `CREATIVE_DIRECTOR.md`: nothing
+held it, so a brief with no falsifier, a taste of "modern, clean", a fork judged by a
+rubric written afterwards and a `Markers` line nobody ran all passed as a record. The
+plan's pipeline (contracts K3, K6, K7) needs a record the next stage can check, and a
+quality bar for flagship surfaces that is more than the measurable table.
+
+- **D3 — `templates/director-record.md` and `npx sheleg-design-skill --check-record
+  <file> [--json]`.** A header with `surface_class` (`flagship`, `product`,
+  `internal`, `ad`) and sixteen `## <Field>` headings: Brief, Mode, Taste, References,
+  Cast, Fork, Rubric, Critique, Markers, Alignment, Quality, Signature, Surfaces,
+  Haptics, ADA, Open. A flagship owes all sixteen; a product screen Brief, Mode,
+  References, Markers, Open; an internal tool Brief, Mode, Markers, Open; an ad Brief,
+  Mode, Taste, References, Markers, Signature, ADA, Open. Each owed field is held to
+  its rule: Brief needs Surface, Job, Constraint and Falsifier; Taste needs `Take:` and
+  `Ban:` lines with something other than generic words (English and Russian); References
+  needs five real-product URLs each with `take:`, or `none found` with `Searched:`;
+  `Fork: yes` needs a Rubric section it names, `A:`/`B:` and a `Winner:`; Rubric three
+  criteria; Critique region → defect → change triples or `clean render`; Markers a
+  `--lint` run with its revision and counts, and no S1; Signature exactly one moment
+  with What/Where/Why; ADA the class profile, every G item passing, at most two J FAIL
+  on a flagship, no J PASS without a `Labelled set:`, safe zones on an ad. Guidance
+  lives in HTML comments, so a copied template fails until it is filled. `Mode:
+  declined` with its reason passes on its own. Exit 0 valid, 1 violations as
+  `<Field>: <problem>`, 2 usage. `bin/record.js`, Node, no dependencies; its rules
+  join `--self-test`. The prose block in `CREATIVE_DIRECTOR.md` is replaced by a
+  pointer to both, keeping the doctrine on `Open`.
+- **K6 — `ADA_RUBRIC.md`.** R1–R25, each binary, typed G (a gate no judge outvotes),
+  J (a judge on a per-task checklist) or H (the human on the contact sheet), with
+  applicability and how to verify (tool → artifact). Profiles: flagship all 25, every
+  G PASS and at most two J FAIL with reasons; product the G items R1, R3–R5, R8, R9,
+  R12–R17, R19, R20, R22; ad R7, R8, R10, R11, R14, R18, R21, R22 plus safe zones. The
+  judge: a checklist per task, pairwise only against an approved reference in both
+  orders, three samples, disagreement `uncertain` to the human, J items NOT_ASSESSED
+  until a labelled set exists, never above a G-FAIL, and never the agent that
+  rendered the surface. Every FAIL is a triple. **The file says plainly that the
+  rubric is derived and Apple publishes none**, and cites Apple's award pages with
+  the date they were read. Linked from Act 5 and `SKILL.md`.
+- **D4 — the reference sweep is mandatory** for a new design and a redesign of a brand
+  or flagship surface (Act 2, `APPLYING.md`, `SKILL.md`), through whichever reference
+  servers the session exposes — Refero, Lazyweb, Mobbin where authorized — with an
+  empty result recorded as `none found` and where it looked.
+- **First time right**, a new section of `CREATIVE_DIRECTOR.md`: decisions before
+  pixels in the record; the forbidden list loaded into context and the linter run;
+  one key screen in one state first; feedback only external and specific; a
+  re-render budget of one, at most two, then `unresolved` to the person; the
+  generator is not the judge.
+- **D5 — `MOTION_DOCTRINE.md` §12, reviewing motion:** a frame strip and a run video,
+  timings judged by one `DUR-*` row each, reduced motion turned on and captured again,
+  one moment per viewport; `npx hyperframes snapshot` / `compare` as the evidence for a
+  rendered file (compare is a review surface, not a gate); `review-animations` by name.
+  It feeds the record's Quality and Critique.
+- **D6 — `FIGMA_BRIDGE.md` §3 re-drawn.** "Motion stays in code — Figma has no easing
+  variable type" was no longer true: the official Figma plugin (2.2.120) documents
+  TIMING and EASING variables, keyframes, animation styles and `get_motion_context`
+  snippets. Durations and curves can now be published; motion read back is held to
+  the doctrine (Figma's `EASE_IN`, `…_BACK` and `BOUNCY` are banned forms in UI); the
+  scroll clock, scrubbed motion and the reduced-motion branch stay in code. Read from
+  the plugin's documentation, not confirmed by a call (B-144). New §5: a frame is
+  critiqued — `get_screenshot`, the record's rubric, triples, `get_variable_defs` —
+  before anyone approves it; and one Figma file per surface (App / Web / ASO). README,
+  the Cursor rule and `DESIGN_SYNC_BRIDGE.md` follow.
+- **D10 — the taste profile** is the record's `Taste` field and a guide in the template
+  (what we take, what we ban, anti-patterns, the three dials); Act 1 writes it beside
+  the brief. A profile of "modern / clean" is empty. A personal profile's content stays
+  with its owner.
+- **`MOBILE_SURFACES.md`, the axes matrix:** states × viewport × theme × text size ×
+  locale, pairwise coverage plus the mandatory pairs dark × largest text and RTL ×
+  narrowest viewport, a capture record per cell, the commands that set each axis; the
+  native state matrix is its native case, and a web render still proves no native cell.
+- **D8 — `evals/render/`:** four fixed briefs (landing hero with motion, mobile
+  onboarding, product dashboard, paywall) and a runner that counts linter findings by
+  severity, validates each director record, and scores the G items source can decide
+  (R8, R20, R24), reporting the rest NOT_RUN; `--write` appends a dated row to
+  `test/evals/RESULTS.md`, whose new section states the method. The model generation
+  step is NOT_RUN in CI; the harness row on the hand-written sample is recorded as
+  such (B-142).
+- **B-140 — the kits obey their own floor.** `workbench`'s progress fill slides by a
+  translate instead of transitioning `width`, `paperclip`'s lane mark grows by a scale
+  instead of `width`/`height`, both rendered before and after with the same geometry;
+  `deskmate`'s gradient word carries its waiver and reason. `node bin/cli.js --lint
+  kits` runs in `npm test` and in CI: 0 S1.
+- **Provenance:** a new table for sources with no commit to pin — Apple's award pages,
+  the judge papers, the Figma plugin's motion skills and the HyperFrames CLI skill,
+  each `derived`, dated, with SHA256 where a file was read.
+- **Gates:** `test/record_test.js` (49 cases through the real CLI, every rule watched
+  failing on one planted defect before `bin/record.js` existed); `validate_director_record()`
+  and `validate_ada_rubric()` with three plants; `test/render_eval_test.js` on the sample.
+
+The `SKILL.md` body is 4747/4750 tokens: the new load-on-demand line was paid for by
+tightening the READ FIRST paragraph and the references section.
+
+## 1.62.0 — a visual floor with reasons and exceptions, and a linter that reads a project against it
+
+Generated design kept shipping through reviews that had nothing to point at.
+`CREATIVE_DIRECTOR.md` had refused impeccable's fixed style bans, rightly, because a
+ban that cannot lose an argument contradicts "an explicit user requirement beats the
+baseline"; what it left was no floor at all. Two private production codebases read
+on 2026-10-07 carried emoji standing in for icons, overshoot curves, a side-stripe
+alert card and layout-property transitions, all found by audits after the fact.
+
+- **`SLOP_MARKERS.md`, the visual floor (catalogue version 2026-10-07).** 49 markers
+  `V001`–`V049` in eight groups (color, type, layout, icon-decor, content, motion,
+  mobile, platform), each with severity S1–S3, the tell, why it reads as a default,
+  what a designer does instead, how it is checked, the exception under which it is
+  not slop, and a commit-pinned or dated source. The floor holds with `Style pack:
+  none`; a pack may tighten it and never loosen it; a brief that asks for a marked
+  pattern wins once the director record names the marker. The three default looks
+  are markers V012, V013 and V026, and the `SHELEG_DESIGN.md` section now points
+  there. Copy tells stay with `copywriting`; no punctuation rule is adopted (in
+  Russian the em dash is normative).
+- **`npx sheleg-design-skill --lint <dir> [--json] [--ratchet <budget.json>]
+  [--include-tests]`.** Twenty rules, one per `lint:` row: purple gradients,
+  gradient text, decorative glass, glows, the side stripe, grid and stripe
+  backgrounds, grey on colour, uniform card chrome, raw colour (under `--ratchet`),
+  default faces, emoji as icons (in markup and in data such as `icon: "📊"`, never
+  in prose), sparkles, fade-in on every section, overshoot curves, `transition:
+  all`, layout-property animation, `scale(0)`, `ease-in` and a missing reduced-motion
+  path. Exit 0 no S1, 1 an S1 or a file over its budget, 2 a usage error; S2 and S3
+  print and never block. Tests, dependencies, build output, hidden directories,
+  comments and a copied pack token layer's measured tokens are not reported. A
+  recorded exception is `sheleg-lint-allow: V0NN <reason>`, and a bare id waives
+  nothing. Written in Node like the installer, so it runs wherever `npx` does.
+- **D9, decided.** `CREATIVE_DIRECTOR.md` records markers-not-bans in place of the
+  old refusal, and the director's record gains a `Markers` line (the lint run and
+  each waived marker with the line that earned it).
+- **The lane references follow the umbrella's design pack.** A new design enters at
+  `references`; a redesign at `verify` + `visual-qa` + `a11y`; an update at
+  `tokens`, then `visual-qa`; an audit runs `a11y → verify → visual-qa → speed`; the
+  `--lane` list names `references`, `critique`, `visual-qa` and `speed`.
+- **Provenance, 16 → 20 rows**, all `derived`: impeccable's detector catalogue,
+  craft floor and motion reference at `12b25ae`, and `anthropics/skills`
+  `frontend-design` at `41bbe19`. Nothing was copied.
+- **Gates.** `validate_slop_markers()` holds the catalogue's shape and required
+  markers, and rule, id and severity in both directions between `bin/lint.js` and the
+  catalogue, with three plants; `test/lint_test.js` runs the real CLI on throwaway
+  trees (every S1 rule blocking, every quiet case quiet, the ratchet, the exit
+  contract); `--self-test` plants a defect and a clean twin for every rule.
+
+Calibrated on the two private codebases (read-only): 107 S1 / 18 S2 and 83 S1 / 5 S2,
+every listed defect found, the two test-fixture hits impeccable's detector reported
+absent by default and present under `--include-tests`. One false-positive class found
+there (a bare `"back"` string read as an ease) was fixed with a regression case. The
+same run over this repository's kits found two layout transitions of its own (B-140).
+The `SKILL.md` body is 4742/4750 tokens. Whether models produce fewer markers with the
+floor loaded was not measured (plan task D8).
+
 ## 1.61.3 — every borrowed rule names its source, and the motion tools agree with the doctrine
 
 `MOTION_DOCTRINE.md` §1–4 is Emil Kowalski's animation doctrine almost word for word

package/README.md

@@ -175,6 +175,9 @@ skills.
 | `SKILL.md` | The agent-facing skill: discovery triggers, the principles, how to apply them, quick-reference rules, common mistakes |
 | `SHELEG_DESIGN.md` | The full reference: architecture, layer-by-layer mechanics with code, the exact morph math, the DOM↔WebGL projection bridge, a build-from-scratch recipe, and why each piece works |
 | `SURFACE_COMPOSITION.md` | Two decisions the pack layer does not make: the six depth layers of a scene, read before writing CSS for a cinematic page; and the handoff to `dataviz`, read before drawing a chart in any pack — token names are not uniform across the thirteen and an undefined custom property fails silently |
+| `SLOP_MARKERS.md` | The visual floor: 49 markers of generated design (purple gradients, emoji as icons, default faces, the side stripe, the three default looks, banned motion forms…), each with severity, reason, what to do instead and the exception under which it is not slop. Holds with or without a pack; twenty of them are checked by `--lint` |
+| `ADA_RUBRIC.md` | 25 binary checks derived from the Apple Design Awards categories (Apple publishes no rubric; the file says so and cites the pages it read), each typed as a deterministic gate, a judged item or a human one, with profiles for flagship, product and ad surfaces and the rules that keep a model judge honest |
+| `templates/director-record.md` | The director record: one `## <Field>` per decision — brief, taste, references, fork and rubric, critique, markers, signature moment, ADA verdict, what is left open — filled before the first render and checked by `--check-record` |
 | `MOTION_DOCTRINE.md` | Whether to animate at all, before how: the frequency table that kills motion on high-repetition paths, the easing tree and the `ease-in` ban, the duration ceiling, the forbidden forms, and the reduced-motion contract. `SKILL.md` marks it required before any animation |
 | `MOTION_PRODUCTION.md` | What changes when motion leaves the page as a file: the four things a rendered asset gives up, the two programmatic-video tools measured side by side with the licence threshold and the pre-1.0 risk stated, which one this library recommends and the three conditions that reverse it, how a pack's token layer crosses the render seam, and where the reduced-motion obligation lands once there is no user to read a media query |
 | `DESIGN_SYNC_BRIDGE.md` | The Claude Design contract: what a pack sends to claude.ai/design and in what shape, the rule for each of the four reference types, and the border motion does not cross |
@@ -184,6 +187,48 @@ skills.
 | `styles/tokens/*.css` | The ready-made token layer per pack, copied verbatim instead of transcribed (`workbench` and `field-notes` each ship a light `:root` plus a `data-theme="dark"` twin) |
 | `styles/STYLE_PACK_TEMPLATE.md` | The pack contract as a skeleton, so a new style is authored against the same headings rather than improvised |
 
+### Check a project against the floor
+
+```bash
+npx sheleg-design-skill --lint ./src            # human report, exit 1 on any S1
+npx sheleg-design-skill --lint ./src --json     # [{id, rule, severity, file, line, snippet}]
+npx sheleg-design-skill --lint ./src --ratchet sloplint-budget.json   # per-file budgets that only fall
+```
+
+The linter reads `html`, `css`, `scss`, `js`, `jsx`, `ts`, `tsx`, `vue`, `svelte`
+and `astro`, skips dependencies, build output, hidden directories and tests
+(`--include-tests` reads them), and checks the `lint:` rows of
+[`SLOP_MARKERS.md`](plugins/sheleg-design/skills/sheleg-design/SLOP_MARKERS.md):
+emoji used as icons (in markup and in data such as `icon: "📊"`), purple
+gradients, gradient text, a default face with no declared reason, decorative
+glass, the side stripe, glows, grid backgrounds, grey on colour, `transition: all`,
+layout-property animation, `scale(0)`, `ease-in`, overshoot curves and a missing
+`prefers-reduced-motion` path. Exit 0 means no S1 finding, 1 an S1 finding or a
+file over its budget, 2 a usage error; S2 and S3 print and never block. A
+recorded exception is a comment, `sheleg-lint-allow: V015 <reason>`, and the
+reason is required. `--self-test` plants a defect for every rule. It is a pattern
+reader, not a renderer: the catalogue's `review` rows stay with the render
+critique.
+
+### Check a director record
+
+```bash
+npx sheleg-design-skill --check-record docs/design/pricing/director-record.md
+npx sheleg-design-skill --check-record docs/design/pricing/director-record.md --json
+```
+
+A design's decisions live in a record before the first pixel: a header with
+`surface_class` (`flagship`, `product`, `internal` or `ad`) and one `## <Field>`
+per decision, from the template in the installed skill. The class decides which
+fields are owed — a flagship all sixteen, a product screen Brief, Mode,
+References, Markers and Open — and each owed field is held to its rule, not just
+its presence: a taste profile of "modern, clean" is empty, five references on
+placeholder hosts are none, `Fork: yes` with no rubric compared nothing,
+`Markers` must cite a `--lint` run with its revision and counts, and a flagship's
+ADA verdict fails on any G item. A refusal is a record too: `Mode: declined` with
+its reason passes. Exit 0 valid, 1 with each violation as `<Field>: <problem>`,
+2 a usage error.
+
 ## What you get out of it
 
 - **A motion methodology, not a component dump.** Scroll-linked animation,
@@ -231,9 +276,10 @@ values *onto* the pack's tokens instead of inlining hexes.
 The bridge is specific because the traps are: `workbench`'s light and dark are
 two **modes of one collection**, while `editorial-luxury`'s espresso sections
 are surfaces and not a mode at all; Figma colors are 0..1 floats, not hex; and
-motion never crosses — Figma has no easing variable type, so the ease, durations
-and stagger stay code-only, and shadows are effect styles whose parts bind to
-variables. A value in a file with no matching token is either a gap in the pack
+motion crosses only in part — durations and curves publish as Figma's TIMING and
+EASING variables, but the scroll clock, scrubbed motion and the reduced-motion branch
+stay code-only, and motion read back from a file is held to the doctrine — and
+shadows are effect styles whose parts bind to variables. A value in a file with no matching token is either a gap in the pack
 or drift in the file — the one thing it is never is a literal in a component.
 
 ## Claude Design, in one direction
@@ -259,18 +305,22 @@ stops an agent inventing motion to fill the silence.
 The kits are not part of the install. `--kit` fetches one on demand, which is how
 the skill stays documentation while still having real components to hand.
 
-## Optional: Lazyweb MCP
+## Reference sweeps (Refero, Lazyweb, Mobbin)
 
 A style pack locks *how it looks*. It says nothing about what a good version of
-the screen you're about to build actually **contains**. If the
-[Lazyweb](https://www.lazyweb.com) MCP server is connected, the skill sweeps
-real-world references for the target screen (signup, onboarding, paywall,
-pricing, checkout, dashboard, settings) before laying anything out.
+the screen you're about to build actually **contains**. For a new design or a
+redesign of a brand or flagship surface the sweep is not optional: through
+whichever reference servers are connected — Refero, [Lazyweb](https://www.lazyweb.com),
+Mobbin where the account is authorized — the skill looks at five or more shipped
+products for the target screen (signup, onboarding, paywall, pricing, checkout,
+dashboard, settings) before laying anything out, and records what it takes from
+each. An empty sweep is recorded as `none found` with where it looked.
 
 The division of labor keeps the result one system: references inform **layout,
 hierarchy and content order**; palette, type and motion stay the pack's. Setup
 is a Streamable HTTP MCP server plus a per-user token — keep it out of your
-repo. Entirely optional; without it the skill works from the pack alone.
+repo. Without any reference server the sweep runs on the open web, and the
+record says the servers were absent.
 
 ## Development
 
@@ -282,8 +332,8 @@ These run **in a clone of this repository**. The published npm package ships no
 python3 test/validate.py   # or: npm test
 ```
 
-`npm test` is **four gates**, not one, and `validate.py` alone is about a third
-of the contract:
+`npm test` is **several gates**, not one, and `validate.py` alone is about a
+third of the contract:
 
 | Gate | What it decides |
 |---|---|
@@ -291,6 +341,11 @@ of the contract:
 | `test/validate_palette.py` | contrast floors and semantic separation per theme, including three simulated dichromacies · AI-default-cluster provenance · **every contrast ratio the docs state, recomputed from the token layer** |
 | `test/sloplint.py` | the bundle obeying its own bans, in token layers, fenced examples **and the inline CSS the packs prescribe in prose** · doctrine completeness · pack origin addressability |
 | `node --check bin/cli.js` | the installer parses |
+| `node test/installer_test.js` | both installers against throwaway HOMEs, above all the refusal to shadow an installed plugin |
+| `node test/lint_test.js` | the project linter end to end: every S1 rule blocks on its plant, every quiet case stays quiet, the ratchet and the exit contract; `--self-test` checks the catalogue against the rules |
+| `node test/record_test.js` | the director-record validator end to end: a valid record for every surface class and a declined one pass; one planted defect per rule fails, each on its own field |
+| `node test/render_eval_test.js` | the render eval runner (`evals/render/`) on the committed hand-written sample: every count it must report |
+| `node bin/cli.js --lint kits` | the reference kits obey the floor they ship with: no S1 marker in any kit |
 
 Each gate ships a `--self-test` that plants a defect it must catch (`npm run
 selftest`), rejects an unknown argument instead of silently running the normal

package/bin/cli.js

@@ -155,10 +155,18 @@ function parseArgs(argv) {
     version: false,
     kit: null, // --kit <pack>: materialize a reference kit instead of installing
     out: null, // --out <path>: where the kit goes
+    lint: null, // --lint <dir>: run the project linter (bin/lint.js) on a tree
+    json: false, // --json: lint findings as a JSON array
+    ratchet: null, // --ratchet <budget.json>: per-file budgets that only fall
+    includeTests: false, // --include-tests: lint test files and fixtures too
+    selfTest: false, // --self-test: every lint rule against its planted defect
+    checkRecord: null, // --check-record <file>: validate a director record (bin/record.js)
     error: null, // set → print help and exit non-zero
   };
+  const seen = [];
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
+    seen.push(a.split("=")[0]);
     if (a === "--help" || a === "-h") opts.help = true;
     else if (a === "--version" || a === "-v") opts.version = true;
     else if (a === "--force" || a === "-f") opts.force = true;
@@ -190,10 +198,52 @@ function parseArgs(argv) {
       const value = a.slice("--out=".length);
       if (!value) opts.error = "--out needs a path";
       else opts.out = value;
-    } else {
+    } else if (a === "--lint" || a.startsWith("--lint=")) {
+      const value = a === "--lint" ? argv[++i] : a.slice("--lint=".length);
+      if (!value || value.startsWith("-")) opts.error = "--lint needs a directory";
+      else opts.lint = value;
+    } else if (a === "--ratchet" || a.startsWith("--ratchet=")) {
+      const value = a === "--ratchet" ? argv[++i] : a.slice("--ratchet=".length);
+      if (!value || value.startsWith("-")) opts.error = "--ratchet needs a budget file";
+      else opts.ratchet = value;
+    } else if (a === "--check-record" || a.startsWith("--check-record=")) {
+      const value = a === "--check-record" ? argv[++i] : a.slice("--check-record=".length);
+      if (!value || value.startsWith("-")) opts.error = "--check-record needs a director-record file";
+      else opts.checkRecord = value;
+    } else if (a === "--json") opts.json = true;
+    else if (a === "--include-tests") opts.includeTests = true;
+    else if (a === "--self-test") opts.selfTest = true;
+    else {
       opts.error = `unknown argument: ${a}`;
     }
   }
+  if (opts.error) return opts;
+  // The linter reads a tree and writes nothing, so any install or kit flag beside
+  // it is a request for two different things at once.
+  const LINT_ONLY = ["--json", "--ratchet", "--include-tests"];
+  const OTHERS = ["--cursor", "--claude", "--dir", "--force", "-f", "--kit", "--out"];
+  if (opts.selfTest && seen.some((x) => x !== "--self-test")) {
+    opts.error = "--self-test runs on its own";
+    return opts;
+  }
+  // The record validator reads one file and writes nothing; --json is the only
+  // flag it takes, and it does not run beside the linter or an install.
+  if (opts.checkRecord) {
+    const other = seen.find((x) => x !== "--check-record" && x !== "--json");
+    if (other) {
+      opts.error = `--check-record reads one record and takes only --json — ${other} does not combine with it`;
+      return opts;
+    }
+    return opts;
+  }
+  if (!opts.lint && seen.some((x) => LINT_ONLY.includes(x))) {
+    opts.error = `${seen.find((x) => LINT_ONLY.includes(x))} is only meaningful with --lint <dir>`;
+    return opts;
+  }
+  if (opts.lint && seen.some((x) => OTHERS.includes(x))) {
+    opts.error = `--lint reads a project and installs nothing — ${seen.find((x) => OTHERS.includes(x))} does not combine with it`;
+    return opts;
+  }
   if (opts.flavor && opts.target) {
     opts.error = "--dir cannot be combined with --cursor / --claude";
   }
@@ -284,6 +334,29 @@ ${c("bold", "Claude Design")} ${c("dim", "(Claude Code only)")}
   come out only when asked for by name. Then: npm install && npm run build,
   and run /design-sync in that directory.
 
+${c("bold", "Project linter")}
+  --lint <dir>          Check a project against the visual floor in
+                        SLOP_MARKERS.md (emoji icons, purple gradients, default
+                        faces, banned motion forms and the rest of the lint: rows)
+  --json                Findings as [{id, rule, severity, file, line, snippet}]
+  --ratchet <budget>    Per-file budgets ({"<file>": count}) that may only fall;
+                        also counts raw palette classes and hex outside tokens
+  --include-tests       Read tests and fixtures too (skipped by default)
+  --self-test           Every rule against its planted defect, and the
+                        catalogue against the rules (the record rules too)
+
+  Exit: 0 no S1 finding, 1 an S1 finding or a file over budget, 2 usage error.
+  S2 and S3 findings print and do not change the exit code.
+
+${c("bold", "Director record")}
+  --check-record <file> Validate a director record (templates/director-record.md
+                        in the installed skill): the fields its surface_class
+                        owes are present and filled by their rules
+  --json                The verdict as {valid, surface_class, violations[]}
+
+  Exit: 0 valid (a declined record with its reason included), 1 violations,
+  each listed as <Field>: <problem>, 2 usage error.
+
 ${c("bold", "Default")}
   Auto-detects: uses .cursor/ if present, else .claude/ if present,
   otherwise creates .cursor/skills/${SKILL_SLUG}/.
@@ -540,6 +613,31 @@ function main() {
     return;
   }
 
+  if (opts.checkRecord) {
+    const record = require("./record.js");
+    const io = { out: (l) => console.log(l), err: (l) => console.error(l) };
+    process.exitCode = record.runCheckRecord({ file: opts.checkRecord, json: opts.json }, io);
+    return;
+  }
+
+  if (opts.selfTest || opts.lint) {
+    const lint = require("./lint.js");
+    const io = { out: (l) => console.log(l), err: (l) => console.error(l) };
+    if (opts.selfTest) {
+      // Both validators answer for themselves; either failing fails the run.
+      const record = require("./record.js");
+      const a = lint.selfTest(io.out);
+      const b = record.selfTest(io.out);
+      process.exitCode = a || b ? 1 : 0;
+    } else {
+      process.exitCode = lint.runLint(
+        { dir: opts.lint, json: opts.json, ratchet: opts.ratchet, includeTests: opts.includeTests },
+        io,
+      );
+    }
+    return;
+  }
+
   const cwd = process.cwd();
 
   if (opts.kit) {