jig-ui 0.23.0 → 0.25.0

package/examples/J-164.html

@@ -0,0 +1,7 @@
+<!-- J-164 · An indexable page a link preview cannot read -->
+<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="font-size:12px;color:#57534e;margin-bottom:6px">Sam, in a team chat:</div><div style="background:#fff;border:1px solid #d6d3d1;border-radius:8px;padding:10px;"><div style="color:#1a0dab;font-size:13px">tidewell.io/pricing</div><div style="border-left:3px solid #d6d3d1;margin-top:8px;padding-left:8px;font-size:12px;color:#4d5156">Tidewell<br>Home · Product · Docs · Pricing · Sign in</div></div><div style="font-size:11px;color:#5c5c5c;margin-top:8px">No preview tags: the card is the site's name and its navigation.</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="font-size:12px;color:#57534e;margin-bottom:6px">Sam, in a team chat:</div><div style="background:#fff;border:1px solid #d6d3d1;border-radius:8px;padding:10px;"><div style="color:#1a0dab;font-size:13px">tidewell.io/pricing</div><div style="border-left:3px solid #3f6212;margin-top:8px;padding-left:8px;font-size:12px;color:#1f1f1f"><b>Pricing · Tidewell</b><br><span style="color:#4d5156">Three plans, billed monthly or yearly. Cancel any time.</span></div></div><div style="font-size:11px;color:#5c5c5c;margin-top:8px">og:title and og:description: the card says what the page is.</div></div>
+</figure>

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "jig-ui",
-  "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.",
+  "version": "0.25.0",
+  "description": "A design system for coding agents. 160 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": {
@@ -22,7 +22,7 @@
     "CHANGELOG.md"
   ],
   "engines": {
-    "node": ">=20"
+    "node": ">=22"
   },
   "scripts": {
     "build": "tsup",
@@ -37,6 +37,7 @@
   "devDependencies": {
     "@types/node": "^22.0.0",
     "tsup": "^8.3.0",
+    "tsx": "^4.23.15",
     "typescript": "^5.6.0",
     "vitest": "^2.1.0"
   },

package/rules/00-anti-patterns.md

@@ -365,7 +365,7 @@ Without `viewport-fit=cover`, the browser keeps the page inside the safe area on
 
 ### D-115 The page scrolls sideways on a phone
 ❌ At phone width the whole page is wider than the screen — a data table, a long URL, an image, a `width: 100vw` element or a fixed-width block pushes it out, and the reader can drag the page left and right
-✅ At every width, nothing makes the page wider than the screen. Content that is genuinely wider — a data table, a code block — scrolls inside its own container with a visible edge (`E-62`), and the page itself never does. `editorial` goes further and allows no scrolling regions on mobile at all (`M-01`).
+✅ At every width, nothing makes the page wider than the screen. Content that is genuinely wider — a data table, a code block — scrolls inside its own container with a visible edge (`E-62`), and the page itself never does. `editorial` goes further and allows no scrolling regions on mobile at all (`M-01`): there a code block wraps its long lines and a wide table stacks its rows (`L-01`, step 6).
 Judge it on a render, not in the source: at 360px, `document.documentElement.scrollWidth` must not be greater than `document.documentElement.clientWidth`. The usual causes are each one line to fix — `overflow-wrap: anywhere` on text the author does not control, `max-width: 100%` on media, `width: 100%` instead of `100vw` (which includes the scrollbar), and a wrapper with `overflow-x: auto` around anything tabular.
 A page that scrolls sideways is not merely untidy. The reader's vertical swipes drift, the page slides half off the screen, and every line of text needs re-centring before it can be read.
 
@@ -376,6 +376,7 @@ Agents render the happy path. This section exists because that is the single mos
 ### E-28 Missing states
 ❌ A component with only a default appearance
 ✅ Every interactive element defines: `hover`, `focus-visible`, `active`, `disabled`. Every data view defines: loading, empty, error, and partial/truncated.
+A browser makes an `<iframe>` a tab stop whether or not anything in it can be used. One that only shows something, with nothing inside to operate or scroll, is taken out of the tab order (`tabindex="-1"`) rather than given states it has no use for; a keyboard reader otherwise meets a stop with nothing to see. One the reader uses (a player, a map, a form) keeps its stop and shows focus.
 
 ### E-29 Focus removed without replacement
 ❌ `outline: none` with nothing in its place
@@ -411,7 +412,7 @@ Where disabling is genuinely right, put a message beside it or a tooltip on it e
 ❌ A toolbar of icon-only buttons whose meaning depends on recognising the glyph
 ✅ A visible text label beside the icon, or the icon plus label on the primary path.
 This is **not** the same problem as `E-34`. An `aria-label` serves a screen reader and does nothing for a sighted user with low computer literacy, or anyone meeting an unfamiliar glyph. Both are required.
-Icon-only is acceptable for a small set of near-universal glyphs (close, search, menu) and in `operator`, where repetition builds recognition — and even there, on first-run surfaces the label stays.
+Icon-only is acceptable for a small set of near-universal glyphs and in `operator`, where repetition builds recognition — and even there, on first-run surfaces the label stays. Close, search and menu are examples, not the whole list: the test is whether most readers would name the glyph the same way without the label. A sun and moon for the theme, or a service's own widely known mark linking to it, usually pass; a funnel, a sparkle or a lightning bolt does not. An icon-only control still carries its name in text a screen reader reads (`E-34`).
 
 ### E-52 Unconventional controls
 ❌ A bespoke form field, checkbox or select that looks and behaves unlike every other one the user has met
@@ -713,6 +714,11 @@ A second copy of the positioning is a second thing to keep in step by hand, whic
 ✅ Concatenate the static routes unconditionally, and let a failed read yield the stale list rather than an empty one. When a list is genuinely empty, prove it before shipping.
 An empty sitemap is not a missing sitemap. It is a positive claim, and the crawler believes it.
 
+### J-164 An indexable page a link preview cannot read
+❌ A link pasted into a message or a post that shows a bare address, or the site's name over a line of its navigation
+✅ Every indexable page states its own preview: `og:title` and `og:description`, beside its `<title>` and meta description, and `og:type` for what it is (`article` for a post). An image and `og:url` take the page's full address: add them once the site has one, never as a relative path.
+The card is met before the page, often by someone who never opens it. Without these tags each service builds the card from whatever it finds, and they find different things. A preview is copy, like the title and description: the change that rewrites the page rewrites its card (`J-120`), and a value the page already holds is read, not typed again (`J-126`).
+
 ---
 
 ## K. Safety at the interface

package/rules/01-modes.md

@@ -85,7 +85,7 @@ Resolved values: `02-tokens.md` — the option sets for type, spacing, radius an
 - One hero maximum, at the top. A second full-viewport section is a second hero.
 - Every page states its subject above the fold in text, not only in an image.
 - Prose blocks are measure-capped even when the container is wide.
-- No horizontal scrolling regions on mobile. Reflow instead.
+- No horizontal scrolling regions on mobile. Reflow instead: a code block wraps its long lines, keeping its line breaks and indents, and a table too wide for the screen stacks its rows, each cell with its column's name (`L-01`, step 6).
 - JavaScript: **none by default.** A content page ships no script unless a feature on it needs some: a theme toggle, a search box, a filter. That is a default, not an absolute zero. Each script names, in a comment, the feature and the decision or rule that asks for it, and a review judges whether the feature needs it and whether it is as small as the feature allows, not whether it exists. What the budget forbids is script no feature asks for: a framework runtime to render static text, a library for one effect, tracking bundled into the page. **Behaviour a rule requires is not a feature and is not counted**: a few lines whose only job is something a rule asks for and the browser does not give, such as `Escape` closing a `<details>` menu, or a tap outside closing a menu in a fixed header (`P-14`), are allowed in every mode, under 1 KB, with the rule named in a comment. Nothing else rides along in them.
 
 ---
@@ -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 128 rules in it apply everywhere.
+- **The anti-pattern file.** All 129 rules in it apply everywhere.
 
 ---
 

package/rules/03-patterns.md

@@ -564,10 +564,20 @@ everything else follows from.
    fluid: they track the viewport between a floor and a ceiling with no media
    query at all. A hand-written ladder of sizes per breakpoint reintroduces the
    jumps the scale exists to remove, and goes stale the moment the scale changes.
-5. **Content that is genuinely wider scrolls inside itself.** A code block, a
-   wide table, a long identifier: its own container scrolls with a visible edge
-   (`E-62`), keeps its type size, and the page never scrolls sideways (`D-115`).
-   `editorial` allows no scrolling region on mobile at all (`M-01`).
+5. **Content that is genuinely wider scrolls inside itself, except in
+   `editorial` on a phone.** A code block, a wide table, a long identifier: its
+   own container scrolls with a visible edge (`E-62`), keeps its type size, and
+   the page never scrolls sideways (`D-115`). `editorial` allows no scrolling
+   region on mobile (`M-01`), so there each one reflows instead:
+   - **A code block** keeps its line breaks and indents and wraps a long line
+     (`white-space: pre-wrap`, `overflow-wrap: anywhere`). What is copied is
+     the source as written, not the wrapped lines.
+   - **A table too wide to fit** stacks its rows: each row a block, each cell a
+     line with its column's name in front. It stays a `<table>` with its header
+     row, so a screen reader still reads it as one. Where it fits, it stays a
+     table: the switch is the width at which its columns stop fitting.
+   - **A long identifier** (a URL, a hash, a file path) breaks where it must
+     (`overflow-wrap: anywhere`).
 6. **Each transition happens where the content needs it.** The width at which
    three columns stop fitting is a property of the columns, not of a device. Set
    it from the content, and expect the numbers to differ per component.

package/rules/05-copy.md

@@ -90,7 +90,7 @@ Whichever you choose, be consistent across sibling elements — a list where thr
 Interface text is read in fragments, at a glance, in a space someone else's content has to fit too. An em dash is a pause the reader has to interpret: it stands in for a comma, a colon, a bracket or a full stop, and which one it is only becomes clear after reading past it. The punctuation that says exactly one thing is faster.
 It is also the clearest tell of machine-written copy. Generated text reaches for the em dash far more often than a person does, and readers have learned to notice. Copy that reads as generated is copy the reader trusts less, whatever it says.
 This is about interface strings: labels, buttons, headings, errors, empty states, help text, and the prose a page ships. Markdown counts where a framework renders it as a page, which is most of them (`src/content`, `content/`, MDX routes). A repository document does not: `README.md`, `CHANGELOG.md`, `AGENTS.md` and their kin are written for whoever works on the code, and so are your commit messages and this file.
-A verbatim quotation keeps its own punctuation. Text a page quotes from another source (a document, a spec, a person), marked as a quotation with `<blockquote>` or `<q>`, is that source's words, and changing them to satisfy this rule would misquote it. The page's own copy around the quotation, and any heading or label it gives it, is still held to the rule.
+A verbatim quotation keeps its own punctuation. Text a page quotes from another source (a document, a spec, a person), marked as a quotation with `<blockquote>` or `<q>`, is that source's words, and so is a program's own output or code shown as it is, in `<pre>`, `<code>`, `<samp>` or `<kbd>`. Changing either to satisfy this rule would misquote it. The page's own copy around the quotation, and any heading or label it gives it, is still held to the rule.
 The en dash keeps its one job: ranges, where it is read as "to" (`2–10 seats`, `Mon–Fri`). That is not a pause, and it is not affected.
 
 ### I-87 Inconsistent vocabulary

package/rules.index.json

@@ -864,6 +864,13 @@
     "since": "0.14.0",
     "pass": "code"
   },
