@ericrisco/rsc 1.0.23 → 1.0.25

package/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.0.23",
+  "version": "1.0.25",
   "counts": {
     "skills": 264
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ericrisco/rsc",
-  "version": "1.0.23",
+  "version": "1.0.25",
   "description": "Eric Risco's agent-skills catalog as a granular, self-recommending CLI installer.",
   "type": "module",
   "bin": {

package/scripts/knowledge-doctor.js

@@ -19,9 +19,16 @@ import { diagnose, CLASSES } from './lib/knowledge-doctor.js';
 const REPO = join(dirname(fileURLToPath(import.meta.url)), '..');
 const WIKI = join(REPO, '02-DOCS', 'wiki');
 
-const walk = (dir) => readdirSync(dir).flatMap((e) => {
-  const p = join(dir, e);
-  return statSync(p).isDirectory() ? walk(p) : (p.endsWith('.md') ? [p] : []);
+// withFileTypes, NOT statSync — this matches scripts/drift-check.js:167, the precedent the plan cited
+// as exact and then diverged from. statSync FOLLOWS symlinks, so a symlink under the wiki let the walk
+// read outside the declared zone (reporting the logical path, hiding the escape), a dangling symlink
+// crashed the whole report with ENOENT, and a symlink cycle crashed it with ELOOP. dirent.isDirectory()
+// does none of that: a symlink is neither a file nor a directory here, so it is skipped.
+const walk = (dir) => readdirSync(dir, { withFileTypes: true }).flatMap((e) => {
+  const p = join(dir, e.name);
+  if (e.isDirectory()) return walk(p);
+  if (e.isFile() && p.endsWith('.md')) return [p];
+  return []; // symlinks, sockets, anything else: not our business, and not a crash
 });
 
 // Injected so the pure library never touches git. Cached: the same ref is asked about repeatedly.
@@ -48,19 +55,49 @@ function main() {
   const indexPath = join(WIKI, 'index.md');
   const indexText = existsSync(indexPath) ? readFileSync(indexPath, 'utf8') : null;
 
+  // AC7 says an unreadable document is a candidate with its reason, never a silent skip. The first
+  // version read "unreadable" as "frontmatter unparseable" only, so a chmod-000 file or a dangling
+  // symlink threw out of readFileSync and took the WHOLE report with it — worse than a silent skip.
+  const unreadable = [];
   const docs = files.map((p) => {
     const rel = relative(WIKI, p);
+    let text;
+    try {
+      text = readFileSync(p, 'utf8');
+    } catch (e) {
+      unreadable.push({
+        path: relative(REPO, p), line: 1, cls: 'fuera-de-sitio', uncertain: true,
+        signal: `no se pudo leer el fichero (${e.code || e.message})`,
+        expected: 'un documento legible', found: e.code || 'error de lectura',
+      });
+      return null;
+    }
     return {
       path: relative(REPO, p),
       rel,
       dir: dirname(rel) === '.' ? '' : dirname(rel),
-      text: readFileSync(p, 'utf8'),
+      text,
       // Only artifacts the chain consumes are expected in the Knowledge map; an article is not.
       indexable: rel.startsWith('sdd/specs/') || rel.startsWith('sdd/verifications/'),
     };
-  });
+  }).filter(Boolean);
+
+  // Project artifacts outside the wiki: skill ids and script basenames. The library cannot read the
+  // repo (it is pure by design), so the caller that can, does.
+  const extraSlugs = [];
+  for (const [dir, strip] of [['skills', null], ['scripts', /\.(js|mjs|sh)$/], ['scripts/lib', /\.(js|mjs)$/]]) {
+    try {
+      for (const e of readdirSync(join(REPO, dir), { withFileTypes: true })) {
+        if (strip && e.isFile()) extraSlugs.push(e.name.replace(strip, ''));
+        else if (!strip && e.isDirectory()) extraSlugs.push(e.name);
+      }
+    } catch { /* a missing directory is not an error here */ }
+  }
 
-  const report = diagnose({ docs, indexText, refExists });
+  const report = diagnose({ docs, indexText, refExists, extraSlugs });
+  // Unreadable files are candidates too, and they sort first: a document nobody can open is the one
+  // whose staleness nobody can check.
+  if (unreadable.length) report.candidates = [...unreadable, ...report.candidates];
   if (asJson) { console.log(JSON.stringify(report, null, 2)); process.exit(0); }
 
   const byClass = (c) => report.candidates.filter((x) => x.cls === c);
@@ -69,10 +106,15 @@ function main() {
     console.log('Sin candidatos. Nada que triar.\n');
   } else {
     console.log(`${report.candidates.length} candidato(s), ordenados por coste de equivocarse:\n`);
+    // Filenames are interpolated into markdown, and a filename may contain newlines and backticks. A
+    // crafted name rendered a structurally valid FORGED candidate while the tally below still read 0 —
+    // and the consumer of this report (knowledge-ops) archives and overwrites files. Neutralise the
+    // three characters that can break out of the line.
+    const safe = (s) => String(s).replace(/[\r\n]+/g, '⏎').replace(/`/g, "'");
     for (const c of report.candidates) {
-      console.log(`- **${c.cls}** · \`${c.path}:${c.line}\`${c.uncertain ? ' · _incierto_' : ''}`);
-      console.log(`  - señal: ${c.signal}`);
-      console.log(`  - esperado: ${c.expected} · encontrado: ${c.found}`);
+      console.log(`- **${c.cls}** · \`${safe(c.path)}:${c.line}\`${c.uncertain ? ' · _incierto_' : ''}`);
+      console.log(`  - señal: ${safe(c.signal)}`);
+      console.log(`  - esperado: ${safe(c.expected)} · encontrado: ${safe(c.found)}`);
     }
     console.log('');
     for (const [label, cls] of [['se contradice', CLASSES.CONTRADICTS], ['ya no aplica', CLASSES.STALE], ['fuera de sitio', CLASSES.MISPLACED]]) {

package/scripts/lib/knowledge-doctor.js

@@ -27,7 +27,11 @@ export const CLASSES = { STALE: 'ya-no-aplica', MISPLACED: 'fuera-de-sitio', CON
 
 // Out of scope, named so their absence is not read as cleanliness.
 export const NOT_LOOKED_AT = [
-  'La PRIMERA instancia de una desviación de convención: las convenciones se derivan del wiki en cada corrida, así que un único fichero fuera de sitio define su propia ubicación como válida. Deliberado — hardcodear la tabla sería una segunda copia de la verdad que deriva de ella.',
+  // This entry described the PRE-FIX dead-code behaviour and survived the fix that removed it: a stale
+  // claim inside the tool built to find stale claims. Rewritten to name the mechanism that actually
+  // ships — the 75% dominant-share threshold — and its real blind spot.
+  'Un tipo con pocos documentos: una carpeta solo se reconoce como el hogar de un `type:` cuando concentra el 75% de sus documentos, así que un tipo con 3 o menos ejemplares no tiene hogar y su ubicación nunca se juzga. Deliberado — la alternativa es marcar trabajo correcto (`article` vive legítimamente en tres carpetas).',
+  'Documentos alcanzados por symlink: el recorrido usa `withFileTypes` y salta los enlaces, así que un `.md` enlazado dentro del wiki no se audita. Es el precio de impedir que el recorrido se escape de `02-DOCS/` siguiendo un enlace.',
   'Contradicción general entre documentos (exige comparación semántica; fuera por clarify 18-08).',
   'Obsolescencia semántica de prosa: si un párrafo sobre arquitectura sigue siendo cierto.',
   'La memoria del proyecto: drift-check ya resuelve sus rutas vía memoryDir(); su auditoría semántica queda fuera.',
@@ -58,9 +62,43 @@ export function parseFrontmatter(text) {
 }
 
 /** Does this document declare itself the single source of a fact? Matched on normalized prose. */
+/**
+ * Does this document declare ITSELF the single source of a fact?
+ *
+ * The first version matched `fuente única` / `single source of` anywhere in the file, and an adversarial
+ * review measured what that admits: on a 51-document wiki, **7 documents passed and only 1 actually
+ * declared single-sourcehood**. The other six were meta-documents merely DISCUSSING the concept — this
+ * detector's own spec, its own plan, and three verification records — and five of them had an unrelated
+ * first table sitting there as a denominator. One ordinary edit adding "probado 9 veces" to any of their
+ * descriptions would have fabricated a contradiction against a table with nothing to do with the number.
+ * That is over-firing on correct work, the direction P7 and the v1.0.17 rule both name as the dangerous
+ * one, and the whole narrow scope agreed in clarify rested on this gate being narrow.
+ *
+ * So the phrase must now be SELF-REFERENTIAL: the document has to point at itself ("esta tabla", "this
+ * table", "aquí") as the place the fact lives. Talking about single sources in the abstract no longer
+ * qualifies.
+ */
 export function declaresSingleSource(text) {
   const p = normalizeProse(text);
-  return /en ning[uú]n otro sitio|and nowhere else|fuente [uú]nica|single source of/i.test(p);
+  // A locator ("en esta tabla", "in this table", "aquí") within a short window of the exclusivity
+  // claim. The window keeps it one sentence: a doc that says "esta tabla" in one paragraph and
+  // "fuente única" three pages later is not declaring anything.
+  const claim = /(en esta (tabla|lista)|in this (table|list)|aqu[ií] y en ning|here and nowhere)/i;
+  const exclusive = /(en ning[uú]n otro sitio|and nowhere else|nowhere else|fuente [uú]nica de|single source of truth for)/i;
+  if (!claim.test(p) || !exclusive.test(p)) return false;
+  // And they must be near each other, or two unrelated sentences pass by coincidence.
+  const ci = p.search(claim);
+  const ei = p.search(exclusive);
+  if (Math.abs(ci - ei) > 160) return false;
+  // A QUOTED phrase is a citation, not a declaration. Measured: two documents still passed after the
+  // narrowing above, and both were quoting this repo's own pattern registry — a spec and a verification
+  // record. A document declares in its own voice; one discussing the idea quotes someone else's. Both
+  // are exactly the kind of document whose description naturally gains "probado 9 veces", which is how
+  // the fabricated contradiction would have arrived.
+  const around = p.slice(Math.max(0, ei - 60), ei + 60);
+  const quoted = /["«“][^"»”]{0,120}$/.test(p.slice(Math.max(0, ei - 120), ei))
+    && /^[^"«“]{0,120}["»”]/.test(p.slice(ei));
+  return !quoted || /\*\*/.test(around) === false ? !quoted : false;
 }
 
 const WORD_NUMBERS = {
@@ -72,9 +110,14 @@ const WORD_NUMBERS = {
  * A count asserted in the FRONTMATTER only. Body prose is not a usable signal: the live case's own
  * document contains "7 veces" inside a table cell describing something else entirely.
  */
+export const MAX_REFS_PER_DOC = 32;
+// A frontmatter value longer than this is not a title or a description. Bound before matching: the
+// digit-run pattern is quadratic, measured at 21.5s on an 160k-character value.
+const MAX_FM_VALUE = 2000;
+
 export function statedCountInFrontmatter(fields) {
   for (const key of ['description', 'title']) {
-    const v = String(fields[key] || '');
+    const v = String(fields[key] || '').slice(0, MAX_FM_VALUE);
     const digits = /(\d+)\s+(?:veces|times|apariciones|occurrences)/i.exec(v);
     if (digits) return { value: Number(digits[1]), source: key, literal: digits[0] };
     const words = new RegExp(`\\b(${Object.keys(WORD_NUMBERS).join('|')})\\s+(?:veces|times)`, 'i').exec(v);
@@ -83,9 +126,22 @@ export function statedCountInFrontmatter(fields) {
   return null;
 }
 
-/** Data rows of the first markdown table (header and separator excluded). */
+/**
+ * Blank out fenced code blocks, keeping the line count intact so reported line numbers stay true.
+ * Without this, an illustrative table inside ``` fences counted as the canonical one: a real 3-row
+ * table read as 1 row, and the report printed two wrong numbers as its evidence.
+ */
+export function stripFences(body) {
+  let inFence = false;
+  return String(body || '').split('\n').map((l) => {
+    if (/^\s*(```|~~~)/.test(l)) { inFence = !inFence; return ''; }
+    return inFence ? '' : l;
+  }).join('\n');
+}
+
+/** Data rows of the first markdown table (header and separator excluded), fences excluded. */
 export function firstTableRowCount(body) {
-  const lines = String(body || '').split('\n');
+  const lines = stripFences(body).split('\n');
   let i = lines.findIndex((l) => /^\s*\|.*\|/.test(l) && /\|/.test(l));
   if (i === -1) return null;
   if (!/^\s*\|[\s:|-]+\|/.test(lines[i + 1] || '')) return null; // header must be followed by a separator
@@ -107,9 +163,29 @@ export function findStaleClaims({ path, text, refExists }) {
   if (!status) return [];
   const out = [];
   const refs = new Set();
-  for (const m of status.matchAll(/\b([0-9a-f]{7,8})\b/g)) refs.add(m[1]);
-  for (const m of status.matchAll(/\bv?(\d+\.\d+\.\d+)\b/g)) refs.add(`v${m[1]}`);
-  for (const ref of refs) {
+  // A short hex run is only a commit if it is NOT all digits: `20260818` is a compact date, and the
+  // old pattern reported it as a missing commit. Verified: `status: implementada el 20260818` produced
+  // a candidate for a ref that never existed as a ref.
+  for (const m of status.matchAll(/\b([0-9a-f]{7,8})\b/g)) {
+    if (/^\d+$/.test(m[1])) continue;
+    refs.add(m[1]);
+  }
+  // A version is only a tag claim when the text presents it as one. `requiere node 18.0.0 y ajv 8.18.0`
+  // used to yield two candidates for tags `v18.0.0` and `v8.18.0` — dependency versions read as releases.
+  for (const m of status.matchAll(/\b(?:v|versión |version |publicada en |released in |released as )(\d+\.\d+\.\d+)\b/gi)) {
+    refs.add(`v${m[1]}`);
+  }
+  // Cap the spawns a single document can cause: one status: with 3000 distinct refs spawned 6002 git
+  // processes and took 76s. A document citing more than this is not making a traceable claim.
+  const capped = [...refs].slice(0, MAX_REFS_PER_DOC);
+  if (refs.size > MAX_REFS_PER_DOC) {
+    out.push({
+      path, line: lineOf(text, 'status:'), cls: CLASSES.STALE, uncertain: true,
+      signal: `status: cita ${refs.size} referencias; solo se comprobaron las primeras ${MAX_REFS_PER_DOC}`,
+      expected: `un status: con referencias acotadas`, found: `${refs.size} referencias`,
+    });
+  }
+  for (const ref of capped) {
     if (refExists(ref)) continue;
     out.push({
       path, line: lineOf(text, 'status:'), cls: CLASSES.STALE,
@@ -120,6 +196,21 @@ export function findStaleClaims({ path, text, refExists }) {
   return out;
 }
 
+/**
+ * Is there an actual index ROW for this path — a list item whose markdown link targets it?
+ *
+ * The first version was `indexText.includes(doc.rel)`, a substring test, so a path merely MENTIONED in
+ * prose silenced the check: "Borramos sdd/specs/x.md porque ya no aplica" counted as indexed. That is
+ * verbatim the mistake this repo recorded as having shipped twice in one day — "the path appears in the
+ * string" is not "the row exists" — and it fails in the under-firing direction, which is the quiet one.
+ */
+export function hasIndexRow(indexText, rel) {
+  if (!rel) return false;
+  const escaped = rel.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const row = new RegExp(`^\\s*[-*]\\s.*\\]\\([^)]*${escaped}\\)`, 'm');
+  return row.test(String(indexText || ''));
+}
+
 /**
  * Class 2 — out of place. Conventions are DERIVED from the wiki on every run, never hardcoded:
  * a hardcoded table is a second copy of the truth and drifts from it.
@@ -214,7 +305,7 @@ export function findMisplaced({ doc, conventions, indexText }) {
       });
     }
   }
-  if (indexText != null && doc.indexable && !indexText.includes(doc.rel)) {
+  if (indexText != null && doc.indexable && !hasIndexRow(indexText, doc.rel)) {
     out.push({
       path: doc.path, line: 1, cls: CLASSES.MISPLACED,
       signal: 'artefacto sin fila en el Knowledge map',
@@ -224,6 +315,44 @@ export function findMisplaced({ doc, conventions, indexText }) {
   return out;
 }
 
+/**
+ * Class 2b — an entry in a canonical log that does not describe what that log says it contains.
+ *
+ * AC2 of the spec, and it was NOT implemented in the shipped version — found by two independent
+ * refuter lenses. It is not a nice-to-have: one of the three incidents that motivated the whole spec
+ * was four entries written into `decisions.md` by eval agents, about features nobody was building.
+ * Worse than absent, the disclosure list did not name it, so the report presented the canonical log as
+ * scanned and clean — affirming a check nobody performed.
+ *
+ * The signal has to be narrow or this becomes the noisiest detector in the tool. A canonical log
+ * declares its own subject in its opening prose ("Procedimientos que el asistente observó",
+ * "decisiones de alcance"). An entry is a candidate when its heading names a SLUG that exists nowhere
+ * in the project — because a decision about `magic-link-login` when no such spec, plan or artifact
+ * exists is either about someone else's work or about work nobody is doing.
+ */
+export function findLogIntruders({ path, text, knownSlugs }) {
+  if (!/decisions\.md$|automation-gaps\.md$/.test(path)) return [];
+  const out = [];
+  const lines = String(text || '').split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    const h = /^##\s+\d{4}-\d{2}-\d{2}\s*[—·-]\s*(.+)$/.exec(lines[i]);
+    if (!h) continue;
+    // A slug-shaped token in the heading: lowercase words joined by hyphens, at least two parts.
+    const slugs = (h[1].match(/`?\b([a-z][a-z0-9]+(?:-[a-z0-9]+)+)\b`?/g) || [])
+      .map((s) => s.replace(/`/g, ''));
+    const orphans = slugs.filter((s) => !knownSlugs.has(s));
+    // Only flag when EVERY slug in the heading is unknown: a heading mixing known and unknown terms is
+    // ordinary prose, not an entry about work that does not exist.
+    if (!slugs.length || orphans.length !== slugs.length) continue;
+    out.push({
+      path, line: i + 1, cls: CLASSES.MISPLACED, uncertain: true,
+      signal: `entrada cuyo asunto (${orphans.map((s) => `\`${s}\``).join(', ')}) no corresponde a ningún artefacto del proyecto`,
+      expected: 'una entrada sobre trabajo que existe', found: 'asunto sin artefacto',
+    });
+  }
+  return out;
+}
+
 /** Class 3 — a frontmatter count contradicting the table the document declares its single source. */
 export function findContradictions({ path, text }) {
   if (!declaresSingleSource(text)) return [];
@@ -253,13 +382,26 @@ export function rank(candidates) {
 }
 
 /** The whole pass, over already-read documents. Pure: no fs, no git — both are injected. */
-export function diagnose({ docs, indexText, refExists }) {
+export function diagnose({ docs, indexText, refExists, extraSlugs = [] }) {
   const cands = [];
   const conventions = deriveConventions(docs);
+  // Slugs the project actually has, derived from the documents themselves (P3: the content is the
+  // ledger). A log entry whose subject is not in here is about work that does not exist.
+  // extraSlugs comes from the CLI, which knows the repo: skill ids and script basenames are project
+  // artifacts too. Deriving only from wiki filenames flagged `drift-check` — a real script — as work
+  // that does not exist.
+  const knownSlugs = new Set(extraSlugs);
+  for (const doc of docs) {
+    const base = (doc.rel || doc.path).split('/').pop().replace(/\.md$/, '').replace(/\.plan$/, '');
+    knownSlugs.add(base);
+    const fmSlug = parseFrontmatter(doc.text).fields.slug;
+    if (fmSlug) knownSlugs.add(fmSlug);
+  }
   for (const doc of docs) {
     cands.push(...findStaleClaims({ path: doc.path, text: doc.text, refExists }));
     cands.push(...findMisplaced({ doc, conventions, indexText }));
     cands.push(...findContradictions({ path: doc.path, text: doc.text }));
+    cands.push(...findLogIntruders({ path: doc.path, text: doc.text, knownSlugs }));
   }
   return { candidates: rank(cands), scanned: docs.length, notLookedAt: NOT_LOOKED_AT };
 }

package/skills/design/SKILL.md

@@ -234,6 +234,36 @@ img  { outline: 1px solid oklch(0 0 0 / 0.1); outline-offset: -1px; }
 
 Depth recipes, glass, noise, concentric math → `references/visual-system.md`.
 
+## The three locks, and who checks them
+
+A long page generated in passes drifts against itself. Three things must be **one** thing for
+the whole page, and they are not preferences — a page that breaks one of them is defective:
+
+1. **Theme lock.** One theme for the page (light, dark, or auto). No section flipping to
+   inverted halfway down because it looked good alone.
+2. **Accent lock.** One accent, used identically in every section. **This one is judgement**:
+   deciding which token is the accent needs to read the system's intent, so no script claims
+   to check it — you do, before you claim done.
+3. **Radius lock.** One radius system. Four different `rounded-*` scales in one tree means
+   there is no system, and `scripts/verify.sh` counts them.
+
+## The tells the script owns, and the ones you own
+
+`scripts/verify.sh` carries a **registry of mechanical tells** and reports each with file and
+line: dashes in rendered copy, scroll cues, numbered eyebrows, build stamps on marketing
+pages, unstable viewport heights, middot chains, hype words, plus counted ratios (eyebrows
+against sections, double-bordered rows, radius scales). Run it; do not re-derive that list
+from memory, and do not treat its silence as a design review.
+
+What it cannot see is the other half: fabricated substance (a product UI built from divs,
+invented photo credits, the Jane Doe cast), decoration posing as information, labels that say
+nothing, and composition habits like three identical feature cards. That half is
+`references/ai-tells.md`, and it is read with your eyes on the page.
+
+When the brief corresponds to an official, maintained design system rather than an aesthetic —
+UK or US public sector, Shopify admin, Carbon, Atlassian, Primer, Fluent — install the
+official package instead of approximating it: `references/design-systems.md`.
+
 ## Anti-patterns
 
 | Rationalization | Reality / Fix |
@@ -314,6 +344,6 @@ Score = Σ(dimension × weight), max 115 (normalize to /100 by ×100/115 if you
 Two records, both indexed in `02-DOCS/wiki/index.md` (the Knowledge map; root `CLAUDE.md` keeps only a short pointer to it), both read first on every use so outputs stay consistent with them:
 
 - The **brand study** at `02-DOCS/wiki/brand/` — the hard gate above: missing or incomplete → ask until complete before designing.
-- The **design-system decisions** at `02-DOCS/wiki/stack/design.md` — the chosen tokens (color/OKLCH, type scale, spacing, radius, shadow, motion), the 2026 direction picked, and the reference sites. Recorded, not gated; create/update it as decisions are made.
+- The **design-system decisions** at `02-DOCS/wiki/stack/design.md` — the chosen tokens (color/OKLCH, type scale, spacing, radius, shadow, motion), the 2026 direction picked, and the reference sites. Recorded, not gated; create/update it as decisions are made. **Read it before fixing type and palette on a new surface**, and either reuse what is there or state why you are departing — otherwise every surface of the project drifts into a different design. (Across *different* projects this record cannot help: it lives inside each one. Distrusting your own second default is the only guard there — see the repetition note in `references/ai-tells.md`.)
 
 The wiki article protocol both follow is `../harness/SKILL.md`'s.

package/skills/design/evals/cases.yaml

@@ -49,7 +49,7 @@ capability:
   - scenario: "User asks: 'Here's our current pricing page — do a design review and tell me how good it actually is.'"
     must_include:
       - "Applies the design-review QA checklist (value prop in 5s, contrast >= 4.5:1, visible focus, one <h1>, semantic landmarks, LCP image priority, next/font, no transition: all, tokens not magic numbers, ban-list-clean copy, 360px fit, empty/loading/error states)."
-      - "Scores the 10-dimension visual-audit rubric 0-10 with weights and reports a weighted total out of 100, mapped to a band (<60 generic / 60-79 competent / 80-94 premium / 95+ award-tier)."
+      - "Scores the 11-dimension visual-audit rubric 0-10 with weights and reports the weighted total on its /115 scale, mapped to a band (<69 generic / 69-91 competent / 92-108 premium / 109+ award-tier)."
       - "For each dimension scoring below 8, gives a concrete actionable fix (e.g. exact spacing/token change), not a vague 'improve spacing'."
       - "Checks copy against the ban-list and flags hype/vague value props that fail the 5s test."
       - "Flags any transition: all, magic hex/px, cards-in-cards, or purple->blue everything gradient as defects, not preferences."

package/skills/design/references/ai-tells.md

@@ -0,0 +1,75 @@
+# AI tells — the ones only a reader can catch
+
+The mechanical tells are **not here**. `scripts/verify.sh` carries a registry of them and
+flags them with file and line, so re-teaching them as prose would be paying twice for the
+same rule. This file holds only what a `grep` cannot decide: presences you have to *look* at
+the page to see.
+
+Part of this corpus is adapted from [Leonxlnx/taste-skill](https://github.com/Leonxlnx/taste-skill)
+(MIT), whose lists came out of real production tests. The split into checkable-vs-judged, the
+thresholds, and the wording are ours.
+
+Every item below is a **default**, overridable by a brief that explicitly asks for it. What
+makes them tells is that they show up *unasked*, as the model's idea of "looking designed".
+
+## Fabricated substance
+
+- **A product UI built out of divs.** A fake task list, fake terminal or fake dashboard
+  assembled from styled rectangles is the single most reliable signature of generated work.
+  Use a real screenshot, a real component, a generated image, or show nothing.
+- **Hand-rolled decorative SVG.** Abstract squiggles and blobs authored inline to fill space.
+  Icons come from a maintained set; decoration comes from a real asset or not at all.
+- **The Jane Doe cast.** "John Doe", "Sarah Chan", egg avatars, `99.99%`, `50%`, round
+  thousands, and startup-slop brand names ("Acme", "Nexus", "SmartFlow"). Real work has
+  specific, slightly awkward names and messy numbers (`47.2%`, not `50%`).
+- **Testimonials nobody said.** A quote with no attributable person, or five quotes with the
+  same cadence, reads as filler. One real quote beats three invented ones.
+
+## Decoration wearing the costume of information
+
+- **Atmospheric locale strips.** A city, a timezone, a temperature in the nav or footer. Only
+  earns its place for a genuinely distributed studio, a travel brand, or a physical venue.
+- **Status dots with no status.** A coloured dot before nav items, list rows or badges. Keep
+  it only where it reports real state, and then only once per section.
+- **Invented photo credits.** `Field study no. 12 · Ines Caetano` under a stock image.
+  Credit a real photographer or write a functional caption.
+- **Pills laid over images.** Tags floated on top of a photo. Either the image speaks alone,
+  or the caption sits below it, outside the frame.
+- **Decoration strips under the hero.** `BRAND. MOTION. SPATIAL.` in small mono caps. Only
+  legitimate when those words are real navigation or real status.
+
+## Labels that say nothing
+
+- **Poetic section labels.** "Field notes", "From the field", "On our desks", "Currently on
+  the bench". Use the functional name ("Testimonials", "Latest writing") or no label.
+- **Generic step labels.** "Stage 1 / Stage 2", "Phase 01 / 02". The step content *is* the
+  label: "Install", "Configure", "Ship".
+- **Mock-humble asides** and micro-meta sentences under a heading ("The list will stay short
+  on purpose"). Eyebrow, headline, body. Nothing else.
+- **"Quietly trusted by".** Say "Used at", "Customers include", or let the logos speak.
+
+## Composition habits
+
+- **Three identical feature cards.** The default feature row. Reach for a two-column zig-zag,
+  an asymmetric grid, or a horizontal rail instead — and do not run the same split three
+  sections in a row.
+- **The corner floater.** A giant left-aligned headline with a small explainer paragraph
+  floating in the section's top-right, aligned to nothing. Stack it, or build a real
+  two-column header.
+- **Rotated vertical text** and crosshair grid lines drawn only to look designed. Both are
+  agency-portfolio clichés unless they organise real content.
+- **A bento with empty cells.** N items means N cells, and at least two cells need real
+  visual variation — otherwise it is a white card grid with extra steps.
+
+## The second default (repetition)
+
+Obeying every rule produces correct pages that all look the same. Before fixing type and
+palette, read the project's recorded design decisions and either reuse them deliberately or
+say why you are departing. Two specific defaults to distrust: reaching for the same display
+serif again, and answering every premium-consumer brief with the beige/brass/oxblood family.
+
+## Surface treatments to distrust by default
+
+Outer glows and neon; pure `#000000` (use an off-black); oversaturated accents that refuse to
+sit with the neutrals; gradient fills on large headings; custom cursors (outdated, hostile to
+accessibility and to performance); glass on every surface rather than on floating ones.

package/skills/design/references/design-systems.md

@@ -0,0 +1,41 @@
+# When the brief is a design system, not an aesthetic
+
+This skill's default is Tailwind v4 + Next.js, and for most briefs that is right. But some
+briefs correspond to a **maintained, official design system**, and there the correct answer is
+to install it. Recreating its CSS by hand produces something that looks like it, fails its
+accessibility work, and drifts on its next release.
+
+The list is deliberately short: only the cases where using the official package is
+**obligatory or strongly expected**, and where the default instinct would be to hand-roll it.
+Free choices (Bootstrap, Material for a non-Google product, Radix Themes, shadcn/ui) are not
+here — they are ordinary picks, and shadcn/ui in particular is already this skill's territory,
+where the rule is simply never to ship it in its default state.
+
+| The brief reads as | Install | Why it is not a choice |
+| --- | --- | --- |
+| A UK public-sector service | `govuk-frontend` | Expected by the Service Standard; deviating is a finding at assessment |
+| A US federal or trust-first public service | `uswds` | Same, under the US Web Design System |
+| A Shopify admin surface or embedded app | `@shopify/polaris` (or Polaris web components) | Required for admin UI to be accepted |
+| IBM-flavoured enterprise or dense analytics | `@carbon/react` + `@carbon/styles` | Mature data-density patterns you will otherwise reinvent badly |
+| An Atlassian / Jira-adjacent product surface | `@atlaskit/*` + `@atlaskit/tokens` | Official DS; token-driven theming |
+| A GitHub-style devtool or community page | `@primer/css`, or `@primer/react-brand` for marketing | Official Primer; the Brand variant is the marketing half |
+| A Microsoft / Fluent-flavoured product | `@fluentui/react-components` | Official Fluent, Microsoft tokens, accessibility already done |
+
+## The three rules that come with them
+
+1. **Do not recreate it.** If the brief names one of these, install the package. Importing its
+   tokens and then overriding ninety percent of them is the same mistake with extra steps.
+2. **One system per project.** No Fluent components inside a Carbon tree, no shadcn/ui
+   dropped into a Material app. Mixing two systems produces a third, worse one.
+3. **Name what is an approximation.** When the brief is an *aesthetic* rather than a system —
+   glassmorphism, bento tiles, brutalism, editorial, aurora gradients, kinetic type — there is
+   no official package, and saying so is part of the work. Apple's Liquid Glass is documented
+   for Apple platforms only: there is no official web implementation, so a web version is a
+   `backdrop-filter` approximation and must be labelled as one, in the code and to the user.
+
+## What still applies
+
+Everything in `../SKILL.md` that is not styling: the brand gate, the accessibility floor,
+the Core Web Vitals budget, the 5-second value-prop test, and the tell registry in
+`../scripts/verify.sh`. An official design system settles which components you use. It does
+not settle whether the page says anything.

package/skills/design/references/motion-and-interaction.md

@@ -174,6 +174,41 @@ export function Toast({ open, message }: { open: boolean; message: string }) {
 
 Once you are in `motion/react`, defer the mechanics (spring config, variants, `layoutId` shared transitions) to the external *motion-foundations* and *motion-ui* references.
 
+## Escalating past the native path
+
+Native `animation-timeline: view()` covers reveals, progress rails and parallax. Two effects it
+cannot express are **pinning** (a section holds still while its content advances) and a
+**horizontal pan** driven by vertical scroll. Those need a scroll library, and the improvised
+version is always wrong in the same three ways. Escalate deliberately:
+
+**Never listen to scroll directly.** `window.addEventListener('scroll')` fires off the main
+thread's budget, blows INP, and never gets a passive-listener or cleanup story right. The
+allowed inputs are `IntersectionObserver`, a scroll-driven CSS timeline, `useScroll()` from
+`motion/react`, or GSAP's ScrollTrigger. Nothing else.
+
+**Sticky stack** (pin a section, advance its layers):
+
+```ts
+// 'use client' leaf only. One trigger per pinned section, killed on unmount.
+const st = ScrollTrigger.create({
+  trigger: sectionRef.current,
+  start: "top top",          // pin the moment the section's top reaches the viewport top
+  end: () => `+=${panels.length * window.innerHeight}`,
+  pin: true,
+  pinSpacing: true,          // without this the next section slides under the pin
+  scrub: 1,                  // 1 = follow scroll with a 1s catch-up, not a hard 1:1 jump
+  invalidateOnRefresh: true, // recompute on resize, or the end point is stale on rotate
+});
+// cleanup is not optional: return () => st.kill();
+```
+
+**Horizontal pan** is the same trigger with `end: () => "+=" + track.scrollWidth` and the
+track moved via `x`, not `left` — `transform` is compositor-only, `left` triggers layout.
+
+Both are opt-in above a motion budget, both stay inside
+`@media (prefers-reduced-motion: no-preference)`, and both collapse to a plain vertical stack
+below `768px` rather than pinning on a phone.
+
 ## See Also
 
 - `visual-system.md` — the easing and duration tokens these animations consume.

package/skills/design/scripts/verify.sh

@@ -7,9 +7,17 @@
 #      performance + accessibility audit and checks Core Web Vitals against the
 #      skill's hard thresholds (LCP < 2.5s, CLS < 0.1, INP proxy via TBT < 200ms,
 #      a11y score >= 0.9).
-#   2. Always runs static, network-free design-review grep checks (one <h1>,
-#      no `transition: all`, hardcoded hex vs tokens, missing image alt, missing
-#      prefers-reduced-motion, marketing ban-list words).
+#   2. Always runs static, network-free design-review checks, in three groups:
+#      - four judgement-shaped ones (more than one <h1>, image without alt,
+#        hardcoded hex despite a token system, animation with no reduced-motion
+#        guard) — see static_checks();
+#      - the tell registry: one row per checkable AI tell, iterated generically
+#        (dashes in rendered copy, scroll cues, numbered eyebrows, build stamps,
+#        unstable viewport heights, middot chains, transition-all, hype words)
+#        — see tell_table(); every row has a fixture in the repo's test suite;
+#      - three counters that need a ratio rather than a match (eyebrows against
+#        sections, double-bordered rows, radius scales) — see counter_checks().
+#      Everything here WARNS. Nothing here fails, unless --strict is passed.
 #   3. If Lighthouse did not run, prints the manual QA checklist. For a graded
 #      0-10 critique, use the visual-audit rubric in SKILL.md instead.
 #
@@ -78,7 +86,10 @@ have() { command -v "$1" >/dev/null 2>&1; }
 SELF_NAME="$(basename "$0")"
 search() {
   [ "$#" -gt 0 ] || return 1
-  if have rg; then
+  # VERIFY_FORCE_GREP=1 pins the grep branch. It exists so the test suite can prove BOTH
+  # engines agree on the multibyte patterns (em-dash, middot) on any machine, instead of
+  # only exercising whichever one happens to be installed.
+  if have rg && [ -z "${VERIFY_FORCE_GREP:-}" ]; then
     # rg already ignores .gitignore'd paths (node_modules, .next, dist); also skip self.
     rg -n --no-heading --glob "!$SELF_NAME" "$@"
   else
@@ -165,6 +176,102 @@ run_lighthouse() {
   fi
 }
 
+# --- the tell registry ------------------------------------------------------
+# One row per checkable AI tell. A row is DATA, not code, so the test suite can enumerate
+# every row and demand a fixture for each: a check nobody has ever seen fire cannot ship.
+# Add a tell by adding a row plus tests/fixtures/design-tells/tells/<id>.tsx — nothing else.
+#
+# Columns, delimited by %% (the pattern column needs `|` for ERE alternation):
+#   id %% sev %% extensions %% POSIX-ERE pattern %% what to do instead / the legit exception
+#
+# Patterns are POSIX ERE: no lookahead, no \b, no \s — they must behave identically under rg
+# and under grep -E. Part of the corpus is adapted from Leonxlnx/taste-skill (MIT).
+tell_table() {
+  cat <<'TELLS'
+em-dash%%warn%%tsx,jsx,html,vue,svelte,mdx%%—|–%%em-dash or en-dash in rendered copy is the loudest AI tell. Use a period, a comma, a colon or parentheses instead
+scroll-cue%%warn%%tsx,jsx,html,vue,svelte%%[Ss]croll to (explore|walk|discover|see|begin)|↓ *[Ss]croll%%a scroll cue explains scrolling to someone already looking at the hero. Delete it, or use a real anchor link instead
+numbered-eyebrow%%warn%%tsx,jsx,html,vue,svelte%%(^|[^0-9A-Za-z])[0-9]{2,3} +(·|/) +[A-Za-z]%%numbered section eyebrow (001 · Capabilities). Name the topic in plain language instead
+version-stamp%%warn%%tsx,jsx,html,vue,svelte%%v[0-9]+\.[0-9]+\.[0-9]+|Build [0-9]{3,4}%%a build or version stamp is devtool furniture on a marketing page. Delete it. Legitimate exception: a real devtool footer, a changelog or a release page
+viewport-unit%%warn%%tsx,jsx,html,vue,svelte,css%%h-screen%%h-screen jumps when mobile browser chrome slides away. Use min-h-[100dvh] instead
+middot-chain%%warn%%tsx,jsx,html,vue,svelte%%·[^·]*·%%more than one middot on a line is decoration pretending to be metadata. Use line breaks, columns or a hairline instead
+transition-all%%warn%%tsx,jsx,css,html,vue,svelte%%transition:[[:space:]]*all|transition-all%%transition-all animates layout properties and janks. List the exact properties instead
+ban-list%%warn%%tsx,jsx,html,md,mdx%%revolutionary|game-?changer|cutting-edge|supercharge|seamless|unlock%%hype words carry no value prop. Use the concrete benefit and a real number instead
+TELLS
+}
+
+run_tell_table() {
+  local line id sev globs pat msg hits exts rest
+  # NOT `IFS='%%'`: IFS is a set of characters, so it would split on a single `%` and put an
+  # empty field between every pair. Parameter expansion splits on the two-character
+  # delimiter exactly, which is what the pattern column needs to keep its ERE `|`.
+  while IFS= read -r line; do
+    case "$line" in ''|'#'*) continue ;; esac
+    id="${line%%"%%"*}";    rest="${line#*"%%"}"
+    sev="${rest%%"%%"*}";   rest="${rest#*"%%"}"
+    globs="${rest%%"%%"*}"; rest="${rest#*"%%"}"
+    pat="${rest%%"%%"*}";   msg="${rest#*"%%"}"
+    exts="${globs//,/|}"
+    # Two post-filters, both learned from a real run over this repo:
+    #   1. keep only the extensions the row declares (anchored before the first colon, so it
+    #      behaves the same under rg and grep and never matches content that names a file);
+    #   2. drop lines whose match sits in a code comment. A dash in `/* tokens — lifted */`
+    #      is not rendered copy, and flagging it trains the reader to ignore the tool.
+    hits="$(search "$pat" 2>/dev/null \
+      | grep -E "^[^:]*\.($exts):" \
+      | grep -vE "^[^:]*:[0-9]+:[[:space:]]*(//|/\*|\*[^a-zA-Z]|#|<!--|\{/\*)" || true)"
+    if [ -n "$hits" ]; then
+      # The sev column is real, not decoration: anything other than `warn` breaks the build.
+      case "$sev" in
+        warn) warn "$id: $msg" ;;
+        *)    fail "$id: $msg" ;;
+      esac
+      printf '%s\n' "$hits" | head -n 5
+    fi
+  done <<EOF
+$(tell_table)
+EOF
+}
+
+# --- counters: the tells that are a ratio or a repetition, not a pattern -----
+# These cannot be table rows because one match proves nothing — it takes a count. Each one
+# carries its own named test instead of riding the generic row mechanism.
+counter_checks() {
+  local eyebrows sections ceiling hits variants v
+
+  # Eyebrow ceiling. Threshold ceil(sections/3) is BORROWED from taste-skill and has never
+  # been calibrated against a page of ours — the warning says so rather than implying rigour.
+  eyebrows="$(search 'uppercase[^"]*tracking|tracking[^"]*uppercase' 2>/dev/null | grep -cE '^[^:]*\.(tsx|jsx|html|vue|svelte):' || true)"
+  sections="$(search '<section' 2>/dev/null | grep -cE '^[^:]*\.(tsx|jsx|html|vue|svelte):' || true)"
+  [ -z "$eyebrows" ] && eyebrows=0
+  [ -z "$sections" ] && sections=0
+  if [ "$sections" -eq 0 ]; then
+    if [ "$eyebrows" -gt 0 ]; then
+      skip "eyebrow ceiling: no <section> found, so there is no denominator — not guessing one"
+    fi
+  else
+    ceiling=$(( (sections + 2) / 3 ))
+    if [ "$eyebrows" -gt "$ceiling" ]; then
+      warn "eyebrow count $eyebrows exceeds the ceiling $ceiling for $sections sections (uncalibrated threshold, borrowed): drop the uppercase micro-labels, or let the headline carry it instead"
+    fi
+  fi
+
+  # A hairline above AND below every row of a long list is the laziest possible layout.
+  hits="$(search 'border-t[^"]*border-b|border-b[^"]*border-t' 2>/dev/null | grep -cE '^[^:]*\.(tsx|jsx|html|vue|svelte):' || true)"
+  [ -z "$hits" ] && hits=0
+  if [ "$hits" -gt 3 ]; then
+    warn "double border on $hits list rows: pick one edge, or use spacing instead of hairlines"
+  fi
+
+  # More than two radius scales in one tree means no radius system at all.
+  variants=0
+  for v in none sm md lg xl 2xl 3xl full; do
+    if search "rounded-$v" >/dev/null 2>&1; then variants=$((variants + 1)); fi
+  done
+  if [ "$variants" -gt 2 ]; then
+    warn "$variants different radius scales in use: one radius system per project — use a --radius-* token instead"
+  fi
+}
+
 # --- static design-review checks (always run, no network) -------------------
 static_checks() {
   local hits
@@ -182,9 +289,8 @@ static_checks() {
     done < <(grep -rl --exclude-dir=node_modules --exclude-dir=.git --exclude-dir=.next '<h1' . 2>/dev/null || true)
   fi
 
-  # 2. transition: all / transition-all  ([[:space:]] is POSIX; \s is not portable in ERE)
-  hits="$(search 'transition:[[:space:]]*all|transition-all' 2>/dev/null || true)"
-  if [ -n "$hits" ]; then warn "transition: all / transition-all found:"; printf '%s\n' "$hits" | head -n 5; fi
+  # 2. (moved) `transition: all` is now a row in tell_table() — it is a plain pattern, so it
+  #    gets the generic mechanism and its fixture for free.
 
   # 3. hardcoded hex when a token system exists (\b is not portable in ERE; a
   #    3-8 char hex run after # is a sufficient heuristic without the boundary).
@@ -209,9 +315,7 @@ static_checks() {
     fi
   fi
 
-  # 6. ban-list marketing words in copy
-  hits="$(search 'revolutionary|game-?changer|cutting-edge|supercharge|seamless|unlock' 2>/dev/null | grep -iE '\.(tsx|jsx|html|md|mdx)' || true)"
-  if [ -n "$hits" ]; then warn "ban-list marketing words found in copy:"; printf '%s\n' "$hits" | head -n 5; fi
+  # 6. (moved) the marketing ban-list is now a row in tell_table(), same reason as #2.
 }
 
 # --- fallback manual checklist ----------------------------------------------
@@ -239,6 +343,8 @@ EOF
 # --- run --------------------------------------------------------------------
 run_lighthouse
 static_checks
+run_tell_table
+counter_checks
 [ "$LH_RAN" -eq 0 ] && print_checklist
 
 printf '\nok=%d skip=%d warn=%d fail=%d\n' "$ok_count" "$skip_count" "$warn_count" "$fail_count"