jig-ui 0.22.0 → 0.23.0

package/CHANGELOG.md

@@ -1,5 +1,89 @@
 # Changelog
 
+## 0.23.0 (2026-09-29)
+
+Rules for the prose a page ships and for how it moves, a spec that says what
+moves and why, and a critique that reads the page against its spec both ways.
+
+### Added
+
+- **Rules for the prose a page ships.** The copy rules were written for
+  interface strings: a label, a button, an error. A docs chapter, a guide or a
+  blog post was held only to those, and a paragraph could claim a figure nobody
+  measured, open with "In today's rapidly changing world" and restate its
+  introduction as its conclusion, and pass. Nine rules now cover prose longer
+  than a paragraph (`I-148` to `I-156`): a claim with no source, a sentence
+  specific in sound and empty in fact, formula openers and closers, saying it
+  twice, a rhetorical shape on repeat, enthusiasm the content has not earned,
+  stacked hedges, emoji in headings, and structure imposed on the content.
+  Four more cover writing a person puts their name to, a blog post or a case
+  study (`I-157` to `I-160`): nothing only the author could say, no point of
+  view, an even rhythm, and a feeling named rather than shown.
+- **They judge the writing, never the writer.** A finding says the copy reads
+  as generic; it never says a model wrote it. Nothing is measured: rhythm and
+  voice have no number a check could hold, and a score would reward prose that
+  games it.
+- **`check` catches two of them.** `I-150` warns on a short list of formula
+  phrases ("it is important to note", "let's dive in", "in conclusion") in the
+  text a reader sees, and leaves a quotation alone. `I-155` warns on an emoji
+  in a Markdown page's heading; in markup, `A-05` already reports it.
+- **The copy checklist asks three more questions** (`L-06`): whether every
+  figure traces to a source, whether prose says something specific once, and
+  whether a long-form piece holds something only its author could say.
+
+- **Three motion rules.** `G-161`: a layout change the user caused shows
+  where things went (a deleted row's neighbours slide into the gap) rather than
+  jumping, and stays instant when the user did not cause it. `G-162`: animate
+  `transform` and `opacity`, never layout, and never `all`; `check` warns on a
+  transition or keyframe that names a layout property or `all`, and on
+  Tailwind's `transition-all`. `G-163`: one thing moves at a time. Moving
+  within the screen takes `--ease-in-out` (`T-04`). No new tokens.
+- **A spec says what moves, and why.** `motion:` lists each movement: what
+  moves, its trigger, and what it tells the reader. One that cannot say is cut
+  before it is built. The owner reads it on the confirmation sheet, `make`
+  builds that motion and no other, and `critique` judges the page against it.
+  A spec confirmed before it has none, and is judged by the rules alone.
+
+### Changed
+
+- **A critique reads the page against the spec, not only the spec against the
+  page.** A section, a paragraph or a claim the page carries that no line of the
+  spec asks for, and no deviation records, is now a finding. On jig-site a
+  chapter carried an accurate paragraph the owner never confirmed, and two
+  critiques saw it and filed nothing, because it broke no rule. The fix is a
+  tweak that writes it into the spec for the owner to confirm, or removes it.
+- **Each critique arm is told the shape of a `ruled` verdict.** An arm wrote
+  four that named the owner's decision only in their reason, and `verdicts`
+  refused them all.
+- **A CLI run from a checkout reads the checkout's rules.** `prepack` copies the
+  rules beside the CLI package for each publish, and the copies stayed behind:
+  a clone that had published read the rules as they were then, and Jig's own
+  first test run after each rule change failed 14 tests. An installed package
+  still reads its own copies.
+- **`jig ship` leaves a replaced spec to the spec that replaced it.**
+  `superseded_by: <spec>` in a spec's front matter marks it, and `ship` reports
+  it apart instead of as never critiqued, once it has checked the spec it names
+  exists. On jig-site two replaced specs were owed a critique at every `ship`,
+  each marked a different way by the agent that replaced it.
+- **A tweak that records a decision applies it to the whole page.** The owner
+  rules on one instance, and the decision states a kind; the tweak now finds the
+  other instances on the page and fixes them in the same change. On jig-site a
+  decision to set every quotation mark curly fixed the one named, and four
+  straight marks survived to the next critique.
+- **A spec's second check covers what changed.** The reader gets the earlier
+  record and the diff; a quotation or fact on an unchanged line, whose source
+  has not changed either, carries over. On jig-site every re-check reopened
+  every source, about $10 a round.
+- **A critique has a place for what no rule names.** A difference between the
+  page and its spec, or a source it teaches, goes under `differences` in the
+  arm's verdict file and counts as a finding. On jig-site both arms of one
+  critique invented rule ids to carry one, and `verdicts` refused them. The
+  report now says what the page-against-spec pass found, "none" included, and
+  `verdicts` explains that a decision is judged, never `ruled`.
+- **Every page is owed a critique again.** A critique judges every rule, so one
+  written before these sixteen is incomplete, and `jig ship` lists each page
+  until it is critiqued on this release.
+
 ## 0.22.0 (2026-09-29)
 
 A spec and a mockup are checked before the owner says yes, a critique can wait,

package/README.md

@@ -12,13 +12,13 @@ Installed as `npx jig-ui` — the bare name was taken on npm.
 Jig is **a skill your coding agent reads**, and **a CLI you can run yourself**.
 They are two halves of the same thing, and the split is not arbitrary:
 
-- Of the 143 rules, **36 can be decided by a machine** — a hard-coded colour, a
+- Of the 159 rules, **39 can be decided by a machine** — a hard-coded colour, a
   contrast ratio below the floor, a removed focus ring. The CLI decides those.
-- The other **107 are judgment** — whether an empty state says anything useful,
+- The other **120 are judgment** — whether an empty state says anything useful,
   whether a label reads as an instruction, whether motion earns its place. No
   regex settles those. An agent reads the rules and applies them.
 
-Running only the CLI gets you the 36. Running only the agent gets you the 107 with
+Running only the CLI gets you the 39. Running only the agent gets you the 120 with
 no verification. **A clean `jig check` is not a clean review**, and the skill
 says so to every agent that reads it.
 
@@ -407,7 +407,7 @@ on the result — the CLI reports, the agent applies the judgment half.
 | Slash command | Equivalent |
 | --- | --- |
 | `/jig init` | `jig init` — then states the mode it chose and what it wired |
-| `/jig check` | `jig check` — then applies the 107 judgment rules and reports both halves |
+| `/jig check` | `jig check` — then applies the 120 judgment rules and reports both halves |
 | `/jig explain C-19` | `jig explain C-19` — prints the rule as-is, without paraphrasing it |
 | `/jig explain contrast` | `jig explain contrast` — every rule matching a word, when you do not have an id |
 | `/jig install --agent cursor` | `jig install --agent cursor` |
@@ -489,6 +489,9 @@ before you say yes:
   the navigation you would expect there.
 - **States cover what the page will meet.** Empty, one, a lot, loading, failure:
   whichever the page can actually be in.
+- **Everything that moves has a reason.** Each line of `motion:` names what
+  moves, what sets it off, and what it tells the reader. Cut any line that
+  can't say, and expect nothing on the page to move that the list leaves out.
 - **Open questions were asked, not answered for you.** A spec touching an item
   under `Unresolved` in `DECISIONS.md` carries your answer, and a field reading
   `unspecified — make chooses one it can defend` is one you can decide now.
@@ -746,12 +749,12 @@ treatment.
 
 | File | Contents |
 | --- | --- |
-| `rules/00-anti-patterns.md` | 125 universal rules with corrections |
+| `rules/00-anti-patterns.md` | 128 universal rules with corrections |
 | `rules/01-modes.md` | `editorial` / `product` / `operator` profiles |
 | `rules/02-tokens.md` | Token contract, naming, consumption |
 | `rules/03-patterns.md` | Component anatomy and behaviour |
 | `rules/04-principles.md` | Five frames + seven tiebreakers |
-| `rules/05-copy.md` | Interface text rules |
+| `rules/05-copy.md` | Interface text rules, and the prose a page ships |
 | `examples/<ID>.html` | For every rule, a small dont and do: self-contained HTML fragments that render in a sandboxed frame. `jig explain <ID>` names the file. |
 | `<css dir>/jig/brand.*.css` | Identity. One per project. |
 | `<css dir>/jig/mode.*.css` | Density, scale, rhythm, motion |

package/dist/index.js

@@ -28,7 +28,7 @@ function assetRoot(startDir = getPackageRoot()) {
   let current = startDir;
   const { root } = parse(startDir);
   while (true) {
-    if (existsSync(join(current, ASSET_MARKER))) return current;
+    if (existsSync(join(current, ASSET_MARKER))) return sourceOf(current);
     if (current === root) {
       throw new Error(
         `assetRoot(): could not find an ancestor of "${startDir}" containing "${ASSET_MARKER}"`
@@ -37,6 +37,11 @@ function assetRoot(startDir = getPackageRoot()) {
     current = dirname(current);
   }
 }
+function sourceOf(found) {
+  if (isPublishedBuild(found)) return found;
+  const repo = join(found, "..", "..");
+  return existsSync(join(repo, ASSET_MARKER)) && existsSync(join(repo, "packages", "cli", "package.json")) ? repo : found;
+}
 function isPublishedBuild(packageRoot2) {
   return packageRoot2.split(/[\\/]/).includes("node_modules");
 }
@@ -1522,8 +1527,9 @@ Example: ${example} (a dont and a do, each a self-contained HTML fragment)` : re
   const idBody = ids.filter((e) => !idTitle.includes(e) && matches(e.text, needle));
   const secTitle = secs.filter((e) => matches(e.title, needle));
   const secBody = secs.filter((e) => !secTitle.includes(e) && matches(e.text, needle));
+  const opens = (e) => e.title.toLowerCase().startsWith(needle.toLowerCase()) ? 0 : 1;
   const hits = [
-    ...idTitle.sort((a, b) => byNumber(a.id, b.id)),
+    ...idTitle.sort((a, b) => opens(a) - opens(b) || byNumber(a.id, b.id)),
     ...idBody.sort((a, b) => byNumber(a.id, b.id)),
     ...secTitle,
     ...secBody
@@ -3505,19 +3511,21 @@ function indentedProse(source) {
   const blank3 = (m) => " ".repeat(m.length);
   return source.split("\n").map((line) => /^\s*(-|\/\/|#(?!\w)|=)/.test(line) ? blank3(line) : line).join("\n");
 }
+function readerSpans(file, raw) {
+  const markdown = MARKDOWN.test(file);
+  const indented = INDENTED.test(file);
+  const masked = markdown ? markdownProse(raw) : indented ? indentedProse(maskNonProse(raw)) : maskNonProse(raw);
+  const script = SCRIPT.test(file);
+  return markdown || indented ? [{ index: 0, text: masked }] : proseSpans(masked, !script).filter((span) => !script || !CODEY.test(span.text));
+}
 var emDash = {
   name: "em-dash",
   appliesTo: (file) => isReaderText(file),
   run(_source, file, ctx) {
-    const markdown = MARKDOWN.test(file);
-    const indented = INDENTED.test(file);
-    const masked = markdown ? markdownProse(ctx.raw) : indented ? indentedProse(maskNonProse(ctx.raw)) : maskNonProse(ctx.raw);
     const starts = buildLineIndex(ctx.raw);
     const findings = [];
     const seen = /* @__PURE__ */ new Set();
-    const script = SCRIPT.test(file);
-    const spans = markdown || indented ? [{ index: 0, text: masked }] : proseSpans(masked, !script).filter((span) => !script || !CODEY.test(span.text));
-    for (const span of spans) {
+    for (const span of readerSpans(file, ctx.raw)) {
       if (!EM_DASH.test(span.text)) continue;
       for (const hit of span.text.matchAll(/\u2014/g)) {
         const line = lineForOffset(starts, span.index + hit.index);
@@ -3539,6 +3547,135 @@ var emDash = {
   }
 };
 
+// src/check/detectors/prose.ts
+var FORMULA = new RegExp(
+  [
+    String.raw`in today['’]s (?:fast[- ]paced|rapidly|ever[- ]|increasingly|digital|modern|busy)`,
+    String.raw`in an (?:increasingly|ever[- ](?:changing|evolving)) \w+ (?:world|landscape|age|marketplace|era)`,
+    String.raw`as technology continues to evolve`,
+    String.raw`it(?: is|['’]s) (?:important|worth) (?:to note|noting)`,
+    String.raw`let['’]s (?:dive|delve)\b`,
+    String.raw`here['’]s the thing\b`,
+    String.raw`without further ado`,
+    String.raw`in conclusion\b`,
+    String.raw`only time will tell`,
+    String.raw`the future (?:looks|is) (?:bright|incredibly promising)`
+  ].map((p) => `\\b${p}`).join("|"),
+  "gi"
+);
+function maskQuotations(raw) {
+  const blank3 = (m) => m.replace(/[^\n]/g, " ");
+  return raw.replace(/<blockquote\b[\s\S]*?<\/blockquote\s*>/gi, blank3).replace(/<q\b[\s\S]*?<\/q\s*>/gi, blank3).replace(/^ {0,3}>[^\n]*/gm, blank3);
+}
+var formulaPhrase = {
+  name: "formula-phrase",
+  appliesTo: (file) => isReaderText(file),
+  run(_source, file, ctx) {
+    const starts = buildLineIndex(ctx.raw);
+    const findings = [];
+    const seen = /* @__PURE__ */ new Set();
+    for (const span of readerSpans(file, maskQuotations(ctx.raw))) {
+      for (const hit of span.text.matchAll(FORMULA)) {
+        const line = lineForOffset(starts, span.index + hit.index);
+        if (seen.has(line)) continue;
+        seen.add(line);
+        findings.push(
+          mkFinding(
+            ctx,
+            "formula-phrase",
+            file,
+            line,
+            `a formula phrase ("${hit[0]}"): start with the point, and end when it has been made`,
+            sourceLine(ctx.raw, line)
+          )
+        );
+      }
+    }
+    return findings.sort((a, b) => a.line - b.line);
+  }
+};
+var HEADING3 = /^ {0,3}#{1,6}[ \t]+(.+)$/gm;
+var FENCE = /^ {0,3}(`{3,}|~{3,})[\s\S]*?^ {0,3}\1[^\n]*$/gm;
+var headingEmoji = {
+  name: "heading-emoji",
+  appliesTo: (file) => isReaderText(file) && hasExtension(file, [".md", ".markdown"]) && !isStyleBearing(file),
+  run(_source, file, ctx) {
+    const masked = ctx.raw.replace(FENCE, (m) => m.replace(/[^\n]/g, " "));
+    const starts = buildLineIndex(ctx.raw);
+    const findings = [];
+    for (const heading of masked.matchAll(HEADING3)) {
+      const glyph = [...heading[1].matchAll(EMOJI_RE)].find((m) => !TEXTUAL.has(m[0]));
+      if (!glyph) continue;
+      const line = lineForOffset(starts, heading.index);
+      findings.push(
+        mkFinding(
+          ctx,
+          "heading-emoji",
+          file,
+          line,
+          `an emoji in a heading ("${glyph[0]}"): let the words carry it; a screen reader reads the emoji's name first`,
+          sourceLine(ctx.raw, line)
+        )
+      );
+    }
+    return findings;
+  }
+};
+
+// src/check/detectors/layout-motion.ts
+var LAYOUT = String.raw`(?:(?:min-|max-)?(?:width|height)|(?:inline|block)-size|top|left|right|bottom|inset(?:-[a-z-]+)?|margin(?:-[a-z-]+)?|padding(?:-[a-z-]+)?)`;
+var LAYOUT_NAME = new RegExp(`^${LAYOUT}$`, "i");
+var TRANSITION = /(?<![-\w])transition(-property)?\s*:\s*([^;}]+)/gi;
+var KEYFRAMES = /@(?:-webkit-)?keyframes\b[^{]*\{/gi;
+var KEYFRAME_DECL = new RegExp(`(?<![-\\w])(${LAYOUT})\\s*:`, "gi");
+var TAILWIND = new RegExp(`(?<![-\\w\\[])transition-(all|\\[[^\\]\\s]*?\\b${LAYOUT}\\b[^\\]\\s]*\\])(?![-\\w])`, "gi");
+function namedProperties(value, longhand) {
+  return value.split(",").map((item) => {
+    const words = item.trim().split(/\s+/);
+    return longhand ? words[0] : words.find((w) => /^[a-z-]+$/i.test(w) && !/^(ease|ease-in|ease-out|ease-in-out|linear|step-start|step-end|allow-discrete|normal|none)$/i.test(w)) ?? "";
+  }).filter(Boolean);
+}
+function blockEnd(source, open) {
+  let depth = 0;
+  for (let i = open; i < source.length; i++) {
+    if (source[i] === "{") depth++;
+    else if (source[i] === "}" && --depth === 0) return i;
+  }
+  return source.length;
+}
+var layoutMotion = {
+  name: "layout-motion",
+  appliesTo: (file) => isStyleBearing(file),
+  run(source, file, ctx) {
+    const findings = [];
+    const seen = /* @__PURE__ */ new Set();
+    const report2 = (text, offset, message) => {
+      const line = lineForOffset(buildLineIndex(text), offset);
+      if (seen.has(line)) return;
+      seen.add(line);
+      findings.push(mkFinding(ctx, "layout-motion", file, line, message, sourceLine(text, line)));
+    };
+    for (const m of source.matchAll(TRANSITION)) {
+      const names = namedProperties(m[2], Boolean(m[1]));
+      const bad = names.find((n) => n.toLowerCase() === "all" || LAYOUT_NAME.test(n));
+      if (!bad) continue;
+      report2(source, m.index, bad.toLowerCase() === "all" ? "a transition on `all`: name the properties it covers, and animate transform and opacity" : `a transition on \`${bad}\`, which lays the page out again every frame: animate transform or opacity instead`);
+    }
+    for (const k of source.matchAll(KEYFRAMES)) {
+      const open = k.index + k[0].length - 1;
+      const body = source.slice(open, blockEnd(source, open));
+      for (const d of body.matchAll(KEYFRAME_DECL)) {
+        report2(source, open + d.index, `a keyframe animates \`${d[1]}\`, which lays the page out again every frame: animate transform or opacity instead`);
+      }
+    }
+    const raw = maskProseComments(ctx.raw);
+    for (const t of raw.matchAll(TAILWIND)) {
+      report2(ctx.raw, t.index, `\`${t[0]}\` animates ${t[1] === "all" ? "every property that changes" : "layout"}: use \`transition\`, \`transition-opacity\` or \`transition-transform\``);
+    }
+    return findings.sort((a, b) => a.line - b.line);
+  }
+};
+
 // src/check/detectors/semantic-element.ts
 var BODY = /<body\b/i;
 var MAIN = /<main\b|role\s*=\s*["']main["']/i;
@@ -4094,6 +4231,9 @@ var DETECTORS = [
   menuState,
   undeclaredToken,
   emDash,
+  formulaPhrase,
+  headingEmoji,
+  layoutMotion,
   semanticElement,
   metadata,
   interfaceSafety,
@@ -6525,7 +6665,7 @@ function probeContradictions(probes, verdictOf, indexable = true) {
 // src/check/decisions.ts
 import { existsSync as existsSync21, readFileSync as readFileSync28 } from "fs";
 import { join as join35, posix as posix3 } from "path";
-var HEADING3 = /^(#{2,3})\s+(.+?)\s*$/gm;
+var HEADING4 = /^(#{2,3})\s+(.+?)\s*$/gm;
 var NOT_A_DECISION = /^(unresolved|open questions?|undecided|contents?|index)$/i;
 function decisionsFile(projectRoot) {
   const candidates = ["jig/DECISIONS.md", "DECISIONS.md", "src/jig/DECISIONS.md", "src/styles/jig/DECISIONS.md", ".jig/DECISIONS.md"];
@@ -6552,7 +6692,7 @@ function decisionHeadings(projectRoot) {
   } catch {
     return headings;
   }
-  for (const match of body.matchAll(HEADING3)) {
+  for (const match of body.matchAll(HEADING4)) {
     const name = match[2].replace(/[`*]/g, "").trim();
     if (!name || NOT_A_DECISION.test(name)) continue;
     if (!headings.has(name)) headings.set(name, match[0].trim());
@@ -6660,6 +6800,18 @@ function specProblems(spec) {
   if (critique !== void 0 && !/^(each|at-ship)$/i.test(critique)) {
     problems.push(`${spec.path}: \`critique: ${critique}\` is neither \`each\` nor \`at-ship\`. Leave it out to follow the project's default.`);
   }
+  const motion = /^motion\s*:[ \t]*(.*)\n?((?:[ \t]+-.*\n?)*)/im.exec(front);
+  if (motion) {
+    const inline = motion[1].replace(/\s+#.*$/, "").trim();
+    const items = motion[2].split("\n").map((l) => l.replace(/^[ \t]+-\s*/, "").trim()).filter(Boolean);
+    if (!items.length && !/^none$/i.test(inline)) {
+      problems.push(`${spec.path}: \`motion:\` is neither \`none\` nor a list. List each movement as \`- <what moves>: <how>, on <trigger>; tells <what the reader learns>\`, or write \`motion: none\`.`);
+    }
+    const unsaid = items.filter((i) => !/\bon\b/i.test(i) || !/\btells?\b/i.test(i));
+    if (unsaid.length) {
+      problems.push(`${spec.path}: ${unsaid.length === 1 ? "a movement in `motion:` does" : `${unsaid.length} movements in \`motion:\` do`} not say what triggers it and what it tells the reader ("${unsaid[0]}"). Write \`on <trigger>; tells <what>\`, or cut the movement.`);
+    }
+  }
   for (const field of ["feature", "surface", "mode", "sizes", "confirmed", "mockup"]) {
     if (!has(field)) problems.push(`${spec.path} frontmatter has no \`${field}:\`.`);
   }
@@ -6803,7 +6955,7 @@ function checkArm(name, file, required, otherPass, extraAllowed, extraRequired,
     seen.add(id);
     const pass = otherPass.get(id);
     if (!required.includes(id) && !extraAllowed.has(id)) {
-      errors.push(pass === "mechanical" ? `${name}.json: ${id} is a mechanical rule \u2014 \`jig check\` decides it, so it has no verdict here. Remove it.` : pass ? `${name}.json: ${id} is a pass: ${pass} rule \u2014 it belongs to the other arm.` : `${name}.json: ${written} is not a rule or spec in this corpus. Run \`jig explain ${written}\`; an id that does not resolve is not a verdict.`);
+      errors.push(pass === "mechanical" ? `${name}.json: ${id} is a mechanical rule \u2014 \`jig check\` decides it, so it has no verdict here. Remove it.` : pass ? `${name}.json: ${id} is a pass: ${pass} rule \u2014 it belongs to the other arm.` : `${name}.json: ${written} is not a rule or spec in this corpus. Run \`jig explain ${written}\`; an id that does not resolve is not a verdict. A difference from the spec, or from a source the page quotes, is not a rule: list it under \`differences\` in the same file.`);
       continue;
     }
     if (typeof v.verdict !== "string" || !RULE_VERDICTS.includes(v.verdict)) {
@@ -6824,6 +6976,16 @@ function checkArm(name, file, required, otherPass, extraAllowed, extraRequired,
     if (v.verdict === "finding") findings++;
   }
   reasonProblems(`${name}.json`, reasons, errors);
+  const differences = file.differences;
+  if (differences !== void 0) {
+    if (!Array.isArray(differences)) errors.push(`${name}.json: \`differences\` is not a list.`);
+    else for (const d of differences) {
+      const said = (x) => typeof x === "string" && x.trim() !== "";
+      if (!said(d?.what) || !said(d?.where) || !said(d?.against)) {
+        errors.push(`${name}.json: a difference needs \`what\` (what differs), \`where\` (the page's file and line) and \`against\` (the spec line or source it differs from).`);
+      } else findings++;
+    }
+  }
   const missing = [...required, ...extraRequired].filter((id) => !seen.has(id));
   if (missing.length) {
     errors.push(`${name}.json: ${missing.length} of ${total} ids have no verdict: ${missing.join(", ")}. Re-run the arm; never report a short pass.`);
@@ -6863,7 +7025,7 @@ function checkDecisions(projectRoot, dir, errors) {
     }
     seen.add(match);
     if (typeof v.verdict !== "string" || !VERDICTS.includes(v.verdict)) {
-      errors.push(`decisions.json: "${match}" has verdict ${JSON.stringify(v.verdict)} \u2014 it must be ok, finding or n/a.`);
+      errors.push(v.verdict === "ruled" ? `decisions.json: "${match}" is marked ruled. A decision is not excused by a decision: judge whether the page follows it, ok, finding or n/a. \`ruled\` is for a rule in screen.json or code.json that a decision overrides.` : `decisions.json: "${match}" has verdict ${JSON.stringify(v.verdict)} \u2014 it must be ok, finding or n/a.`);
       continue;
     }
     const reason = typeof v.reason === "string" ? v.reason.trim() : "";
@@ -7397,12 +7559,21 @@ function changedSinceLock(projectRoot, dir) {
     return void 0;
   }
 }
+function supersededBy(front) {
+  const named = /^\s*superseded_by\s*:\s*(.*)$/im.exec(front)?.[1]?.replace(/\s+#.*$/, "").trim();
+  return named ? named : void 0;
+}
 function pageStatus(projectRoot, surface) {
   const spec = readFileSync33(join40(projectRoot, ".jig", "specs", `${surface}.spec.md`), "utf8");
   const front = spec.split(/^---\s*$/m)[1] ?? "";
   if (!/^\s*confirmed\s*:\s*true\b/im.test(front)) {
     return { surface, state: "in-progress", detail: "its spec is not confirmed, so nothing of it is built to ship" };
   }
+  const successor = supersededBy(front);
+  if (successor !== void 0) {
+    const file = successor.replace(/(\.spec\.md)?$/, ".spec.md");
+    return existsSync24(join40(projectRoot, ".jig", "specs", file)) ? { surface, state: "superseded", detail: `superseded by ${file}, whose critique judges its page` } : { surface, state: "incomplete", detail: `\`superseded_by: ${successor}\` names a spec that does not exist in .jig/specs` };
+  }
   const dir = join40(projectRoot, ".jig", "critique", surface);
   if (!existsSync24(join40(dir, "screen.json")) && !existsSync24(join40(dir, "code.json"))) {
     return { surface, state: "never", detail: "never critiqued" };
@@ -7433,11 +7604,11 @@ function ship(opts) {
   const specsDir = join40(root, ".jig", "specs");
   const surfaces = existsSync24(specsDir) ? readdirSync15(specsDir).filter((f) => f.endsWith(".spec.md") && !f.startsWith("_")).map((f) => f.replace(/\.spec\.md$/, "")).sort() : [];
   const pages = surfaces.map((s) => pageStatus(root, s));
-  const owed = pages.filter((p) => p.state !== "judged" && p.state !== "in-progress");
+  const owed = pages.filter((p) => p.state !== "judged" && p.state !== "in-progress" && p.state !== "superseded");
   const ready = mechanicalErrors === 0 && seoErrors === 0 && owed.length === 0;
   const count = (state) => pages.filter((p) => p.state === state).length;
-  const line = `JIG_SHIP: ready=${ready ? "yes" : "no"} mechanical=${mechanicalErrors} seo=${seoErrors} pages=${pages.length} judged=${count("judged")} owed=${owed.length} in-progress=${count("in-progress")}`;
-  const mark = { judged: "\u2713", never: "\u2717", changed: "\u2717", reprobe: "\u2717", deferred: "\u2717", incomplete: "\u2717", findings: "\u2717", "in-progress": "\xB7" };
+  const line = `JIG_SHIP: ready=${ready ? "yes" : "no"} mechanical=${mechanicalErrors} seo=${seoErrors} pages=${pages.length} judged=${count("judged")} owed=${owed.length} in-progress=${count("in-progress")} superseded=${count("superseded")}`;
+  const mark = { judged: "\u2713", never: "\u2717", changed: "\u2717", reprobe: "\u2717", deferred: "\u2717", incomplete: "\u2717", findings: "\u2717", "in-progress": "\xB7", superseded: "\xB7" };
   const report2 = [
     `  ${mechanicalErrors === 0 ? "\u2713" : "\u2717"} check --all --ci: ${mechanicalErrors} mechanical error${mechanicalErrors === 1 ? "" : "s"}`,
     `  ${seoErrors === 0 ? "\u2713" : "\u2717"} seo: ${seoErrors} error${seoErrors === 1 ? "" : "s"}`,

package/examples/G-161.html

@@ -0,0 +1,7 @@
+<!-- G-161 · A layout change that jumps -->
+<figure data-example="dont">
+  <div style="font-family:system-ui,-apple-system,'Segoe UI',sans-serif;font-size:13px;line-height:1.45;color:#1f1f1f;background:#f5f5f4;padding:16px;min-height:176px;box-sizing:border-box;"><div style="display:flex;flex-direction:column;gap:6px;"><p style="margin:0;font-size:12px;color:#57534e;">Row 2 deleted. In the next frame:</p><div style="background:#fff;border:1px solid #d6d3d1;border-radius:4px;padding:6px 10px;font-size:13px;">Pay the invoice</div><div style="background:#fff;border:1px solid #d6d3d1;border-radius:4px;padding:6px 10px;font-size:13px;">Book the venue</div><div style="background:#fff;border:1px solid #d6d3d1;border-radius:4px;padding:6px 10px;font-size:13px;">Send the agenda</div><p style="margin:0;font-size:12px;color:#57534e;">The rows below snapped up. Nothing shows what went where.</p></div></div>
+</figure>
+<figure data-example="do">
+  <div style="font-family:system-ui,-apple-system,'Segoe UI',sans-serif;font-size:13px;line-height:1.45;color:#1f1f1f;background:#f5f5f4;padding:16px;min-height:176px;box-sizing:border-box;"><div style="display:flex;flex-direction:column;gap:6px;"><p style="margin:0;font-size:12px;color:#57534e;">Row 2 deleted. Over the next 150ms:</p><div style="background:#fff;border:1px solid #d6d3d1;border-radius:4px;padding:6px 10px;font-size:13px;">Pay the invoice</div><div style="background:#fff;border:1px solid #d6d3d1;border-radius:4px;padding:6px 10px;font-size:13px;box-shadow:0 0 0 2px #a8a29e;">Book the venue ↑</div><div style="background:#fff;border:1px solid #d6d3d1;border-radius:4px;padding:6px 10px;font-size:13px;box-shadow:0 0 0 2px #a8a29e;">Send the agenda ↑</div><p style="margin:0;font-size:12px;color:#57534e;">The rows below slide up into the gap, so the eye follows them.</p></div></div>
+</figure>

package/examples/G-162.html

@@ -0,0 +1,18 @@
+<!-- G-162 · Animating layout, or everything -->
+<figure data-example="dont">
+  <div style="font-family:system-ui,-apple-system,'Segoe UI',sans-serif;font-size:13px;line-height:1.45;color:#1f1f1f;background:#f5f5f4;padding:16px;min-height:176px;box-sizing:border-box;"><div style="display:flex;flex-direction:column;gap:6px;"><pre style="margin:0;font-family:ui-monospace,Menlo,monospace;font-size:12px;background:#fff;border:1px solid #d6d3d1;border-radius:4px;padding:8px;white-space:pre-wrap;">.panel {
+  transition: all 200ms;
+}
+.row {
+  transition: height 200ms;
+}</pre></div></div>
+</figure>
+<figure data-example="do">
+  <div style="font-family:system-ui,-apple-system,'Segoe UI',sans-serif;font-size:13px;line-height:1.45;color:#1f1f1f;background:#f5f5f4;padding:16px;min-height:176px;box-sizing:border-box;"><div style="display:flex;flex-direction:column;gap:6px;"><pre style="margin:0;font-family:ui-monospace,Menlo,monospace;font-size:12px;background:#fff;border:1px solid #d6d3d1;border-radius:4px;padding:8px;white-space:pre-wrap;">.panel {
+  transition: opacity 150ms var(--ease-out),
+    transform 150ms var(--ease-out);
+}
+.row {
+  transition: transform 150ms var(--ease-in-out);
+}</pre></div></div>
+</figure>

package/examples/G-163.html

@@ -0,0 +1,7 @@
+<!-- G-163 · Several things moving at once -->
+<figure data-example="dont">
+  <div style="font-family:system-ui,-apple-system,'Segoe UI',sans-serif;font-size:13px;line-height:1.45;color:#1f1f1f;background:#f5f5f4;padding:16px;min-height:176px;box-sizing:border-box;"><div style="display:flex;flex-direction:column;gap:6px;"><div style="background:#fff;border:1px solid #d6d3d1;border-radius:4px;padding:6px 10px;font-size:13px;">Gradient drifting behind the hero</div><div style="background:#fff;border:1px solid #d6d3d1;border-radius:4px;padding:6px 10px;font-size:13px;">Scroll arrow bouncing</div><div style="background:#fff;border:1px solid #d6d3d1;border-radius:4px;padding:6px 10px;font-size:13px;">Logo ticker scrolling</div><div style="background:#fff;border:1px solid #d6d3d1;border-radius:4px;padding:6px 10px;font-size:13px;">"New" badge pulsing</div><p style="margin:0;font-size:12px;color:#57534e;">Four loops at once. The saved message arrives and nobody sees it.</p></div></div>
+</figure>
+<figure data-example="do">
+  <div style="font-family:system-ui,-apple-system,'Segoe UI',sans-serif;font-size:13px;line-height:1.45;color:#1f1f1f;background:#f5f5f4;padding:16px;min-height:176px;box-sizing:border-box;"><div style="display:flex;flex-direction:column;gap:6px;"><div style="background:#fff;border:1px solid #d6d3d1;border-radius:4px;padding:6px 10px;font-size:13px;">Hero, still</div><div style="background:#fff;border:1px solid #d6d3d1;border-radius:4px;padding:6px 10px;font-size:13px;">Scroll arrow, still</div><div style="background:#fff;border:1px solid #d6d3d1;border-radius:4px;padding:6px 10px;font-size:13px;">Logo row, still</div><div style="background:#fff;border:1px solid #d6d3d1;border-radius:4px;padding:6px 10px;font-size:13px;box-shadow:0 0 0 2px #a8a29e;">Saved ✓</div><p style="margin:0;font-size:12px;color:#57534e;">One thing moves: the message the user caused.</p></div></div>
+</figure>

package/examples/I-148.html

@@ -0,0 +1,7 @@
+<!-- I-148 · A claim with no source -->
+<figure data-example="dont">
+  <div style="font-family:system-ui,-apple-system,'Segoe UI',sans-serif;font-size:13px;line-height:1.45;color:#1f1f1f;background:#f5f5f4;padding:16px;min-height:176px;box-sizing:border-box;"><div style="display:flex;flex-direction:column;gap:8px;"><p style="margin:0;font-size:14px;">Teams using Acme ship 37% faster.</p><p style="margin:0;font-size:14px;">A 2024 study found developers save 11 hours a week.</p></div></div>
+</figure>
+<figure data-example="do">
+  <div style="font-family:system-ui,-apple-system,'Segoe UI',sans-serif;font-size:13px;line-height:1.45;color:#1f1f1f;background:#f5f5f4;padding:16px;min-height:176px;box-sizing:border-box;"><div style="display:flex;flex-direction:column;gap:8px;"><p style="margin:0;font-size:14px;">In our own use, releases went from weekly to twice a week.</p><p style="margin:0;font-size:12px;color:#57534e;">Source: our release log, January to June 2026</p></div></div>
+</figure>

package/examples/I-149.html

@@ -0,0 +1,7 @@
+<!-- I-149 · Specific in sound, empty in fact -->
+<figure data-example="dont">
+  <div style="font-family:system-ui,-apple-system,'Segoe UI',sans-serif;font-size:13px;line-height:1.45;color:#1f1f1f;background:#f5f5f4;padding:16px;min-height:176px;box-sizing:border-box;"><div style="display:flex;flex-direction:column;gap:8px;"><p style="margin:0;font-size:14px;">Organisations that adopt these practices often see significant gains in efficiency.</p></div></div>
+</figure>
+<figure data-example="do">
+  <div style="font-family:system-ui,-apple-system,'Segoe UI',sans-serif;font-size:13px;line-height:1.45;color:#1f1f1f;background:#f5f5f4;padding:16px;min-height:176px;box-sizing:border-box;"><div style="display:flex;flex-direction:column;gap:8px;"><p style="margin:0;font-size:14px;">The billing team closed March in two days instead of five.</p></div></div>
+</figure>

package/examples/I-150.html

@@ -0,0 +1,7 @@
+<!-- I-150 · Formula openers, closers and signposts -->
+<figure data-example="dont">
+  <div style="font-family:system-ui,-apple-system,'Segoe UI',sans-serif;font-size:13px;line-height:1.45;color:#1f1f1f;background:#f5f5f4;padding:16px;min-height:176px;box-sizing:border-box;"><div style="display:flex;flex-direction:column;gap:8px;"><p style="margin:0;font-size:14px;">In today's rapidly changing world, it is important to note that backups matter.</p><p style="margin:0;font-size:14px;">In conclusion, only time will tell.</p></div></div>
+</figure>
+<figure data-example="do">
+  <div style="font-family:system-ui,-apple-system,'Segoe UI',sans-serif;font-size:13px;line-height:1.45;color:#1f1f1f;background:#f5f5f4;padding:16px;min-height:176px;box-sizing:border-box;"><div style="display:flex;flex-direction:column;gap:8px;"><p style="margin:0;font-size:14px;">Back up before you migrate.</p><p style="margin:0;font-size:14px;">A failed migration cannot be undone.</p></div></div>
+</figure>

package/examples/I-151.html

@@ -0,0 +1,7 @@
+<!-- I-151 · Saying it twice -->
+<figure data-example="dont">
+  <div style="font-family:system-ui,-apple-system,'Segoe UI',sans-serif;font-size:13px;line-height:1.45;color:#1f1f1f;background:#f5f5f4;padding:16px;min-height:176px;box-sizing:border-box;"><div style="display:flex;flex-direction:column;gap:8px;"><p style="margin:0;font-size:14px;">Jig checks a page before it ships.</p><p style="margin:0;font-size:14px;">It reads the rules and applies them.</p><p style="margin:0;font-size:14px;">In short, Jig makes sure every page is checked before shipping.</p></div></div>
+</figure>
+<figure data-example="do">
+  <div style="font-family:system-ui,-apple-system,'Segoe UI',sans-serif;font-size:13px;line-height:1.45;color:#1f1f1f;background:#f5f5f4;padding:16px;min-height:176px;box-sizing:border-box;"><div style="display:flex;flex-direction:column;gap:8px;"><p style="margin:0;font-size:14px;">Jig checks a page before it ships.</p><p style="margin:0;font-size:14px;">It reads the rules and applies them.</p><p style="margin:0;font-size:14px;">A machine decides 39 of them; a reviewer judges the rest.</p></div></div>
+</figure>

package/examples/I-152.html

@@ -0,0 +1,7 @@
+<!-- I-152 · A rhetorical shape on repeat -->
+<figure data-example="dont">
+  <div style="font-family:system-ui,-apple-system,'Segoe UI',sans-serif;font-size:13px;line-height:1.45;color:#1f1f1f;background:#f5f5f4;padding:16px;min-height:176px;box-sizing:border-box;"><div style="display:flex;flex-direction:column;gap:8px;"><p style="margin:0;font-size:14px;">It's not a tool, it's a workflow.</p><p style="margin:0;font-size:14px;">It's not a checklist, it's a habit.</p><p style="margin:0;font-size:14px;">It's not a rule, it's a promise.</p></div></div>
+</figure>
+<figure data-example="do">
+  <div style="font-family:system-ui,-apple-system,'Segoe UI',sans-serif;font-size:13px;line-height:1.45;color:#1f1f1f;background:#f5f5f4;padding:16px;min-height:176px;box-sizing:border-box;"><div style="display:flex;flex-direction:column;gap:8px;"><p style="margin:0;font-size:14px;">It runs in your editor.</p><p style="margin:0;font-size:14px;">Before you ship, it checks each page and names the rule a line breaks.</p></div></div>
+</figure>

package/examples/I-153.html

@@ -0,0 +1,7 @@
+<!-- I-153 · Enthusiasm the content has not earned -->
+<figure data-example="dont">
+  <div style="font-family:system-ui,-apple-system,'Segoe UI',sans-serif;font-size:13px;line-height:1.45;color:#1f1f1f;background:#f5f5f4;padding:16px;min-height:176px;box-sizing:border-box;"><div style="display:flex;flex-direction:column;gap:8px;"><p style="margin:0;font-size:14px;">An incredibly exciting, truly transformative update. The possibilities are endless.</p></div></div>
+</figure>
+<figure data-example="do">
+  <div style="font-family:system-ui,-apple-system,'Segoe UI',sans-serif;font-size:13px;line-height:1.45;color:#1f1f1f;background:#f5f5f4;padding:16px;min-height:176px;box-sizing:border-box;"><div style="display:flex;flex-direction:column;gap:8px;"><p style="margin:0;font-size:14px;">Exports now include every column, so the monthly report takes one download instead of four.</p></div></div>
+</figure>

package/examples/I-154.html

@@ -0,0 +1,7 @@
+<!-- I-154 · Stacked hedges -->
+<figure data-example="dont">
+  <div style="font-family:system-ui,-apple-system,'Segoe UI',sans-serif;font-size:13px;line-height:1.45;color:#1f1f1f;background:#f5f5f4;padding:16px;min-height:176px;box-sizing:border-box;"><div style="display:flex;flex-direction:column;gap:8px;"><p style="margin:0;font-size:14px;">It may potentially suggest that this could, in some cases, help.</p></div></div>
+</figure>
+<figure data-example="do">
+  <div style="font-family:system-ui,-apple-system,'Segoe UI',sans-serif;font-size:13px;line-height:1.45;color:#1f1f1f;background:#f5f5f4;padding:16px;min-height:176px;box-sizing:border-box;"><div style="display:flex;flex-direction:column;gap:8px;"><p style="margin:0;font-size:14px;">The evidence suggests it helps on pages over 2,000 words.</p></div></div>
+</figure>

package/examples/I-155.html

@@ -0,0 +1,7 @@
+<!-- I-155 · Emoji in headings -->
+<figure data-example="dont">
+  <div style="font-family:system-ui,-apple-system,'Segoe UI',sans-serif;font-size:13px;line-height:1.45;color:#1f1f1f;background:#f5f5f4;padding:16px;min-height:176px;box-sizing:border-box;"><div style="display:flex;flex-direction:column;gap:8px;"><div style="font-size:16px;font-weight:700;line-height:1.2;">🚀 Getting started</div><p style="margin:0;font-size:14px;">Install it with one command.</p><div style="font-size:16px;font-weight:700;line-height:1.2;">✨ Key features</div><p style="margin:0;font-size:14px;">It checks each page before you ship.</p></div></div>
+</figure>
+<figure data-example="do">
+  <div style="font-family:system-ui,-apple-system,'Segoe UI',sans-serif;font-size:13px;line-height:1.45;color:#1f1f1f;background:#f5f5f4;padding:16px;min-height:176px;box-sizing:border-box;"><div style="display:flex;flex-direction:column;gap:8px;"><div style="font-size:16px;font-weight:700;line-height:1.2;">Install Jig in one command</div><p style="margin:0;font-size:14px;">Install it with one command.</p><div style="font-size:16px;font-weight:700;line-height:1.2;">What each check reports</div><p style="margin:0;font-size:14px;">It checks each page before you ship.</p></div></div>
+</figure>

package/examples/I-156.html

@@ -0,0 +1,7 @@
+<!-- I-156 · Structure imposed rather than earned -->
+<figure data-example="dont">
+  <div style="font-family:system-ui,-apple-system,'Segoe UI',sans-serif;font-size:13px;line-height:1.45;color:#1f1f1f;background:#f5f5f4;padding:16px;min-height:176px;box-sizing:border-box;"><div style="display:flex;flex-direction:column;gap:8px;"><div style="font-size:14px;font-weight:700;line-height:1.2;">Overview</div><p style="margin:0;font-size:14px;">Jig checks pages.</p><div style="font-size:14px;font-weight:700;line-height:1.2;">Key benefits</div><p style="margin:0;font-size:14px;">It is fast.</p><div style="font-size:14px;font-weight:700;line-height:1.2;">Conclusion</div><p style="margin:0;font-size:14px;">Jig checks pages.</p></div></div>
+</figure>
+<figure data-example="do">
+  <div style="font-family:system-ui,-apple-system,'Segoe UI',sans-serif;font-size:13px;line-height:1.45;color:#1f1f1f;background:#f5f5f4;padding:16px;min-height:176px;box-sizing:border-box;"><div style="display:flex;flex-direction:column;gap:8px;"><div style="font-size:14px;font-weight:700;line-height:1.2;">Install Jig in one command</div><p style="margin:0;font-size:14px;">Run npx jig-ui init in your project.</p><div style="font-size:14px;font-weight:700;line-height:1.2;">Run your first check</div><p style="margin:0;font-size:14px;">Run npx jig-ui check. Each finding names its rule.</p></div></div>
+</figure>

package/examples/I-157.html

@@ -0,0 +1,7 @@
+<!-- I-157 · Nothing only the author could say -->
+<figure data-example="dont">
+  <div style="font-family:system-ui,-apple-system,'Segoe UI',sans-serif;font-size:13px;line-height:1.45;color:#1f1f1f;background:#f5f5f4;padding:16px;min-height:176px;box-sizing:border-box;"><div style="display:flex;flex-direction:column;gap:8px;"><p style="margin:0;font-size:14px;">The migration was challenging, but the team learned valuable lessons.</p></div></div>
+</figure>
+<figure data-example="do">
+  <div style="font-family:system-ui,-apple-system,'Segoe UI',sans-serif;font-size:13px;line-height:1.45;color:#1f1f1f;background:#f5f5f4;padding:16px;min-height:176px;box-sizing:border-box;"><div style="display:flex;flex-direction:column;gap:8px;"><p style="margin:0;font-size:14px;">The migration looked like a weekend's work. It took three weeks, because two services wrote the same table and nobody had written that down.</p></div></div>
+</figure>

package/examples/I-158.html

@@ -0,0 +1,7 @@
+<!-- I-158 · No point of view -->
+<figure data-example="dont">
+  <div style="font-family:system-ui,-apple-system,'Segoe UI',sans-serif;font-size:13px;line-height:1.45;color:#1f1f1f;background:#f5f5f4;padding:16px;min-height:176px;box-sizing:border-box;"><div style="display:flex;flex-direction:column;gap:8px;"><p style="margin:0;font-size:14px;">There are several factors to consider, each with its own trade-offs.</p></div></div>
+</figure>
+<figure data-example="do">
+  <div style="font-family:system-ui,-apple-system,'Segoe UI',sans-serif;font-size:13px;line-height:1.45;color:#1f1f1f;background:#f5f5f4;padding:16px;min-height:176px;box-sizing:border-box;"><div style="display:flex;flex-direction:column;gap:8px;"><p style="margin:0;font-size:14px;">The technology was not the hard part. Changing how procurement worked was.</p></div></div>
+</figure>

package/examples/I-159.html

@@ -0,0 +1,7 @@
+<!-- I-159 · An even rhythm -->
+<figure data-example="dont">
+  <div style="font-family:system-ui,-apple-system,'Segoe UI',sans-serif;font-size:13px;line-height:1.45;color:#1f1f1f;background:#f5f5f4;padding:16px;min-height:176px;box-sizing:border-box;"><div style="display:flex;flex-direction:column;gap:8px;"><p style="margin:0;font-size:14px;">We started the project in May. We chose a small team for it. We wrote the plan in one week. We shipped the first page in June. We learned a lot along the way.</p></div></div>
+</figure>
+<figure data-example="do">
+  <div style="font-family:system-ui,-apple-system,'Segoe UI',sans-serif;font-size:13px;line-height:1.45;color:#1f1f1f;background:#f5f5f4;padding:16px;min-height:176px;box-sizing:border-box;"><div style="display:flex;flex-direction:column;gap:8px;"><p style="margin:0;font-size:14px;">We started in May with three people. The plan took a week. The first page took six, because nobody had asked support what customers searched for.</p></div></div>
+</figure>

package/examples/I-160.html

@@ -0,0 +1,7 @@
+<!-- I-160 · Feeling named, not shown -->
+<figure data-example="dont">
+  <div style="font-family:system-ui,-apple-system,'Segoe UI',sans-serif;font-size:13px;line-height:1.45;color:#1f1f1f;background:#f5f5f4;padding:16px;min-height:176px;box-sizing:border-box;"><div style="display:flex;flex-direction:column;gap:8px;"><p style="margin:0;font-size:14px;">I was fascinated by the results, which provided valuable insights.</p></div></div>
+</figure>
+<figure data-example="do">
+  <div style="font-family:system-ui,-apple-system,'Segoe UI',sans-serif;font-size:13px;line-height:1.45;color:#1f1f1f;background:#f5f5f4;padding:16px;min-height:176px;box-sizing:border-box;"><div style="display:flex;flex-direction:column;gap:8px;"><p style="margin:0;font-size:14px;">I did not expect the result. We had tested it three times, and it failed in exactly the same place.</p></div></div>
+</figure>

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "jig-ui",
-  "version": "0.22.0",
-  "description": "A design system for coding agents. 143 numbered UI rules, brand x mode design tokens, and an installer for Claude Code, Codex, Cursor and opencode.",
+  "version": "0.23.0",
+  "description": "A design system for coding agents. 159 numbered UI rules, brand x mode design tokens, and an installer for Claude Code, Codex, Cursor and opencode.",
   "license": "Apache-2.0",
   "type": "module",
   "bin": {

package/rules/00-anti-patterns.md

@@ -590,6 +590,25 @@ A pulse says "look here, something is happening". On a status that has not chang
 
 **Scope: this is about motion that answers an input or carries a state change.** It is not a ceiling on every animation on the page. Slow decorative looping motion — see `P-13` — runs for seconds by design, and is not covered here. The reason the two differ is the reason the numbers differ: interaction motion sits between the user and their task, so it must get out of the way; ambient motion is never in the way, so speed would only make it noticeable.
 
+### G-161 A layout change that jumps
+❌ A row deleted, and the rows below snap up into the gap in one frame. A filter applied, and the grid reshuffles with nothing to follow. A card opened into its detail view, with nothing connecting the two.
+✅ When the user's own action moves things, show where they went. The rows below slide up into the gap. Items that stay keep their identity and move to their new place; items that go fade out where they stood. A card grows into its detail view (`view-transition-name` on both, where the browser has View Transitions). Moves within the screen take `--ease-in-out` and `--duration-base`; a whole view changing, `--duration-slow`.
+A jump makes the user find their place again, and they cannot tell a row that moved from a row that changed. The move answers "where did it go?" before they have to ask.
+**Keep it instant** when the user did not cause the change: a live table updating under someone's pointer must not slide the row they were about to click. Also when most of the view changes at once, since a cut is clearer than twenty moves. Under reduced motion the change is instant, and focus or a live region says where things went (`G-43`).
+Technique, for a layout change CSS cannot transition: record each item's position before the change, apply it, then animate each item's `transform` from the old position to zero (first, last, invert, play). Never animate the layout properties themselves (`G-162`).
+
+### G-162 Animating layout, or everything
+❌ `transition: height 200ms`, `transition: all 150ms`, a keyframe that moves `top` or `margin-left`, Tailwind's `transition-all`
+✅ Animate `transform` and `opacity`. To move, `translate`; to grow, `scale` or a clip; to appear, `opacity`. Name the properties a transition covers: `transition: opacity var(--duration-fast) var(--ease-out), transform var(--duration-fast) var(--ease-out)`.
+`width`, `height`, `margin`, `padding`, `top`, `left` and their kin change layout, so the browser works out the position of everything around the element again on every frame, and on a slow phone the motion stutters. `transform` and `opacity` do not move anything else. `all` animates every property that changes, including a layout one someone adds next month, and nobody reading the rule can tell which.
+**One accepted case:** a disclosure opening to its content's height (`P-11`). Animate `grid-template-rows` from `0fr` to `1fr` on a wrapper, which the detector does not flag, or write the `height` transition with `<!-- jig-allow G-162: a disclosure grows to its content -->`.
+The detector warns on `transition` or `transition-property` naming `all` or a layout property; a keyframe step setting one; Tailwind's `transition-all` and `transition-[<layout property>]`. `P-13`'s "Animate `transform` and `opacity`" becomes a pointer here.
+
+### G-163 Several things moving at once
+❌ A hero with a drifting gradient, a bouncing scroll arrow, a logo ticker and a pulsing "New" badge, all running together.
+✅ At a time, one thing moves: the one the user caused, or the one they need to notice now. Things that move as one count as one: a list reordering, `P-13`'s ambient layers on one surface.
+Motion is the strongest pull on the eye a page has. Two things moving split it; four make the page restless, and the one that matters (a saved state, an error arriving) competes with decoration and loses. `G-145` is the one-dot case of this rule.
+
 ---
 
 ## H. Code-level

package/rules/01-modes.md

@@ -190,7 +190,7 @@ Attempting to vary these by mode is a category error:
 - **Accessibility floors.** Contrast, focus indication, target size, semantic markup. Identical in all three. `operator` being dense does not license a 24px tap target or a 3:1 body contrast.
 - **Brand identity.** Palette, typeface, logo, voice.
 - **State completeness.** Every mode renders loading, empty, error and disabled.
-- **The anti-pattern file.** All 125 rules in it apply everywhere.
+- **The anti-pattern file.** All 128 rules in it apply everywhere.
 
 ---
 

package/rules/02-tokens.md

@@ -243,6 +243,9 @@ away. That maps onto the tokens:
   the closer analogue, and we do not ship one: exits in this system fade or
   collapse in place rather than fly off screen, and a third easing token bought
   only that one case.
+- **Moving within the screen**, from one place to another: `--ease-in-out`. The
+  element is on screen at the start and the end, so it speeds up leaving its
+  place and slows into the new one (`G-161`).
 - **Never linear** for anything that moves. Linear reads as mechanical because
   nothing physical moves that way. Colour and opacity are the exception — a
   simple curve is enough there, and often linear is fine.

package/rules/03-patterns.md

@@ -429,7 +429,8 @@ it that they did not cause. Motion in those modes always means something changed
 - **Animate `transform` and `opacity`.** These run on the compositor. A loop that
   runs forever on every frame the page is open cannot afford animated `blur`,
   `box-shadow`, or anything that triggers layout — the cost is not paid once, it is
-  paid continuously, on whatever device the reader has.
+  paid continuously, on whatever device the reader has. `G-162` holds this for all motion;
+  here the cost is simply paid forever.
 
 **Anti-pattern:** ambient motion used to direct attention. It is atmosphere, not a
 signal. The moment it points at something it has become interaction motion badly

package/rules/05-copy.md

@@ -1,8 +1,8 @@
 # 05 · Copy
 
 **Status:** draft v0.1
-**Scope:** universal. Interface text in every mode.
-**Load when:** writing or reviewing any user-facing string — labels, buttons, headings, errors, empty states, help text.
+**Scope:** universal. Interface text in every mode, and the prose a page ships: docs, guides, marketing pages, blog posts.
+**Load when:** writing or reviewing any user-facing string — labels, buttons, headings, errors, empty states, help text — or any prose longer than a paragraph.
 
 Interface text is interface design. A screen with perfect spacing and a vague button label is a broken screen. Most of what follows costs nothing to apply and is invisible when done well.
 
@@ -142,6 +142,89 @@ See `P-01` for *where* the message goes and `F-37` for field-level validation te
 
 ---
 
+## Prose
+
+**Scope:** prose longer than a paragraph that a page ships: docs, guides,
+marketing pages, and everything under *Long-form* below. Interface strings stay
+under the rules above; `I-79`'s 20-word sentence limit is for them, not for
+prose. A page with no prose longer than a paragraph judges these `n/a`.
+
+These rules judge whether prose is specific, sourced and authored. They never
+judge who wrote it: a finding says the copy reads as generic, never that a
+model wrote it.
+
+### I-148 A claim with no source
+❌ "Teams using Acme ship 37% faster." "A 2024 Stanford study found…" A feature described that the product does not have.
+✅ Every figure, study, quotation, date and feature a page states traces to something in the project: its data, its docs, a link to the source, the product itself. Otherwise it is cut, or written as what it is: "in our own use", "we expect".
+A made-up figure reads exactly like a real one, and it is the claim a reader is most likely to repeat. Of everything here, it costs the most when it is wrong.
+
+### I-149 Specific in sound, empty in fact
+❌ "Organisations that adopt these practices often see significant gains in efficiency."
+✅ Name who, how many, how much, compared with what. "The billing team closed the month in two days instead of five."
+The test, as `I-81` has it for headlines: if the sentence would still be true after swapping in any other product, team or year, it says nothing.
+
+### I-150 Formula openers, closers and signposts
+❌ "In today's rapidly changing world…" "It is important to note that…" "Let's dive in." "Here's the thing:" "In conclusion…" "Only time will tell."
+✅ Start with the point; end when it has been made. Signpost only where a reader would otherwise be lost.
+`check` warns on a short, fixed list of phrases that are almost never needed; the judgment half covers the same habit in other words. A quotation keeps its own words, as with `I-118`.
+
+### I-151 Saying it twice
+❌ A conclusion that restates the introduction. A lead sentence repeated as the next section's opening. The same point made again in new words two paragraphs later.
+✅ Each paragraph adds something. Where a reader needs a reminder, point back to where it was said.
+
+### I-152 A rhetorical shape on repeat
+❌ "It's not X, it's Y" in every section; three adjectives, three verbs, three clauses, sentence after sentence; every paragraph built claim, example, takeaway.
+✅ Any one of these is fine. The finding is density: the same shape often enough that a reader starts to hear it.
+
+### I-153 Enthusiasm the content has not earned
+❌ "An incredibly exciting, truly transformative opportunity." "The possibilities are endless."
+✅ Let the thing described make the case. If it is impressive, the specifics show it; if they do not, the adjectives will not.
+
+### I-154 Stacked hedges
+❌ "It may potentially suggest that this could, in some cases, help."
+✅ One qualifier, where the uncertainty is real: "The evidence suggests…"
+Exception: legal, medical and scientific text, and any claim that is genuinely uncertain, may need more.
+
+### I-155 Emoji in headings
+❌ "🚀 Getting started", "✨ Key features"
+✅ The words carry the heading. An emoji is read aloud by a screen reader as its name, and at the head of every section it reads as a template.
+In markup, `A-05` already reports every emoji, a heading's included; `check` reports this rule for a Markdown page's headings, which `A-05` does not read.
+
+### I-156 Structure imposed rather than earned
+❌ Overview, Key benefits, Challenges, Best practices, Conclusion, whatever the subject. A heading every two paragraphs. Every bullet opening with a bold phrase. A numbered list for things with no order.
+✅ Let the content decide the structure: a heading where a reader would look for one, a numbered list for a sequence, bold only where a reader scanning must stop.
+
+---
+
+## Long-form
+
+**Scope:** authored writing a person puts their name to: blog posts, essays,
+case studies, release notes written as a story. Everything under *Prose* applies
+as well. Judged by a reader, never measured: rhythm and voice have no number a
+check could hold, and a score would reward prose that games it.
+
+### I-157 Nothing only the author could say
+❌ "The migration was challenging, but the team learned valuable lessons."
+✅ "The migration looked like a weekend's work. It took three weeks, because two services wrote the same table and nobody had written that down."
+A post worth reading holds something the reader could not have written themselves: a case, a number, a mistake, a decision and its reason.
+
+### I-158 No point of view
+❌ "There are several factors to consider, each with its own trade-offs."
+✅ Say which factor mattered, and why: "The technology was not the hard part. Changing how procurement worked was."
+Balance is fine when the question is open. A post that never commits to anything has not said what its author thinks.
+
+### I-159 An even rhythm
+❌ Sentence after sentence of the same length and build; paragraphs of identical size down the page.
+✅ Short sentences where something lands, longer ones where an idea needs room. Read it aloud: an even rhythm is audible long before it is visible.
+Not a length rule, and not a count: `I-79`'s limit is for interface strings.
+
+### I-160 Feeling named, not shown
+❌ "I was fascinated by the results, which provided valuable insights."
+✅ "I did not expect the result. We had tested it three times, and it failed in exactly the same place."
+Where a post reports a reaction, the specifics carry it; a named emotion with nothing behind it reads as flat.
+
+---
+
 ## L-06 · Copy checklist
 
 1. Sentence case throughout? (`I-53`)
@@ -152,3 +235,6 @@ See `P-01` for *where* the message goes and `F-37` for field-level validation te
 6. Numerals as figures, formatted consistently? (`I-83`)
 7. One word per concept across the whole product? (`I-87`)
 8. Every error saying what happened and what to do next? (`I-90`)
+9. Every figure, study, quotation and feature traceable to a source? (`I-148`)
+10. Prose saying something specific, once, without formula? (`I-149`, `I-150`, `I-151`)
+11. For long-form: something only the author could say, and a view? (`I-157`, `I-158`)

package/rules.index.json

@@ -1013,5 +1013,119 @@
     "severity": "warning",
     "since": "0.17.0",
     "pass": "screen"
+  },
+  {
+    "id": "I-148",
+    "bucket": "judgment",
+    "severity": "warning",
+    "since": "0.23.0",
+    "pass": "code"
+  },
+  {
+    "id": "I-149",
+    "bucket": "judgment",
+    "severity": "note",
+    "since": "0.23.0",
+    "pass": "code"
+  },
+  {
+    "id": "I-150",
+    "bucket": "hybrid",
+    "severity": "warning",
+    "since": "0.23.0",
+    "detector": "formula-phrase",
+    "pass": "code"
+  },
+  {
+    "id": "I-151",
+    "bucket": "judgment",
+    "severity": "note",
+    "since": "0.23.0",
+    "pass": "code"
+  },
+  {
+    "id": "I-152",
+    "bucket": "judgment",
+    "severity": "note",
+    "since": "0.23.0",
+    "pass": "code"
+  },
+  {
+    "id": "I-153",
+    "bucket": "judgment",
+    "severity": "note",
+    "since": "0.23.0",
+    "pass": "code"
+  },
+  {
+    "id": "I-154",
+    "bucket": "judgment",
+    "severity": "note",
+    "since": "0.23.0",
+    "pass": "code"
+  },
+  {
+    "id": "I-155",
+    "bucket": "mechanical",
+    "severity": "warning",
+    "since": "0.23.0",
+    "detector": "heading-emoji"
+  },
+  {
+    "id": "I-156",
+    "bucket": "judgment",
+    "severity": "note",
+    "since": "0.23.0",
+    "pass": "code"
+  },
+  {
+    "id": "I-157",
+    "bucket": "judgment",
+    "severity": "warning",
+    "since": "0.23.0",
+    "pass": "code"
+  },
+  {
+    "id": "I-158",
+    "bucket": "judgment",
+    "severity": "note",
+    "since": "0.23.0",
+    "pass": "code"
+  },
+  {
+    "id": "I-159",
+    "bucket": "judgment",
+    "severity": "note",
+    "since": "0.23.0",
+    "pass": "code"
+  },
+  {
+    "id": "I-160",
+    "bucket": "judgment",
+    "severity": "note",
+    "since": "0.23.0",
+    "pass": "code"
+  },
+  {
+    "id": "G-161",
+    "bucket": "judgment",
+    "severity": "note",
+    "since": "0.23.0",
+    "pass": "code"
+  },
+  {
+    "id": "G-162",
+    "bucket": "hybrid",
+    "severity": "warning",
+    "since": "0.23.0",
+    "detector": "layout-motion",
+    "pass": "code"
+  },
+  {
+    "id": "G-163",
+    "bucket": "judgment",
+    "severity": "note",
+    "since": "0.23.0",
+    "pass": "code"
   }
 ]

package/templates/COMMAND.md.tmpl

@@ -369,6 +369,8 @@ sizes:                     # phone first. Each size is a whole composition, not
     why: "content is capped at 1200px, so 1600 adds margin and nothing else"
 switches: none             # the recorded switches (--breakpoint-*, T-04) this page crosses, by name; none if it crosses none. Absent, the mockup draws either side of every one
 states: [default, loading, error, success]
+motion:                    # every movement the page has, or `none`: what moves, on its trigger; tells what
+  - deleted row: rows below slide into the gap, on delete; tells where the list went
 decisions: [The Engineer Reads First]     # every DECISIONS.md entry this screen implements, by name
 later: [social sign-in, remember this device]   # cut from V1, by name — the next specs start here
 indexable: true            # from the mode — editorial yes, product/operator no. Say why when you override it.
@@ -378,11 +380,19 @@ mockup: pending            # approved or skipped, quoting the user: approved by
 mockup_at:                 # where the approved drawing is: a .jig/mockups path, or a Figma or Stitch link
 deviations: []             # `make` writes here; `spec` leaves it empty
 critique: each             # optional: each, or at-ship; left out, the project's default in {{config_file}}
+# superseded_by: reference.spec.md   # only when another spec replaces this one; `ship` then leaves this page to that spec's critique
 ---
 ```
 
 - **`phone` is written first, and in full.** It is the most common screen, and the
   one a derived composition fails on worst.
+- **`motion:` lists every movement, and why it moves.** Each names what moves, its
+  trigger, and what it tells the reader. The trigger is the user's input, a state
+  change, arrival (once per visitor, editorial only, `G-42`) or ambient (editorial
+  only, `P-13`). A movement that cannot say what it tells the reader is cut here,
+  before it is built. Write it from the composition; it is not a question for the
+  owner, who reads it on the sheet beside `states:`. A page with nothing moving
+  says `none`.
 - **`indexable:`, `title:` and `description:` are copy, decided here.** The mode
   sets the default — `editorial` is first-visit content and is indexable,
   `product` and `operator` are what somebody reaches after signing in and are
@@ -521,7 +531,15 @@ not your summary of what the owner meant. It writes
   touches.
 
 Fix what it found, then have the spec checked again: the record is of the spec
-you show, and the gate compares its `spec` checksum to the file. **If you cannot
+you show, and the gate compares its `spec` checksum to the file.
+
+**A second check covers what changed, not the whole spec again.** Give the
+reader the earlier record and the spec's diff since it. A quotation or fact whose
+line did not change, and whose source has not changed since (`git diff` on that
+file), carries over as recorded; the reader checks the changed lines, the new
+ones, and any fact whose source moved. It still writes the whole record, with
+the new checksum. On jig-site each re-check opened every source again, about $10
+a round, to confirm facts on lines nobody had touched. **If you cannot
 delegate, write the record yourself, with `"reader": "the writer"` in it, and say
 in the confirmation message that nobody else checked the spec.** That is an
 honest gap the owner can close by reading more closely; a check you ran on your
@@ -536,6 +554,8 @@ Show the spec, and with it the sheet the owner checks it by, from
 - **Facts:** each claim and its source, the ones that could not be checked
   first.
 - **Copy the page will show as written.**
+- **What moves:** each line of `motion:`, with its trigger and what it tells
+  the reader, or that nothing moves.
 - **Your conditions**, beside the lines that carry them.
 - **Left for you:** the `open` items, which they can decide now.
 
@@ -896,6 +916,10 @@ indexable carries `noindex` instead, from its own metadata rather than from
 Then the ordinary rules apply: tokens by semantic name, the relevant
 `03-patterns.md` section for each component, `05-copy.md` for every string.
 
+**Build the motion `motion:` lists, and no other.** A movement the spec does not
+list is a deviation, recorded below like any other. A spec with no `motion:`
+(one confirmed before it existed) leaves motion to the `G-` rules alone.
+
 ### Record what you changed
 
 Building reveals that a spec was wrong somewhere — that is normal and expected.
@@ -1060,7 +1084,11 @@ owner ruled icon-only, a menu the owner put at every phone width. The verdict
 names that decision in `ruling`, exactly as its heading reads, and `verdicts`
 refuses a `ruled` with no ruling or with one the file does not hold. A ruled
 verdict is reported, and counted apart (`ruled=`); it is not a finding, and it
-does not go back to `make`, which could only leave it as it is. On jig-site a
+does not go back to `make`, which could only leave it as it is. **Put the field
+in each arm's brief, with its shape:** `{ "id": …, "verdict": "ruled", "ruling":
+"<the decision's heading>", "reason": … }`. On jig-site an arm wrote four ruled
+verdicts that named the decision only in `reason`, `verdicts` refused all four,
+and the parent had to write the field into a file it was not to edit. On jig-site a
 header critique counted 15 findings, five of them rulings labelled "owner-ruled"
 in prose: every count was inflated, and the real findings were harder to see.
 A rule the page breaks with no decision behind it is a `finding`, however sure
@@ -1129,11 +1157,21 @@ Each reader arm writes its own file. The arm reports back only that it wrote it.
     { "id": "P-14", "verdict": "finding", "reason": "menu button at 360 does not open; aria-expanded never set" },
     { "id": "A-60", "verdict": "n/a", "reason": "A-60 is about competing icons; this page has none" },
     { "id": "E-51", "verdict": "ruled", "ruling": "The theme toggle is icon-only", "reason": "the toggle shows only a sun or a moon; the owner ruled it icon-only" }
+  ],
+  "differences": [
+    { "what": "the checklist gives nine checks", "where": "src/pages/guide.astro:245", "against": "README.md, 'Before you confirm a spec': ten" }
   ]
 }
 ```
 
 `screen.json` carries `rendered` and `artefacts`; `code.json` needs only `verdicts`.
+**`differences` holds what no rule names:** the page against its spec (step 3),
+or against a source it quotes or teaches. Each counts as a finding. Never carry
+one as a verdict under an id you made up: `verdicts` refuses an id the corpus
+does not hold, and on jig-site both arms of one critique invented one
+(`page-vs-corpus-1`), which the parent then had to move by hand. `ruled` is for a
+rule a decision overrides; a decision in `decisions.json` is judged `ok`,
+`finding` or `n/a`, never ruled.
 
 **And the project's own decisions, one verdict each**, in
 `.jig/critique/<surface>/decisions.json`:
@@ -1280,6 +1318,26 @@ grouped with what, what stacks or moves on the phone. Not the colour, type or
 polish: the mockup is grayscale and low-fidelity on purpose, so its appearance is
 not a target.
 
+**Motion, against `motion:`.** Each movement on the page is judged against its
+line: one the spec does not list is a `G-42` finding, and one that tells the
+reader something other than its line says is a finding under the rule it
+breaks. With no `motion:` in the spec, the `G-` rules alone judge it.
+
+**Then the other way: the page against the spec.** Each section, paragraph,
+control or claim the page carries that no line of the spec asks for is a
+difference too, however accurate it is. The owner confirmed the spec, not the
+page; content the spec never held is content they never approved, and every
+later tweak and critique works from a spec that no longer says what is there.
+On jig-site a chapter carried an accurate paragraph with no spec line and no
+deviation, and two critiques in a row saw it and filed nothing, because it broke
+no rule. Report it among the findings as a difference from the spec, naming the
+content and where it is: the fix is a tweak that writes it into the spec for the
+owner to confirm, or removes it.
+
+**Say in the report what each direction found**, "none" included: a report that
+does not mention the page-against-spec pass cannot be told apart from one that
+skipped it.
+
 A difference from either is a finding **unless** `deviations:` already explains it
 — that is what the recorded deviation is for. A difference explained by neither is
 the more serious finding, because it means the spec has quietly stopped describing
@@ -1410,6 +1468,15 @@ jig-site a tweak shown a picture of a copy button wrote an exception to `E-51`
 gave, which every later critique would have judged the page by. The gate stops a
 tweak whose new `**Why:**` quotes words tweak.json does not hold.
 
+**A decision you record or amend covers the whole page, not the one place it
+was raised.** The owner rules on an instance ("keep this apostrophe curly") and
+the decision states a kind ("every apostrophe, curly"). Before you build, look
+through the page, and the chrome it shares, for every other instance of that
+kind, and bring each one in line in the same change; name them in your report.
+On jig-site a tweak recorded "every apostrophe and quotation mark curly" and
+fixed the one apostrophe the critique had named; three straight ones and a pair
+of straight quotation marks on the same page survived to the next critique.
+
 ### 2. Bring the spec in line, if it disagrees
 
 If the spec says something the change contradicts, or the page will no longer
@@ -1482,7 +1549,10 @@ is owed a critique when it has none, when its page changed after it was judged,
 when a tweak deferred its re-judge, when its verdicts are incomplete, or when a
 finding stands that the owner has not ruled on. It prints each page's state and
 a `JIG_SHIP:` line, and exits non-zero until the project is ready. A spec that
-is not confirmed yet is in progress and not held against the ship.
+is not confirmed yet is in progress and not held against the ship. Nor is a spec
+another has replaced: `superseded_by: <spec>` in its front matter leaves its page
+to that spec's critique, and `ship` checks the spec it names exists. Write that
+line, in those words, when a spec is replaced; a marker of your own is not read.
 
 ### 2. Clear what it names
 

package/templates/SKILL.md.tmpl

@@ -42,7 +42,7 @@ cite the number when you follow or deliberately break one.
    selects it and nothing else will. (`explain L-01` prints it too, but the
    file is the source — do not skip the step if the command is unavailable.)
 4. Load the relevant section of `{{rules_path}}/03-patterns.md` for the component you are building.
-5. Load `{{rules_path}}/05-copy.md` whenever you write a label, button, heading, error or empty state.
+5. Load `{{rules_path}}/05-copy.md` whenever you write a label, button, heading, error or empty state, or prose a page ships (docs, a guide, a blog post).
 6. Consume tokens by semantic name only. Never write a raw colour or pixel value
    at a call site, and never resolve a name yourself: if a token you need has no
    value, that is a finding to report, not a number to supply.