jig-ui 0.9.0 → 0.10.0

package/CHANGELOG.md

@@ -1,5 +1,71 @@
 # Changelog
 
+## 0.10.0
+
+Mobile-first, and a design loop that a weak model cannot skip. Everything here
+was measured on live runs at the capability floor (Haiku), and most of it exists
+because an instruction the agent could choose to ignore was ignored.
+
+### Added
+
+- **The loop: `decide` → `spec` → `mockup` → `make` → `critique`.** `decide`
+  runs once per project. The other four run per page, feature or functionality.
+  `mockup` is new: a low-fidelity grayscale drawing, reviewed before any code,
+  in HTML (the default), Figma or Google Stitch. Every region is labelled with
+  its measured size, and the phone frame draws the menu open as well as closed.
+- **`jig verdicts <surface>`.** A critique's reader arms write one verdict per
+  rule to `.jig/critique/<surface>/screen.json` and `code.json`; this command
+  decides whether the review is complete and computes the counts the attestation
+  reports. It refuses invented ids, a rule filed by the wrong arm, a rule judged
+  twice, an `n/a` whose reason says the rule was never read, and `rendered: true`
+  with no artefact. A screen pass with no render is `skipped`, not `ran`.
+- **`jig probe`.** One expression the critique evaluates in any browser at 360,
+  768 and 1280. It operates the phone menu (does it open, does `aria-expanded`
+  change, does the label read as close, does Escape close it), measures sideways
+  scroll, and reads whether the styles and tokens actually applied. `verdicts`
+  refuses a verdict the probe contradicts.
+- **`jig gate`, run by a Stop hook** — off unless you ask for it with
+  `install --hook`, or say yes when an interactive install offers it. It blocks
+  an agent from finishing while the files it changed fail `check`, or while the
+  `/jig` command it just ran left its work unfinished. After three attempts it
+  lets go and says the work is not done. `--yes` never adds it: that is the
+  agent's path, and nobody is there to consent. `update` moves an existing hook
+  to the new version and never adds one.
+- **Six mobile rules.** `D-111` a page that never adapts, `D-112` `100vh`,
+  `F-113` form text that zooms on iOS, `D-114` a bar under the notch,
+  `D-115` a page that scrolls sideways, `E-116` a menu that cannot be opened or
+  cannot say it is open.
+- **`H-117` a token name nothing declares.** A `var()` naming a property no file
+  declares makes its whole declaration invalid, so the page silently loses its
+  font, spacing and borders. Three of four live builds shipped exactly that,
+  and every file-based check passed them.
+- **`P-14` site navigation**, composed for the phone first: what to show at each
+  width, a named menu control whose state is visible and announced, `aria-current`
+  styled from the attribute, and no sideways-scrolling nav row.
+
+### Changed
+
+- **`spec` writes a whole composition per screen size**, phone first, with
+  `regions:` and `nav:` at each — not one composition and a note about narrow
+  screens. A menu button at a width where the links fit is refused: where the
+  button sits is the project's decision, whether it exists at that width is not.
+- **`make` finishes on three gates**: a pasted `JIG_CHECK` with no mechanical
+  errors, a region-by-region comparison with the approved mockup at each width,
+  and each size's spec fields accounted for.
+- **`critique` operates the page** instead of only looking at it, judges the
+  `P-` patterns the spec uses, and sends its findings back to `make` until the
+  page is clean or the user accepts what is left, by id.
+- **`decide` records what is still open** in an `Unresolved` section, and writes
+  only reasons the owner gave.
+- **`explain` searches every line of every rule**, and the free sections of the
+  reference, not only titles and preambles.
+- **`check` warns** when `jig.config.json` is unreadable or declares a mode the
+  token layer does not import, and counts those warnings in `JIG_CHECK`.
+- **`L-01`'s squint test runs on a grayscale render** where a browser exists;
+  reading the source is the fallback, not the equal.
+- **`init --yes` says what it did not decide** — no surface mapping, and
+  re-running `init` after you declare one.
+
 ## 0.9.0
 
 One new rule and one amended correction, both from the same afternoon of

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 105 rules, **7 can be decided by a machine** — a hard-coded colour, a
+- Of the 113 rules, **16 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 **97 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 7. Running only the agent gets you the 97 with
+Running only the CLI gets you the 16. Running only the agent gets you the 97 with
 no verification. **A clean `jig check` is not a clean review**, and the skill
 says so to every agent that reads it.
 
