jig-ui 0.21.0 → 0.23.0

package/CHANGELOG.md

@@ -1,5 +1,139 @@
 # 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,
+and `jig ship` is where nothing is optional.
+
+### Added
+
+- **A spec is checked before you are asked to confirm it.** `spec` checked
+  itself against the decisions, and nothing checked it against the owner's
+  words or the facts it states: on jig-site a confirmed spec carried seven
+  errors to the built page. A reader that did not write the spec now checks
+  each quotation given as the owner's and each fact at its source, and writes
+  `.jig/specs/<name>.checked.json`. The owner gets the spec with a sheet to
+  check it by, and an agent asked to confirm for them works from the same
+  sheet. The README's new "Before you confirm a spec" says what to look for.
+- **The gate holds a spec back from the owner** while it gives a quotation as
+  the owner's that the owner never said, states a fact its reader found false,
+  cites a source the project does not have, or has no check of the spec as it
+  stands.
+- **A mockup is approved against its spec, and skipping one is plain.** The
+  owner gets the drawing with a sheet, size by size, the spec's line beside what
+  the frame shows, and the README's new "Before you approve a mockup" says what
+  to look for. An approval or a skip is recorded in the owner's words
+  (`mockup: approved — "…"`), and the gate holds one they did not say. A skip
+  can be given to `make` or at the spec's confirmation, not only to `mockup`;
+  `make` then builds from the spec alone, and asks rather than finishing on a
+  spec nobody has said to draw or skip.
+
+- **A critique can wait, and `ship` is where it cannot.** `check` still runs on
+  every `make` and `tweak`; the judgment half can run after a batch of pages or
+  only before shipping, and a tweak's re-judge can wait when the owner says so
+  (or `"critique": "at-ship"` in jig.config.json says it once). The lock now
+  records the page each critique judged, so nothing that waited is forgotten.
+  `jig ship` runs `check --all --ci` and `seo` and names every confirmed page
+  that owes a critique; `/jig ship` critiques each in full and runs until it
+  says `ready=yes`. It deploys nothing, and says what Jig does not check.
+  Each page can say for itself when it is critiqued: `spec` asks, last, and writes
+  `critique: each` or `critique: at-ship`, which wins over the project's
+  default. `init` asks for that default when it sets the project up; page by
+  page, the default, writes nothing.
+
+### Fixed
+
+- **`init` merging into an edited `jig.config.json` dropped its other keys.** It
+  rebuilt the file from `brand` and `surfaces`, so an `exempt` list was lost
+  without a word. A merge now keeps every key.
+- **A `/jig` command whose words hold a `<`** read as no command at all, so
+  the gate judged a tweak as a builder editing verdicts. The session then wrote
+  `verdicts.lock` by hand; the procedure now says the lock is the gate's alone.
+
 ## 0.21.0 (2026-09-28)
 
 Dev builds, so a fix is tried on a real project before it ships, and the gate

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.
 
@@ -377,6 +377,7 @@ overwrites a config or brand file you have edited.
 | `seo [--json]` | Audits what a search engine and a link preview read, across the whole project: a route whose metadata says `noindex` sitting in the sitemap, two pages claiming one title, a sitemap that lists nothing or lists paths a crawler drops. Whether a sitemap and a robots file exist is counted, not reported: no rule asks for either, and a site with no domain yet cannot write an honest sitemap. Needs no config, no decisions and no spec. |
 | `verdicts <surface>` | Verifies a critique's verdict files and computes its counts: every rule in each pass judged once, no id that does not exist, no rule in the wrong arm, and no verdict the render probe contradicts. |
 | `probe` | Prints the render probe — one expression the critique runs in a browser at each width. It operates the menu, measures sideways scroll, and reads whether the styles and tokens applied. |
+| `ship` | Says whether the project is ready to ship, by everything Jig checks: `check --all --ci` and `seo` with no errors, and every confirmed page critiqued as it stands, with no finding you have not ruled on. Exits non-zero until it is, and names what Jig does not check. |
 | `gate` | Run by the Stop hook `install` adds for Claude Code, not by hand. Blocks an agent from finishing while `check` fails on the files it changed, or the step it just ran left its work unfinished. |
 | `explain <rule-id \| word> [--list]` | Given an id, prints a rule in full — what it forbids, what to do instead, the version it arrived in, and who checks it. Also resolves the `P-` pattern and `M-` mode specs, which no rule index contains. Given a **word**, searches every title and body and lists what matches, so you can find a rule you cannot name. `--list` prints every id, or one section's. |
 
