jig-ui 0.9.0 → 0.11.0

package/CHANGELOG.md

@@ -1,5 +1,100 @@
 # Changelog
 
+## 0.11.0
+
+One release, one lesson: a measurement an agent can type is not a
+measurement. Everything here came from two live runs at the capability
+floor the day 0.10.0 shipped.
+
+### Added
+
+- **`jig probe --save <surface>`.** The CLI writes the probe file now. It
+  reads what the probe returned on stdin, checks it is probe output for a
+  page inside the project, and stamps it with that page's checksum and the
+  time. A run had written its own probe file by hand — five links and an
+  Escape key that closed a menu with thirteen links and no Escape handler —
+  and its review passed on those numbers.
+- **`install --hook` / `--no-hook`.** The Stop hook is opt-in. An
+  interactive install offers it once and takes silence as no; `--yes` never
+  adds it, because that is the path an agent takes and nobody is there to
+  consent. `update` moves an existing hook and never adds one.
+
+### Changed
+
+- **Probe files are version 2.** `jig verdicts` rejects a probe with no
+  stamp — nothing measured it — and one whose page changed after it was
+  taken. Version 1 files no longer validate.
+- **README and `init` say which directory to commit, and why.** The tokens
+  live in `<css dir>/jig/`; `.jig/` holds `state.json`, specs, mockups and
+  critique verdicts. Both are warned about separately, each with what
+  ignoring it costs. Since 0.7.0 both had said `.jig/` holds the tokens.
+
+## 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` |
@@ -133,13 +149,23 @@ Set `brand` in `jig.config.json` to put it somewhere else. Projects set up
 before 0.7.0 keep their `.jig/tokens/` layout; `update` does not move them, and
 `init` offers to.
 
-The mode file is the one thing genuinely copied: a stylesheet `@import` is an
-edge in a build graph and has to resolve locally, on every machine that builds.
+The mode file is the one token file copied verbatim from the package: a
+stylesheet `@import` is an edge in a build graph and has to resolve locally, on
+every machine that builds. The brand file and the barrel are generated for your
+project, not copied.
+
+**Commit the token directory** — `<css dir>/jig/`. It holds the files your
+stylesheet `@import`s, so ignoring it means the design system does not exist for
+anyone who did not run `init` themselves: their build breaks on a missing import,
+and CI's `jig check` sees no token layer at all.
 
-**Commit `.jig/`.** It holds the token files your stylesheet imports, so a
-gitignored `.jig/` means the design system does not exist for anyone who did not
-run `init` themselves — their build breaks on a missing import, and CI's `jig
-check` sees no token layer at all. `init` warns if it finds `.jig/` ignored.
+**Commit `.jig/` too.** It is not the tokens (it was, before 0.7.0). It holds
+`state.json`, which records the version and checksum of every file `init` wrote
+and is what `update` reads to know what it may refresh, plus the durable record of
+the design loop: your specs, approved mockups and critique verdicts. Ignored, a
+teammate's `update` cannot tell a file you edited from one it wrote, and every
+spec the project agreed is invisible to the next agent. `init` warns if it finds
+either directory ignored.
 
 Add `--yes` to accept every derived default non-interactively — the mode CI and
 agents run in. It states the mode it chose and where to change it, because
@@ -150,10 +176,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 +195,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 +211,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 +272,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 +371,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 |
@@ -339,6 +380,8 @@ treatment.
 | `<css dir>/jig/brand.*.css` | Identity. One per project. |
 | `<css dir>/jig/mode.*.css` | Density, scale, rhythm, motion |
 | `<css dir>/jig/theme.css` | The barrel — brand + mode. This is what you import. |
+| `.jig/state.json` | What `init` wrote, with checksums. `update` reads it to leave your edits alone. |
+| `.jig/specs/`, `.jig/mockups/`, `.jig/critique/` | The design loop's record: what was agreed, what was drawn, what the review found. |
 
 `rules/*` and `rules.index.json` live beside your installed skill file, not
 in the project — see above.