@@ -49,6 +49,22 @@ Paste the line for your agent and let it run the command.
 Add `--scope global` to install once for every project instead of just this one.
 Every agent supports both scopes.
 
+**Claude Code can also install a Stop hook — if you ask for it.** Add `--hook`, or
+answer yes when an interactive install offers it. It adds one entry to
+`.claude/settings.json`, keeping everything already in that file, and runs `jig gate`
+when the agent tries to finish: it holds the agent there while the files it changed
+fail `check`, or while the `/jig` command it just ran left its work incomplete — a
+spec that is prose, a critique with no verdict files, a review that never rendered
+the page. After three attempts it lets the agent stop and says the work is
+unfinished.
+
+It is off by default, and `--yes` never adds it, because that is the path an agent
+takes and nobody is there to consent. It exists because weak models skip any step
+they are merely asked to run: in live runs at the capability floor, builds shipped
+53 mechanical errors, pages rendered with no styles at all, and four reviews in a row
+wrote no verdicts. Delete the entry to remove it; `update` moves it with the version
+but never adds one.
+
 | Agent | Project scope | Global scope |
 | --- | --- | --- |
 | Claude Code | `.claude/skills/jig/SKILL.md` | `~/.claude/skills/jig/SKILL.md` |
@@ -150,10 +166,13 @@ overwrites a config or brand file you have edited.
 
 | Command | What it does |
 | --- | --- |
-| `install --agent <name> [--scope project\|global]` | Puts the skill and its rules where your agent will find them. Writes nothing else into your repo. |
+| `install --agent <name> [--scope project\|global] [--hook]` | Puts the skill and its rules where your agent will find them. Writes nothing else into your repo, unless you ask for `--hook`. |
 | `init [--yes]` | Sets the project up: CSS system, brand colour, token files, `jig.config.json`, wired imports, baseline check. The only command that writes into your repo. |
 | `check [--all] [--ci] [--json]` | Runs the rules a machine can decide. Reports findings by rule id. |
 | `update` | Refreshes an install to a newer version, leaving alone any file you have edited. |
+| `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. |
+| `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. |
 
 Flags worth knowing:
@@ -166,6 +185,7 @@ Flags worth knowing:
 | `check --json` | Machine-readable findings, for tooling or for reading every finding when the terminal output elides repeats. |
 | `init --yes` | Non-interactive; accept every derived default. |
 | `install --scope global` | Install once for every project. |
+| `install --hook` | Add the Stop hook (Claude Code, project scope). Off unless asked; `--no-hook` declines without being asked. |
 
 **Run `update` unpinned:** `npx jig-ui@latest update`. The skill pins every other
 command to the version that wrote it, so the CLI and the rules always agree;
@@ -181,11 +201,19 @@ 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 95 judgment rules and reports both halves |
+| `/jig check` | `jig check` — then applies the 97 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` |
 | `/jig update` | `jig update` |
+| `/jig decide` | No CLI. Once per project: interviews you and writes the project-wide decisions, with a reason for each |
+| `/jig spec invoice page` | No CLI. What exactly is being built — a page, feature or functionality — at its smallest useful version, at every screen size |
+| `/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 |
+
+`decide` runs once. The other four run for each page, feature or functionality, one
+at a time — never the whole product at once.
 
 Where each lands:
 
@@ -234,10 +262,13 @@ that plainly involves UI usually loads it. If it does not, say so once —
 Every finished piece of UI work ends with an attestation line:
 
 ```text
-JIG_CHECK: version=<version> mode=<mode> mechanical=<pass|fail|skipped>:<n> judgment=<ran|skipped>
+JIG_CHECK: version=<version> mode=<mode> mechanical=<pass|fail|skipped>:<n> warnings=<n> judgment=<ran|skipped>:<n> files=<n> styled=<n>
 ```
 
 `jig check` emits the same line for the half it can do, with `judgment=not-run`.
+`mechanical=pass` means no errors; `warnings=` is counted beside it, because the
+mobile detectors warn rather than fail CI and a page can carry `pass:0` while
+not working on a phone.
 If an agent reports `judgment=ran`, it ran the self-check at the end of
 `rules/00-anti-patterns.md`; if it says `skipped`, it must say why.
 
@@ -330,7 +361,7 @@ treatment.
 
 | File | Contents |
 | --- | --- |
-| `rules/00-anti-patterns.md` | 88 universal rules with corrections |
+| `rules/00-anti-patterns.md` | 96 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 |