+  {
+    "id": "J-164",
+    "bucket": "mechanical",
+    "severity": "warning",
+    "since": "0.25.0",
+    "detector": "metadata"
+  },
   {
     "id": "K-128",
     "bucket": "mechanical",

package/templates/COMMAND.md.tmpl

@@ -6,7 +6,7 @@ these, say so, list them, and stop.
 
 There are two kinds of subcommand, and they are not run the same way.
 
-**CLI-backed** — `install`, `update`, `init`, `check`, `explain`, `verdicts`, `gate`, `probe`, `seo`, `ship`. Run the
+**CLI-backed** — `install`, `update`, `init`, `check`, `explain`, `verdicts`, `gate`, `probe`, `seo`, `ship`, `checksum`. Run the
 matching command with `{{scripts_path}}`, passing the flags through unchanged,
 then do the work below for that subcommand. Read the command's full output —
 findings are ordered by severity, not position, so `head`, `tail`, `grep` and
@@ -261,10 +261,12 @@ The commands after this run unchanged.
 ### 1. Ask, two or three questions at a time
 
 **This is a required interaction, not a suggestion.** Ask two or three questions,
-then **wait**. Do not send a questionnaire. Do not write the spec and present it
-for approval on your first response — a spec synthesised from a one-line prompt
-and handed over for a yes is the failure this command exists to prevent, and it
-looks exactly like the command working.
+then **wait**. Do not send a questionnaire. Do not hand the owner a finished
+spec for approval on your first response — a spec synthesised from a one-line
+prompt and handed over for a yes is the failure this command exists to prevent,
+and it looks exactly like the command working. (This is about what you ask the
+owner, not where you write: when you do write the spec, it goes in
+`.jig/specs/`, step 3.)
 
 Ask about **structure**, not appearance. Colour, type scale and density were
 settled at `init` and live in `{{config_file}}` and the token layer; re-deciding
@@ -320,13 +322,20 @@ Write the answer as `critique: each` or `critique: at-ship`.
 
 ### 2. Run `L-01`
 
-Read `L-01 · Layout method` in `{{rules_path}}/03-patterns.md` and run its five
+Read `L-01 · Layout method` in `{{rules_path}}/03-patterns.md` and run its six
 steps against the answers. The spec's structural half **is** that output — group,
-order by importance, space from the inside out, align to a grid, and state the
-hierarchy plainly enough that the squint question can be answered against it.
+order by importance, space from the inside out, align to a grid, state the
+hierarchy plainly enough that the squint question can be answered against it,
+and decide how it collapses. Step 6 is where the phone composition comes from,
+including what this mode does with a code block or table wider than the screen.
 
 ### 3. Write it down — one composition per screen size
 
+**Write it at `.jig/specs/<name>.spec.md` from the first draft**, with
+`confirmed: false`, never in a scratchpad or a temporary file. Every check the
+owner relies on reads that file, the check in 3c and the gate among them; a
+draft kept elsewhere is checked by nothing, and reaches the owner unchecked.
+
 `.jig/specs/<surface-slug>.spec.md`. Frontmatter carries what can be compared to
 a built page; prose carries the reasoning that no check can read.
 
@@ -340,6 +349,7 @@ phone as a squeezed desktop.
 ---
 feature: sign in to an existing account      # the task, not the screen
 surface: login page
+route: /login/             # optional: where the page is served, when the surface's name does not say
 mode: product              # from {{config_file}} — state it, never leave it implied
 confirmed: false           # only the user sets this to true; see below
 sizes:                     # phone first. Each size is a whole composition, not a diff.
@@ -384,6 +394,10 @@ critique: each             # optional: each, or at-ship; left out, the project's
 ---
 ```
 
+- **Only these fields.** The front matter holds the fields above and nothing
+  else; the gate refuses one it does not read, since nothing would check what it
+  says. Everything else a spec has to say (where its words come from, a round's
+  history, a note for `make`) goes in the prose below it.
 - **`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
@@ -471,7 +485,7 @@ to the spec, never the spec to the decisions.
 - **"The design system decides" is not a value.** When the user defers — "you decide",
   "whatever Jig says", "leave it to the system" — that is an instruction to look the
   answer up, not a phrase to copy into the spec. Search in this order: the `P-`
-  pattern for the component (`{{command_prefix}}explain <component>`), `L-01`'s five
+  pattern for the component (`{{command_prefix}}explain <component>`), `L-01`'s six
   steps, then the rules. Write the composition that lookup gives — "stacked, Pro
   first", "Menu button, links in a vertical list" — and cite the id it came from.
   Three of six specs in a live run wrote "arrangement decided by design system" into
@@ -489,10 +503,9 @@ to the spec, never the spec to the decisions.
 Step 3b checks the spec against the decisions. Nothing after it checks the spec
 against the owner's words or against the facts it states: `make` builds a
 confirmed spec as written, and `critique` compares the page to the spec, never
-the spec to what is true. On jig-site a confirmed spec for a docs chapter carried
-seven errors to the built page, among them a procedure Jig does not have and a
-lock written at the wrong moment, and the owner had confirmed it. The writer
-cannot catch these, for the same reason a builder cannot review its own page.
+the spec to what is true. An error a confirmed spec carries (a feature the
+product does not have, a step in the wrong order) is built into the page, and the
+owner confirmed it without knowing. The writer cannot catch these, for the same reason a builder cannot review its own page.
 
 **Delegate to a subagent.** Give it the spec, `DECISIONS.md`, the owner's messages
 from this conversation, and read access to the project. Not your reasoning, and
@@ -501,7 +514,7 @@ not your summary of what the owner meant. It writes
 
 ```json
 {
-  "spec": "sha256 of the spec file with its confirmed: line removed",
+  "spec": "`{{scripts_path}} checksum <name>` prints it: the spec with its confirmed: and mockup: lines emptied",
   "quotes": [
     { "quote": "Only where the steps differ by path", "said": "the owner, this conversation", "holds": true }
   ],
@@ -538,8 +551,8 @@ reader the earlier record and the spec's diff since it. A quotation or fact whos
 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
+the new checksum. Opening every source again on each round costs the most on
+exactly the lines nobody 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
@@ -584,9 +597,37 @@ they confirm.
 renames a region at any size, the approved drawing no longer shows the page: set
 `mockup: pending`, and `{{command_prefix}}mockup` redraws it for the owner. The gate
 checks it for a drawing in frames: while `mockup: approved`, each region the spec lists must be labelled in
-its size's frame of the drawing at `mockup_at:`. On jig-site the header spec went
-through five confirmed rounds after its drawing was approved, and still said
-`approved` over a drawing of none of them.
+its size's frame of the drawing at `mockup_at:`. Otherwise a spec can go through
+several confirmed rounds after its drawing was approved and still say `approved`
+over a drawing of none of them.
+
+### Before you stop: what the gate holds a spec to
+
+With the Stop hook, each of these keeps the session open until it is fixed. Get
+them right as you write, not after the gate names them:
+
+- **A spec writes under `.jig/` only.** A change to `DECISIONS.md`, a stylesheet or
+  a page is for `{{command_prefix}}decide`, `make` or `tweak`: record in the spec
+  what the owner said, and hand the change on.
+- **The front matter holds Jig's fields and nothing else.** Anything more goes in
+  the prose below it.
+- **Quotation marks within a few words after "owner", or after "the user said",
+  mark the owner's words.** What is inside them must be what the owner said: in
+  this conversation, in `DECISIONS.md`, or already in the spec. To name a
+  decision, a heading or a file near the word "owner", leave the quotation marks
+  off.
+- **`<name>.checked.json` is of the spec as it stands.** Its `spec` value matches
+  `{{scripts_path}} checksum <name>`, so an edit after the check means a second
+  check, of what changed.
+- **Each fact has one `source`:** a path from the project root, `path:line`, or a
+  URL, and nothing else. The file exists and the line is in it. Two places are two
+  facts; what you found at the source goes in `note`.
+- **`holds` is `true`, `false` or `"unchecked"`, with a `note` for anything but
+  `true`.** A fact found false is fixed in the spec before the owner is asked.
+- **`confirmed: true` only on the owner's yes, in this session, to the sheet you
+  showed them.** Words in the request that started the session came before the
+  sheet existed, and are not a reply to it, even when they say the owner
+  confirms. Show the sheet and stop.
 
 ## mockup
 
@@ -828,9 +869,9 @@ confirmed again.
   Record where the approved drawing is in `mockup_at:` — the file path, or the
   Figma or Stitch link. Only their own response counts; your summary of the
   drawing, or no objection, does not. **A condition they attach goes into the
-  spec first**, in their words, on the lines it governs: on jig-site the owner
-  approved with "three columns at 1280 and wider, inside the page margins", the
-  condition lived only in the conversation, and `make` moved the switch to 1290.
+  spec first**, in their words, on the lines it governs. An approval "with three
+  columns at 1280 and wider" whose condition lives only in the conversation is
+  not what `make` builds: it reads the spec, and may put the switch anywhere.
 - The user says to skip it → `mockup: skipped — "<their words>"`. For a change
   small enough that drawing it costs more than building it, that is a reasonable
   call; it is still theirs to make.
@@ -838,6 +879,22 @@ confirmed again.
 With the Stop hook, the gate reads the quotation after `approved` or `skipped` and
 holds it to what the owner said in this session.
 
+### Before you stop: what the gate holds a mockup to
+
+- **A mockup writes under `.jig/` only:** the drawing in `.jig/mockups/`, and the
+  spec's `mockup:` and `mockup_at:` lines.
+- **The drawing shows what the spec lists**, at every size, and either side of each
+  switch the page crosses. The gate checks this before you put it to the owner.
+- **`mockup:` stays `pending` until the owner answers.** Then it is `approved` or
+  `skipped`, followed by their words in quotation marks: the reply that approves
+  this drawing, or says to skip it. Words that only say they looked at it, or
+  that are about something else, are not their word on the drawing. Ask them
+  whether they approve it for `make`, and quote the answer.
+- **`mockup_at:` names the approved drawing**, a file under `.jig/mockups/` that
+  exists, or a link.
+- **An approved drawing does not change.** Changing it after approval sets
+  `mockup: pending` and puts it to the owner again.
+
 Then stop. The next step is `{{command_prefix}}make`.
 
 ## make
@@ -887,10 +944,9 @@ and `make` is where decisions are carried out, not taken. When the build shows a
 decision is wrong, missing or in conflict with the spec, stop and say so: the owner
 changes it through `{{command_prefix}}decide`, or `{{command_prefix}}tweak` for a
 small change to a built page. A note that a decision has been carried out belongs in
-the spec, under `deviations:` or its as-built notes, not in the decision. On jig-site
-one make round added a decision and another rewrote one to match the tokens it had
-just switched to; the next critique judged the page against text the build had
-written. The gate stops a `make` session that changed `DECISIONS.md`.
+the spec, under `deviations:` or its as-built notes, not in the decision. A build
+that adds a decision, or rewrites one to match what it just built, leaves the next
+critique judging the page against text the build wrote. The gate stops a `make` session that changed `DECISIONS.md`.
 
 Build V1 only. Nothing in `later:`, however little extra it looks.
 
@@ -1086,11 +1142,10 @@ 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. **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.
+"<the decision's heading>", "reason": … }`. An arm that names the decision only
+in `reason` has every ruled verdict refused by `verdicts`, and the parent is left
+to write the field into a file it is not to edit. Rulings counted as findings
+inflate every count, and the real findings are harder to see.
 A rule the page breaks with no decision behind it is a `finding`, however sure
 you are the owner would agree.
 
@@ -1168,11 +1223,17 @@ Each reader arm writes its own file. The arm reports back only that it wrote it.
 **`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
+does not hold (`page-vs-corpus-1`), and the parent is left to move it by hand. `ruled` is for a
 rule a decision overrides; a decision in `decisions.json` is judged `ok`,
 `finding` or `n/a`, never ruled.
 
+**One problem, one entry.** A difference goes under `differences` only when no
+rule and no decision holds it. A stale figure is `I-148`'s finding; a page
+paraphrasing a source the owner decided it quotes is that decision's. File it
+there and nowhere else, and let the two arms' entries agree rather than repeat.
+One stale number filed as a rule's finding, a decision's, and a difference in
+each arm is four findings for one problem, and every count built on them is wrong.
+
 **And the project's own decisions, one verdict each**, in
 `.jig/critique/<surface>/decisions.json`:
 
@@ -1227,9 +1288,13 @@ The probe opens the phone menu, presses Escape, measures sideways scroll, and re
 whether the styles and tokens actually applied. `verdicts` refuses `rendered: true`
 without a probe at each width, and refuses an `ok` the probe contradicts — a `P-14`
 "ok" on a menu that did not open, a `D-115` "ok" on a page that scrolls sideways. It
-also fails a page that renders in the browser's default font, or shows `${` to
-readers, whatever the verdicts say. Never write a probe file yourself: when it
-disagrees with you, it is the review that is wrong.
+also names what the page fails whatever the verdicts say: it renders in the
+browser's default font, shows `${` or an em dash to readers, or serves a missing
+or overlong title or description. Those are findings on the page, listed under
+`!` and counted as `measured=` on the `JIG_VERDICTS` line. Put each in the report;
+make or tweak fixes them, and the critique leaves the page as it is.
+Never write a probe file yourself: when it disagrees with you, it is the review
+that is wrong.
 Then run:
 
 ```
@@ -1328,9 +1393,8 @@ 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
+An accurate paragraph with no spec line and no deviation breaks no rule, so a
+critique that reads only the spec against the page sees it and files nothing. 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.
 
@@ -1462,10 +1526,10 @@ its own line, `B-106`), there is nothing to decide; do not invent a decision.
 
 The owner's words are the ones tweak.json records as `change`. A `**Why:**` you
 add quotes them, in quotation marks, and nothing else; what you read into them,
-or into a screenshot the owner pointed at, goes under `**Why (inferred):**`. On
-jig-site a tweak shown a picture of a copy button wrote an exception to `E-51`
-"given directly by the owner … by reference rather than words": a ruling nobody
-gave, which every later critique would have judged the page by. The gate stops a
+or into a screenshot the owner pointed at, goes under `**Why (inferred):**`. A
+tweak shown a picture that writes an exception "given directly by the owner … by
+reference rather than words" records a ruling nobody gave, and every later
+critique judges the page by it. 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
@@ -1473,9 +1537,9 @@ 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.
+A tweak that records "every apostrophe and quotation mark curly" and fixes only
+the one the critique named leaves the rest of the page's straight marks for the
+next critique to find.
 
 ### 2. Bring the spec in line, if it disagrees
 
@@ -1526,6 +1590,21 @@ judges it, and leave the verdicts alone. The page then owes a critique, and
 `{{command_prefix}}ship` will not pass until one has judged it. Never defer it
 on your own account: the gate refuses a deferral nobody gave.
 
+### Before you stop: what the gate holds a tweak to
+
+- **The spec is confirmed, and its mockup approved or skipped.** A page that has
+  neither goes through `mockup` and `make`.
+- **The page's regions and its approved drawing stay as they were.** A change to
+  what the page holds goes through `spec` and `mockup`.
+- **`tweak.json` holds `at`, `change`, `ids` and, when the owner said so,
+  `deferred`, and no other field.**
+- **`change` is the owner's words for the change, exactly as they gave them in
+  this session.** Nothing goes before or after them, not even a label such as
+  "the owner's words:". What you made of them goes in the spec's Tweak entry.
+- **`ids` names at least one rule or decision**, and each is re-judged by a reader
+  that did not make the change, unless `deferred` quotes the owner telling you to
+  leave it for later (or is `true` where the page's critique waits for ship).
+
 ### Finish
 
 Report what changed, in the owner's words; the decision and spec lines you
@@ -1547,7 +1626,9 @@ Build the project the way it ships, then run `{{scripts_path}} ship`. It runs
 `check --all --ci` and `seo`, and reads every confirmed spec's critique: a page
 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
+finding stands that the owner has not ruled on. A page that is as judged but
+whose stylesheets or scripts changed is owed only a re-probe
+(`{{scripts_path}} verdicts <page> --reprobe`), not a critique. 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. Nor is a spec
 another has replaced: `superseded_by: <spec>` in its front matter leaves its page
@@ -1617,14 +1698,15 @@ review, never by the builder editing the last one.
 When a `critique` or `tweak` session stops, the gate records its verdicts in
 `.jig/critique/<surface>/verdicts.lock`. That happens after you have committed, so
 if your verdicts are committed it stops you once more to commit the lock on its
-own; the next stop passes.
+own; the next stop passes. The same goes for a page's probe files: when the page
+changed since they were taken, the gate renders it again as you stop, and if
+your work is committed it stops you once to commit them on their own.
 
 **The lock is the gate's to write, never yours.** When the gate is wrong (it
 misreads the session, or asks for something the procedure does not), say what it
-got wrong, leave the lock as it is, and report the work as held by the gate. On
-jig-site the gate misread a tweak as no command at all, and the session computed
-the lock by hand and committed it. The lock was right that time, and a lock an
-agent can write is still a record of nothing.
+got wrong, leave the lock as it is, and report the work as held by the gate. A
+lock computed by hand may even be right, and a lock an agent can write is still a
+record of nothing.
 
 It judges the critiques this session touched: any with a file changed since the
 session began, and the current spec's surface when you ran `critique`. Another
@@ -1645,6 +1727,14 @@ It exists because every "run check" and "run verdicts" step in these procedures
 skipped in a live run, and pages that did not render their styles were reported
 clean.
 
+## checksum
+
+Run `{{scripts_path}} checksum <spec>`, passing the argument through, and report the
+value it prints. It is the `spec` field of `.jig/specs/<name>.checked.json`: the
+spec's checksum with its `confirmed:` and `mockup:` lines emptied, which the owner's
+answer sets after the check. Never compute it yourself: a hand-computed value is
+easily wrong, and a wrong one reads as a spec that changed after its check.
+
 ## verdicts
 
 Run `{{scripts_path}} verdicts <surface>`, passing the argument through, and report its
@@ -1852,9 +1942,9 @@ weighs it as the team's and applies the rule where the team never would.
 
 What you add to explain a reason, work out from it, or carry over from what the
 owner said elsewhere goes in its own paragraph, `**Why (inferred):**`, which says it
-is yours. On jig-site, reasons read "given directly by the owner", followed by
-sentences the agent had written; a later agent could not tell which half to weigh
-as the team's. The gate checks each decision this session wrote or changed: its
+is yours. A reason that reads "given directly by the owner" and goes on in the
+agent's own sentences leaves a later agent unable to tell which half to weigh as
+the team's. The gate checks each decision this session wrote or changed: its
 `Why` is quoted, `not given`, or labelled inferred.
 
 **Record what is still open in its own section, at the end:**

package/templates/SKILL.md.tmpl

@@ -36,8 +36,20 @@ cite the number when you follow or deliberately break one.
    `.jig/specs/<name>.checked.json` (its step 4), `{{command_prefix}}mockup`'s
    size by size against the spec (its step 3, rendering every frame). Confirm
    only what you checked yourself, and name to the owner what you could not.
+   **Recording the owner's word?** A spec confirmed, a drawing approved or
+   skipped, a re-judge left for later, a tweak's change, a decision's reason:
+   each is the owner's words, quoted as they said them, and words that say that
+   thing. A remark about the layout is not a skip of the mockup; a yes to one
+   question is not a yes to the spec. When they have not said it, ask. What you
+   read into their words goes under a label that says it is yours
+   (`**Why (inferred):**`), never inside their quotation marks.
+   **Recording something Jig has no field for?** Write it in prose, below a
+   spec's front matter or in the report. Never invent a front-matter key, a
+   verdict id or a JSON field for it: nothing reads an invented one, so what it
+   says is lost to every check. If it keeps recurring, tell the owner, since
+   Jig may be missing a field.
    **Building a screen rather than a single component?** Read `L-01 · Layout
-   method` in `{{rules_path}}/03-patterns.md` and run its five steps before
+   method` in `{{rules_path}}/03-patterns.md` and run its six steps before
    writing any markup. It is a procedure, not a component, so step 4 never
    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.)

package/templates/command-metadata.json

@@ -34,6 +34,11 @@
     "argumentHint": "",
     "status": "available"
   },
+  "checksum": {
+    "description": "Print a spec's checksum: the value its `.checked.json` records as `spec`, so a spec's reader never computes it by hand.",
+    "argumentHint": "<spec>",
+    "status": "available"
+  },
   "verdicts": {
     "description": "Verify a critique's verdict files: every rule in each pass judged once, no id that does not exist, no rule in the wrong arm, rendered only with a screenshot. Computes the counts the critique reports, so the agent never writes them.",
     "argumentHint": "<surface>",