@@ -406,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` |
@@ -417,6 +418,8 @@ on the result — the CLI reports, the agent applies the judgment half.
 | `/jig mockup` | No CLI. Low-fidelity design of that spec, reviewed before code — in HTML, Figma or Google Stitch, whichever you choose |
 | `/jig make` | No CLI. High-fidelity: builds the actual page or feature from the spec and mockup |
 | `/jig critique` | `jig verdicts` + `jig probe`. Scrutinises what was built against the rules, its spec and its mockup: two reader arms write their verdicts to files, the CLI decides whether the review is complete, and a browser probe checks the verdicts against what the page actually does |
+| `/jig tweak` | No CLI. A small change to a built page that its approved mockup does not show: decided if it is a decision, specced, built, and re-judged where it could matter |
+| `/jig ship` | `jig ship` — then critiques every page that owes one, puts the findings to you, and runs again until the project is ready |
 
 `decide` runs once. The other four run for each page, feature or functionality, one
 at a time — never the whole product at once.
@@ -445,6 +448,148 @@ convention for *skills*, not a harness with a command system of its own, so
 there is no file to write and nothing that would read one. Ask in plain language
 instead; the skill still loads.
 
+### Before you confirm a spec
+
+`spec` checks its own work before it asks you: every decision it cites exists,
+no field hands the choice to nobody ("as appropriate", "decided by the design
+system"), and nothing contradicts `DECISIONS.md`. What it cannot check is whether
+it is right about you and about the world. Your yes is what `make` builds from
+without asking again, and `critique` compares the page to the spec, never the
+spec to what is true. An error you confirm reaches the page intact.
+
+So before you are asked, a reader that did not write the spec checks it: each
+quotation it gives as yours against what you said, and each fact against the
+source it names. You get the spec with a sheet: your words and where you said
+them, each fact with its source (the ones nobody could check first), the copy
+the page will show as written, your conditions beside the lines that carry
+them, and what is left for you to decide. With the Stop hook, the spec is not
+put to you with a quotation you never said, a fact its reader found false, or a
+sheet of an earlier version of the spec.
+
+The sheet makes checking quick. It does not replace it. Read the spec for these
+before you say yes:
+
+- **Your words are yours.** Every quotation it gives as yours is something you
+  said, and nothing reads as your ruling that you did not give. What the agent
+  worked out for itself is labelled as its own.
+- **Every fact holds up at its source.** Where the spec says how something works
+  (your product, an API, an existing page, a tool you depend on), open the source
+  and check. One habit of your project stated as a general rule is a fact nobody
+  decided.
+- **Words the page will show are words you would ship.** Headings, labels and
+  any copy the spec writes out are built as written. Read them as the person
+  arriving would. A sentence about how the page works (what a control costs to
+  use, where a choice is stored) is a note for the builder, not copy.
+- **Conditions you gave are there, as you gave them.** "Three columns from 1280
+  up" is written as 1280, not moved to a width that was easier to build.
+- **V1 is small, and `later:` holds what you cut.** Nothing you set aside has
+  come back in.
+- **Every size says what you expect to see.** The phone is written in full,
+  first. Each `same-as:` gives a reason that is true, and `nav:` at every size is
+  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.
+- **A page that exists is described as built.** Its regions are the ones on the
+  page today, and anywhere it contradicts your decisions is said plainly.
+
+When something fails, say what is wrong. The spec is revised and shown to you
+again, and nothing is built until you confirm it.
+
+**Handing the check to an agent.** You can ask your agent to check a spec and
+confirm it for you. It works from the same sheet and confirms only what it
+checked itself: it opens every source marked unchecked and any it doubts, reads
+the copy as the person arriving would, and holds each condition to your words.
+What it could not check, it names to you instead of confirming. An agent's yes
+is still yours, so read what it says it did not check.
+
+### Before you approve a mockup
+
+A mockup is the confirmed spec, drawn: one page, at every size the spec names,
+in grey. So the first thing to check is that it matches the spec. The Stop hook
+already checks that every region and navigation the spec names is labelled in
+each size's frame, and holds the drawing back from you until it is. What a label
+check cannot see is whether each is drawn the way the spec says, and that is
+yours.
+
+You get the drawing with a sheet, size by size: the spec's line beside what the
+frame shows. Read it for these before you approve:
+
+- **Every size matches its line in the spec.** The order of the regions, what
+  comes first, what sits with what, where each one is. A region that is present
+  but in the wrong place is not a match.
+- **The navigation at each size is what the spec's `nav:` says.**
+- **Nothing extra.** No region the spec does not list, and nothing from
+  `later:`.
+- **The spec's states are drawn** where one changes the layout: empty, error, a
+  lot.
+- **What a drawing cannot show is named, from your spec.** If your spec says a
+  part stays in place on scroll, or opens and closes, the sheet names it so you
+  approve that too. If your spec says nothing of the kind, there is nothing to
+  name.
+- **Now that you see it, the spec is still what you want.** If it is not, the
+  spec changes first and the drawing is redrawn from it, so the two never
+  disagree.
+- **A condition you attach is written into the spec, in your words,** before
+  the approval is recorded. `make` builds from the spec, not from the
+  conversation.
+- **You are not approving colour, type or exact spacing.** Those come from the
+  tokens; a grey drawing settles none of them.
+
+Your approval is recorded as your own words, `mockup: approved — "…"`, and with
+the Stop hook it cannot be recorded in words you did not say.
+
+**Handing the check to an agent.** It renders every frame, compares each with
+its line in the spec, confirms only what it checked, and names to you what it
+could not.
+
+**Skipping the mockup.** A mockup is not required. Say so, to `mockup`, to
+`make`, or when you confirm the spec, and it is recorded as `mockup: skipped —
+"your words"`. `make` then builds from the spec alone, `critique` compares the
+page to the spec alone, and nothing waits on a drawing. What `make` will not do
+is decide for you: on a spec whose mockup nobody has approved or skipped, it asks
+which. With no drawing, the spec is all there is to build from, so the check
+before you confirm it carries all the weight.
+
+### When to critique, and shipping
+
+`check` runs on every `make` and every `tweak`. It is mechanical, it takes
+seconds, and it catches a hard-coded colour before it spreads. `critique` is the
+judgment half, and it can wait: a page judged once, as it stands, gets the
+verdicts it would have got straight after it was built. Critique a page after
+each build, after a batch of pages, or only before you ship. The one page worth
+judging early is one that sets up what later pages reuse, a header or a card: a
+finding in it found late is fixed in every page built on it.
+
+A `tweak` re-judges what its change could affect, and that can wait too when you
+say so. `init` asks when you set the project up, and writes
+`"critique": "each"` or `"critique": "at-ship"` to `jig.config.json` to say it once
+for the project (the default, page by page, writes nothing); on a project already
+set up, add the key yourself. Add `critique: each` or `critique: at-ship` in a page's spec to say it
+for that page: a header every page reuses judged each time, the chapters of a
+guide left for `ship`. `spec` asks you which, at the end of its questions, and
+says why now is worth it for a page others reuse. The spec wins where it says
+either. Neither stops you
+critiquing any page whenever you like, and `ship` judges every one.
+
+Waiting is tracked, not forgotten. The verdict lock records the page each
+critique judged, so Jig knows every page that changed since, every tweak that
+left its re-judge for later, and every page never judged. `/jig ship` is where
+none of it is optional: `jig ship` runs `check --all --ci` and `seo`, and names
+each page that owes a critique; the agent critiques each one in full, with
+readers that have not seen the conversation, and puts the findings to you. Each
+is fixed, or ruled on by you in your own words. It runs until `jig ship` says
+`ready=yes`.
+
+`ship` does not deploy anything, and it is not a security review. Jig has no
+rules for security, performance or what a real screen reader does, and its report
+says so on every run.
+
 ## What a search engine reads
 
 A page's title, description and preview text are copy, and they drift because a
@@ -604,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 |
@@ -655,7 +800,13 @@ Drop this in the project root so mode selection does not require asking on every
   // `check` names the pattern and its match count on every run, and says so
   // when one is excusing enough files to look like a mistake. Nothing is ever
   // exempt by default: this list is the only source.
-  "exempt": ["src/components/og-card.tsx", "src/cv/pdf/**"]
+  "exempt": ["src/components/og-card.tsx", "src/cv/pdf/**"],
+
+  // When pages are critiqued. Leave it out to decide each time; "at-ship"
+  // says once that critiques and a tweak's re-judge wait for `/jig ship`,
+  // which will not pass until every page is judged as it stands. A page's
+  // spec can say otherwise for itself: `critique: each` or `critique: at-ship`.
+  "critique": "at-ship"
 }
 ```