jig-ui 0.8.2 → 0.10.0

package/templates/COMMAND.md.tmpl

@@ -4,19 +4,38 @@ The user invoked `{{command_prefix}}{{args_placeholder}}`. Treat
 Available subcommands: {{subcommand_list}}. If it is empty or is not one of
 these, say so, list them, and stop.
 
-Run the matching CLI 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 `jq` drop the ones that matter.
+There are two kinds of subcommand, and they are not run the same way.
+
+**CLI-backed** — `install`, `update`, `init`, `check`, `explain`, `verdicts`, `gate`, `probe`. 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
+`jq` drop the ones that matter.
+
+**Agent procedures** — `decide`, `spec`, `mockup`, `make`, `critique`. There is no binary. Do not try to run one:
+the section below **is** the command. A CLI can check what these produce; it
+cannot do their work, because the work is judgment and authorship.
+
+`decide` runs once per project. The other four run for each page, feature or
+functionality, one at a time — never the whole product at once:
+
+```text
+decide     project-wide decisions, and the reason for each      once per project
+
+spec       what exactly is being built: its smallest useful version, at every screen size
+mockup     low-fidelity design of that spec, reviewed before any code
+make       high-fidelity: the actual page or feature, built from the spec & mockup
+critique   scrutinises what was built against the rules, its spec & mockup
+```
 
 ## init
 
 **Settle the surfaces before you run it.** Mode is the most consequential thing
-`init` writes and the thing it is worst at choosing: with `--yes` it takes
-`'/' → product` without reading the project at all, and `{{rules_path}}/01-modes.md`
-rule 1 then makes that config outrank your own reading of the project from then
-on. A default chosen in a second binds the project indefinitely, and density is
-expensive to reverse.
+`init` writes and the thing it cannot choose: with `--yes` it has nobody to ask, so
+it declares no surface mapping at all, and every mode-gated rule stays silent until
+someone does. A mode written into `{{config_file}}` then outranks your own reading
+of the project from then on (`{{rules_path}}/01-modes.md` rule 1), so it has to be
+chosen deliberately — and density is expensive to reverse.
 
 You are the half that can fix this, because you are talking to someone who knows
 the answer and the CLI is not. So, first:
@@ -36,6 +55,11 @@ the answer and the CLI is not. So, first:
 Where there is genuinely one surface, say so and move on; the point is that the
 mode was chosen rather than defaulted into.
 
+**Surfaces declared after `init` do not reach the page until `init` runs again.**
+Writing a mode into `{{config_file}}` changes what agents read; the token files the
+page imports still carry the mode `init` wrote. Run `{{scripts_path}} init` again after
+any change to `surfaces`, and `check` will say when the two disagree.
+
 Afterwards, report what it detected, the brand colour it derived and where that
 came from, and the surfaces it used — the output says whether they came from
 `jig.config.json` or from the default.
@@ -55,23 +79,56 @@ its own attestation says `judgment=not-run` to make that explicit.
 
 Do the other half yourself:
 
-1. Load `{{rules_path}}/00-anti-patterns.md` and `{{rules_path}}/05-copy.md`,
-   plus the relevant section of `{{rules_path}}/03-patterns.md` for whatever the
-   changed files build.
-2. Apply the judgment rules to the same files the CLI just scanned.
+1. Load `rules.index.json` and filter it to the entries marked `pass: code`.
+   **That list is the work.** Do not decide from the filenames which rules are
+   likely to matter and read only those — the rule you would not have thought to
+   open is the one you are about to break. Read whatever files those ids live in.
+2. Return a verdict for **every id on the list**: `ok`, `finding`, or `n/a` with
+   one line of reason. `n/a, no form on this page` is a verdict; silence is not.
+   Leave the `pass: screen` rules alone: they need the rendered composition,
+   which is not in any file you have, and guessing at them here is how this
+   command and `critique` come to give one page two verdicts.
+   `{{command_prefix}}critique` owns those.
+
+   **This is self-review, and it is the weakest arm in the system.** You built
+   these files; you know what you meant, and what you meant is invisible in the
+   artifact. It runs here because it is better than nothing and it is cheap. It
+   does not replace `{{command_prefix}}critique`, whose arm C reads the same
+   rules against the same source with an agent that has never seen this
+   conversation. When the two disagree, the one that did not build the page is
+   the one to believe.
 3. Merge both halves into **one** report keyed by rule id, ordered by severity —
    not two lists. A reader should not have to know which half found what.
-4. Run the self-check at the end of `{{rules_path}}/00-anti-patterns.md`.
+4. Run the self-check `L-04` at the end of `{{rules_path}}/00-anti-patterns.md`.
 
 Then emit the attestation with both halves filled in:
 
 ```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>
 ```
 
-Take `mechanical=` from the CLI's own line. If `check` could not run, that is
+Take `mechanical=`, `warnings=`, `files=` and `styled=` from the CLI's own line.
+`warnings=` counts the findings `check` reported as warnings. `mechanical=pass`
+means no errors, and nothing more: a page that is not usable on a phone can
+carry `pass:0` with several warnings, because the mobile detectors warn rather
+than fail CI. A record that says `pass` with warnings above zero is not a clean
+page — say what the warnings were.
+
+If `check` could not run, that is
 `mechanical=skipped:0` — never `pass`, which would report a clean result for a
-check that inspected nothing. Report `judgment=ran` only if you did step 2.
+check that inspected nothing.
+
+`judgment=`'s `<n>` is **the number of ids you returned a verdict for**, not the
+number of findings. It exists because `ran` on its own cannot be checked: an
+agent that read four rules and an agent that walked all of them both wrote
+`ran`. A number that is far below the size of the `pass: code` list is a
+sampled review, and it says so without anyone having to ask.
+
+`judgment=ran` here means the `code` rules ran. It does not mean the page was
+reviewed — nothing in this command looks at a rendered page, so a screen whose
+stylesheet never loaded passes every part of it. Say so if the user is treating
+a clean `check` as a finished review, and point them at
+`{{command_prefix}}critique`.
 
 ## install
 
@@ -79,8 +136,23 @@ Report where the skill landed and at which scope. If it warned that a global
 install already exists, do not work around it — that warning is the system
 refusing to leave two contradictory skills for one harness.
 
+**The Stop hook is the user's to accept, not yours.** In Claude Code at project
+scope, `--hook` adds an entry to `.claude/settings.json` that runs `{{scripts_path}}
+gate` when an agent tries to finish, and holds it there while the files it changed
+fail `check` or the step it just ran is unfinished. Run without the flag it is not
+added, and `--no-hook` says so outright. Do not pass `--hook` on the user's behalf:
+tell them it exists, say plainly that it can stop an agent finishing, and let them
+answer. A hook you chose for them is a change to their editor they did not make.
+
 ## explain
 
+`--layer` is the entry point for an agent that knows what it is trying to do but
+not the rule number. `explain --layer` names the six and the question each
+answers; `explain --layer layout` lists that one. The layers are a view, not a
+location — nothing was renumbered to fit one, so `P-02 Button` sits in
+`components` and `P-04 Form` in `patterns` while both keep the `P-` address they
+have always had.
+
 Print the CLI's output as it stands. It is already the rule's full text — do not
 summarise it, and do not paraphrase the correction into your own words: the
 wording is the rule.
@@ -118,3 +190,966 @@ locally and are the user's; never re-apply Jig's version over them.
 
 Everything in `{{rules_path}}/` is yours to read. Cite rules by id, and cite any
 rule you deliberately break with the reason, in one line.
+
+## spec
+
+Say exactly what is being built — a page, a feature, or a piece of
+functionality — before any of it is designed. This command writes no markup and no
+CSS.
+
+**Start with what it is for, not how it is laid out.** "A page where the user
+creates an invoice" is a spec. "A dashboard with a sidebar" is a layout with
+nothing in it yet: a sidebar, a container width and a navigation structure are
+guesses until there is something real to put in them.
+
+### Refuse rather than guess
+
+Stop and say which of these is missing, rather than proceeding:
+
+- `{{config_file}}` does not exist → run `init` first. Without it there is no
+  mode and no token layer, so there is nothing for a spec to be specific to.
+- No `DECISIONS.md` with substance → run `{{command_prefix}}decide` first. A spec
+  implements the project's decisions, and cannot check itself against ones that
+  do not exist.
+- The user named nothing → ask which page, feature or functionality.
+  `{{command_prefix}}spec` with no argument is not a request to invent one.
+
+Read `DECISIONS.md` before asking anything. Do not re-ask what it already records;
+cite it instead. If the screen touches an item in its **Unresolved** section, ask the user
+about it by name; do not settle it in the spec.
+
+### 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.
+
+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
+them per screen creates a second source of truth for the values Jig exists to
+centralise. If the user raises appearance, record it and move on.
+
+- Round 1 — what is it for? What does the user need to do there ("create an
+  invoice")? Who arrives, and what is the single most important thing they must be
+  able to see or do?
+- **Then scope it — be a pessimist.** Of everything this could include,
+  what is the smallest version that is useful on its own? Ask that plainly and
+  expect to cut. "Comments with attachments, mentions, reactions, editing,
+  threading and notifications" is a wishlist; "text and a submit button" might be
+  V1. What is cut goes in `later:`, by name — deferred on the record, not
+  forgotten. Everything after this designs V1 only.
+- Round 2 — what content and states does it carry? Empty, loading, error,
+  first-run, and the realistic range (0 items, 5, 500)?
+- Round 3 — only what is still unresolved: entry points, where it leads, what
+  must not happen here.
+
+**Ask about the phone by name.** What does the reader see first on a phone, and
+what moves, stacks, or goes behind a control? If the conversation only ever
+describes the wide screen, the phone composition will be derived from it rather
+than designed — and a derived phone composition is a squeezed desktop.
+
+### 2. Run `L-01`
+
+Read `L-01 · Layout method` in `{{rules_path}}/03-patterns.md` and run its five
+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.
+
+### 3. Write it down — one composition per screen size
+
+`.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.
+
+**Write a whole composition for every size, starting with the phone.** A spec
+with one set of regions and a note about what changes when it is narrow is one
+spec doing the work of three. It is always the wide composition that gets
+designed and the narrow one that gets derived, which is how a page arrives on a
+phone as a squeezed desktop.
+
+```yaml
+---
+feature: sign in to an existing account      # the task, not the screen
+surface: login page
+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.
+  phone:                   # judged at 360px
+    regions:               # in order, top to bottom
+      - brand: wordmark only
+      - form: the single primary task
+      - recovery: secondary, below the action
+    hierarchy: [form, brand, recovery]    # most important first
+    grouping: { form: proximity, recovery: continuity }
+    grid: { columns: 4 }
+    nav: none on this screen
+  tablet:                  # judged at 768px
+    same-as: phone
+    why: "one centred form; a second column would hold nothing"
+  desktop:                 # judged at 1280px
+    regions:
+      - brand: left column — wordmark and one line on what the product does
+      - form: right column, the single primary task
+      - recovery: below the action, in the form column
+    hierarchy: [form, brand, recovery]
+    grouping: { form: proximity, brand: common region }
+    grid: { columns: 12, form: 5, brand: 6 }
+    nav: none on this screen
+states: [default, loading, error, success]
+decisions: [The Engineer Reads First]     # every DECISIONS.md entry this screen implements, by name
+later: [social sign-in, remember this device]   # cut from V1, by name — the next specs start here
+mockup: pending            # `mockup` sets approved or skipped, from the user's own words
+mockup_at:                 # where the approved drawing is: a .jig/mockups path, or a Figma or Stitch link
+deviations: []             # `make` writes here; `spec` leaves it empty
+---
+```
+
+- **`phone` is written first, and in full.** It is the most common screen, and the
+  one a derived composition fails on worst.
+- **`tablet` and `desktop` are written in full too.** `same-as: <size>` is allowed
+  when nothing changes, but only with `why:`. It is a claim that the composition
+  holds at that width — `critique` checks it on a render — not a way to leave the
+  size out.
+- **The widths are where a composition is judged, not where breakpoints must
+  fall.** The CSS breaks wherever the content needs it, and there may be more
+  breakpoints than sizes. A navigation row, for example, breaks at the width where
+  its labels fit.
+- **No shell before there are features.** If the product has no navigation yet,
+  `nav:` says `none yet` — it is decided once there is more than one feature to
+  move between, not invented for the first one.
+- **`nav:` at every size, on any screen with navigation — decided by `P-14`'s table
+  at that width, not copied.** It is the field most likely to be written once and
+  copied, and most likely to be genuinely different at every size on a page that
+  works. Count the destinations and run the table for each size: five links fit on
+  one row at 768px and 1280px, so there the value is the links in a row, and the
+  Menu button exists only at the widths where they do not fit. In a live run all
+  four specs wrote "menu button, top right" at phone, tablet **and** desktop, citing
+  a `DECISIONS.md` entry that said only where the button sits. Every page then hid
+  five links behind a menu on a 1280px screen, and every later step faithfully
+  built and approved it.
+
+Every frontmatter field must be answerable by looking at the built page at that
+size. If a field cannot be, it is prose — put it below the frontmatter, where it
+belongs. "Feels focused" is prose. "Three regions, form first" is a field.
+
+Add fields the surface needs (`form: { steps, validation }` for a form). Do not
+add fields nothing can check.
+
+### 3b. Check it against the decisions before anyone confirms it
+
+A live run produced a spec that ranked the price above the plan limits, on a
+product whose confirmed `DECISIONS.md` said the limits are the headline and the
+price never dominates. The agent had written that decision itself, one command
+earlier. Nothing in the chain would have caught it: `critique` compares the page
+to the spec, never the spec to the decisions.
+
+- List every `DECISIONS.md` entry the screen implements in `decisions:`, by name.
+- Check **every size's** fields against each one. A field that contradicts a
+  decision is fixed now, before confirmation. It is not a deviation — deviations
+  record what building revealed, not what writing got wrong.
+- **A menu button where the links fit is refused.** Before confirmation, read `nav:`
+  at every size. If it says a menu button at a width where `P-14`'s table says the
+  destinations fit, fix it now. A decision about where the menu button sits is
+  about position, not about whether a button exists at that width — it does not
+  override `P-14`.
+- **Every reference must resolve.** A decision is cited by its name; a rule by an
+  id that `{{command_prefix}}explain` returns. Where nothing decides something,
+  write `unspecified — make chooses one it can defend, and records it`. Never write
+  a sentence that implies a rule exists when it does not. The same run wrote
+  "FAQ arranged per DECISIONS.md rules" where no such rule existed — and the next
+  agent would have gone looking for it, found nothing, and invented one.
+- **"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
+  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
+  the frontmatter, and the build that read it had nothing to build from.
+- **Before asking for confirmation, read every field back and refuse any value that
+  names nobody.** "Decided by the design system", "as appropriate", "per best
+  practice", "TBD", "standard layout" each hand the decision to no one. Replace each
+  with the looked-up composition. Only when the lookup genuinely finds nothing does
+  the field say `unspecified — make chooses one it can defend, and records it`; and
+  say in the confirmation message which fields those are, so the user can decide
+  them instead.
+
+### 4. Get it confirmed
+
+Show the spec and ask the user to confirm it. Then **stop**.
+
+`confirmed: true` records that **the user said so in their own response**. You
+may not set it on their behalf, and you may not treat your own summary,
+`{{config_file}}`, or the absence of objection as confirmation. An unconfirmed
+spec is not a weaker spec — it is not a spec, and `make` will refuse it.
+
+If the user changes something, revise and ask again. The run is incomplete until
+they confirm.
+
+## mockup
+
+**Low-fidelity design.** Draw the confirmed spec in grayscale, at every size it
+names, and get it looked at **before** any code is written. Once approved, the
+drawing is what `make` builds to and what `critique` checks against, alongside the
+spec. The spec stays the durable record, and everything the review changes goes
+back into it first, so the two never disagree.
+
+It draws **what one spec defines** — its V1 — and nothing deferred to `later:`.
+Never the whole product.
+
+### Refuse rather than guess
+
+- No `.jig/specs/<surface>.spec.md` → run `{{command_prefix}}spec` first.
+- `confirmed: false` → nobody has agreed to what you would be drawing. Ask, and stop.
+- The request is "mock up the app" or "the whole site" → say that a mockup draws
+  one specified page, feature or functionality, and offer to run `spec` for it.
+
+### 1. Ask the user how they want it drawn
+
+**Ask every time, before drawing anything.** Three ways, and the choice is the
+user's:
+
+1. **HTML** — you draw it as `.jig/mockups/<surface-slug>.html`. Needs nothing
+   connected. `.jig/` is outside what `check` scans and outside what ships, which
+   is where a working drawing belongs.
+2. **Figma** — drawn on a Figma canvas through Figma's MCP server.
+3. **Google Stitch** — generated through Stitch's MCP server.
+
+Jig ships neither tool and writes nothing for either. They are MCP servers the user
+connects to their own agent, and the user decides whether to.
+
+**If they choose Figma or Stitch, check that its server is among your tools.** If it
+is not, tell them plainly: that tool's MCP server is not connected to this agent;
+they need to connect it — Figma's through its official MCP server, Stitch's with a
+Stitch API key — and some agents only see a newly added server after a restart.
+Then **stop and wait**. When they say it is connected, check your tools again
+before drawing. Do not switch to HTML on their behalf; offer it, and let them
+choose.
+
+- **Drawing in Figma.** One page named for the feature, one frame per size at the
+  spec's widths — 360, 768, 1280 — phone first. Grey fills and strokes only; no
+  library components, styles or variables from the product's design system, for
+  the same reason the HTML carries no tokens.
+- **Drawing in Stitch.** Ask for a low-fidelity grayscale wireframe of this one
+  feature, at each size, with the spec's regions in order and its real labels.
+  Stitch leans towards finished, coloured screens: if what comes back is polished
+  — brand colour, imagery, decoration — it is not a mockup. Ask Stitch again for a
+  wireframe. If it still will not produce one, tell the user and ask whether to
+  switch to HTML. Do not review a finished-looking screen as though it were one.
+
+  **One screen per size, one request each:** `deviceType` `MOBILE` for 360, `TABLET`
+  for 768, `DESKTOP` for 1280. A live run asked once per project and got phone
+  screens only.
+
+  **A timeout is not a failure.** Generating a screen takes minutes, longer than the
+  call waits, so the call often times out while Stitch keeps working and saves the
+  screen afterwards. In a live run all three agents took the timeout as "Stitch made
+  nothing", retried — which made a duplicate — and switched tools, while their
+  screens were sitting in the project. So, when the call times out or drops:
+  1. **Do not call it again.** A second request is a second screen.
+  2. List the project's screens every 30 seconds or so, for up to 10 minutes. The
+     list of projects does not show screens; only listing one project's screens
+     does.
+  3. When the screen appears, carry on with it. If the project already holds a
+     screen for that size from an earlier attempt, use it rather than generating
+     another.
+  4. Only when 10 minutes pass with nothing, tell the user, and ask whether to try
+     again or switch to HTML or Figma. Do not switch on their behalf.
+
+  Before review, confirm there is a screen for **each** size, not only the phone.
+- **An existing design the user already has** for this feature, in either tool, can
+  stand in for drawing one. Read it through the server, and compare its structure
+  to the spec at every size. It will usually be high fidelity, so say plainly that
+  this step reviews structure only, and do not take up its colours or type as
+  decisions — those belong to the tokens and `DECISIONS.md`.
+
+The rules below apply whichever of the three it is. They are written for HTML; in
+Figma or Stitch they apply to the frames.
+
+### 2. Draw it — structure only
+
+**Low fidelity means low detail.** The purpose is to judge structure before
+appearance, and appearance wins every time it is allowed in: a reviewer shown
+finished colour and type stops evaluating the layout and starts reacting to the
+look. So the drawing contains:
+
+- **Grayscale only.** No brand colour, no accent, no status colours — unless colour
+  *is* the feature (a colour picker, a status legend), and then only there.
+- **No tokens and no project CSS.** Use the wireframe stylesheet below, pasted into
+  the file's `<style>`. The mockup must not look like the product; if it does, it
+  has become a design review.
+- **No icons, imagery, shadows or decoration.** An image is a labelled box that says
+  what goes there. An icon is its name in brackets: `[search]`.
+- **Real words, not lorem ipsum.** Labels, headings and button text are part of the
+  structure — "Create invoice" versus "Submit" is a decision worth reviewing.
+- **Every size the spec names, as its own frame** — phone, then tablet, then desktop,
+  stacked top to bottom, each drawn with its own markup. Size is structure, not
+  detail: a phone composition that is only the desktop one narrower is the failure
+  specs are written per size to prevent. A `same-as:` size is drawn anyway, so the
+  claim can be seen to hold.
+- **Navigation at every size, exactly as the spec's `nav:` says for that size.** On
+  the phone that usually means the Menu button, drawn where `DECISIONS.md` puts it —
+  and, because an open menu changes the structure, a second phone frame labelled
+  `phone — menu open` showing the links as a vertical list and the button reading as
+  close (`P-14`). A phone frame with no way to the other pages is not a simpler
+  drawing; it is a missing region. A live run approved exactly that in Figma, and the
+  build copied the gap.
+- **The primary state, plus any state that changes the structure.** An empty state
+  that replaces a table, or an error that moves a form, is drawn. The rest stay
+  listed in the spec. Do not draw what building will reveal: 2,000 contacts, a
+  thirty-character name, a slow network — unless the feature is about exactly that.
+
+```html
+<style>
+  /* Jig wireframe. Structure only: do not add colour, fonts, shadows or images. */
+  *, *::before, *::after { box-sizing: border-box; }
+  body { margin: 0; padding: 24px; font: 16px/1.5 system-ui, sans-serif; color: #222; background: #f4f4f4; }
+  .size { margin: 0 0 8px; font-size: 13px; color: #666; }
+  .frame { background: #fff; border: 1px solid #999; margin: 0 0 40px; padding: 16px; overflow: hidden; }
+  .frame[data-size="phone"] { width: 360px; }
+  .frame[data-size="tablet"] { width: 768px; }
+  .frame[data-size="desktop"] { width: 1280px; }
+  .region { border: 1px dashed #aaa; padding: 12px; margin: 0 0 12px; }
+  .region > .name { display: block; font-size: 12px; color: #777; margin: 0 0 8px; }
+  .media { background: #ddd; color: #555; display: grid; place-items: center; min-height: 120px; }
+  .field { display: block; width: 100%; min-height: 40px; border: 1px solid #888; background: #fff; }
+  button { font: inherit; padding: 8px 16px; border: 1px solid #555; background: #fff; }
+  button.primary { background: #444; color: #fff; border-color: #444; }
+  h1 { font-size: 28px; margin: 0 0 12px; }
+  h2 { font-size: 22px; margin: 0 0 8px; }
+  h3 { font-size: 18px; margin: 0 0 8px; }
+  .dims { font-variant-numeric: tabular-nums; color: #555; }
+</style>
+<script>
+  // Jig wireframe. Labels every region with its measured size, e.g.
+  // "navigation · 326 × 48". Measured from the drawing, never typed by hand.
+  function jigDims() {
+    document.querySelectorAll('.region > .name').forEach((label) => {
+      const box = label.parentElement.getBoundingClientRect();
+      let dims = label.querySelector('.dims');
+      if (!dims) { dims = document.createElement('span'); dims.className = 'dims'; label.append(dims); }
+      dims.textContent = ` · ${Math.round(box.width)} × ${Math.round(box.height)}`;
+    });
+  }
+  addEventListener('load', jigDims);
+  addEventListener('resize', jigDims);
+</script>
+```
+
+Each frame is a `<section class="frame" data-size="phone">`, preceded by a
+`<p class="size">` naming the size and its width. **Every region is labelled** —
+navigation, header, each group, the primary action — with the name the spec uses,
+in a `.name` label, so the drawing and the spec can be read against each other.
+
+**Every label carries the region's dimensions in px**, width × height at that frame's
+width: `navigation · 326 × 48`. In HTML the script above writes them; do not type
+them yourself, because a number that was not measured is a guess the reviewer will
+trust. In Figma, put the frame's own width and height in the layer's label. In
+Stitch, ask for the labels in the prompt, and where the screen does not show them,
+say so in review rather than supplying numbers.
+
+**The dimensions describe the drawing; they are not the build's values.** A
+navigation 326px wide at 360 is the phone width minus the frame's padding and border, not a width to
+hard-code — `make` still sizes with tokens and fluid widths (`D-111`). What they are
+for is review: is the header taking a sixth of the phone? Is a tap target under
+`--size-touch-target`? Is the hero pushing the plans below the first screen?
+
+### 3. Put it in front of the user
+
+**Check the drawing against the spec before anyone sees it.** For each size, go
+down the spec's `regions:` and its `nav:` and find each one in that frame. A region
+the spec names and the frame lacks is drawn now, not raised in review. This matters
+most on the phone, where a region dropped for space is easy to miss and the reviewer
+is looking at what is there, not at what is not.
+
+Tell the user where the drawing is — the file path, or the Figma or Stitch link —
+and how to open it. If the harness can render —
+a browse skill, Playwright, a headless browser — render each frame and show them the
+images; a drawing nobody looked at has not been reviewed.
+
+Then ask **structural** questions, not whether they like it: is the most important
+thing the first thing seen at each size? Does anything belong in a different group?
+Is anything here that V1 does not need?
+
+### 4. Every change goes into the spec first
+
+When the review moves, adds, cuts or regroups anything, **edit the spec**, then
+redraw from it. Never adjust the drawing alone. A mockup changed in review and not in
+the spec has quietly become the real specification, and `make` would build from a
+document that no longer describes what was approved.
+
+A request for more — "add reactions while you're at it" — goes to `later:`, unless
+the user explicitly moves it into V1. Then the spec's scope changes, and it is
+confirmed again.
+
+### 5. Record the outcome in the user's words
+
+- The user approves → set `mockup: approved` in the spec, and `confirmed: true` if
+  review changed it. 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.
+- The user says to skip it → `mockup: skipped — <their reason>`. For a change small
+  enough that drawing it costs more than building it, that is a reasonable call; it
+  is still theirs to make.
+
+Then stop. The next step is `{{command_prefix}}make`.
+
+## make
+
+**High-fidelity.** Build the actual page or feature from its confirmed spec and its
+approved mockup — the real tokens, components and copy, working.
+
+**After a critique,** `make` is how its findings get fixed: read the report, fix
+each finding, run the finish again, and then `critique` runs again. See step 5 of
+`critique`.
+
+### Refuse rather than guess
+
+- No `.jig/specs/<surface>.spec.md` → say so and run `{{command_prefix}}spec`
+  first. Do not write a quick spec of your own to satisfy the check; a spec you
+  wrote and accepted in the same breath is the thing the confirmation exists to
+  prevent.
+- `confirmed: false` → the spec exists but nobody has agreed to it. Ask for
+  confirmation and stop.
+- `mockup: pending` → the feature has not been looked at. Run
+  `{{command_prefix}}mockup`, or ask the user whether to skip it. Do not decide to
+  skip it yourself.
+
+### Build
+
+**Build from the spec and the mockup, never by copying the mockup.** The spec says
+what is being built; the approved mockup shows its structure at each size — what
+comes first, what is grouped with what, what stacks on the phone. Match that
+structure at high fidelity.
+
+What you do not do is paste the mockup's HTML into the product, or take the code a
+Figma or Stitch frame will generate for you. The drawing has fixed frame widths, grey
+boxes and no tokens; pasted in, it carries none of the rules or tokens the product is
+built on. Read it; do not copy it.
+
+If the spec and the approved mockup disagree, the spec was not updated during review.
+Stop and ask the user which is right, fix the spec, and continue — do not choose
+between them yourself.
+
+If `mockup: skipped`, build from the spec alone.
+
+Build V1 only. Nothing in `later:`, however little extra it looks.
+
+Build the **phone** composition first, then add what `tablet` and `desktop`
+change. Write base styles for the phone and add width as it is available — not
+the desktop layout with overrides that take it apart again. A layout built wide
+and subtracted from ends up correct at exactly the widths somebody checked.
+
+Then the ordinary rules apply: tokens by semantic name, the relevant
+`03-patterns.md` section for each component, `05-copy.md` for every string.
+
+### Record what you changed
+
+Building reveals that a spec was wrong somewhere — that is normal and expected.
+**Silence is the failure, not the change.** Append to `deviations:`:
+
+```yaml
+deviations:
+  - field: sizes.phone.form.steps
+    from: 1
+    to: 2
+    why: "password reset needs an email round-trip; one screen cannot hold both"
+```
+
+A spec that quietly stops describing the page is worse than no spec: a later
+review then validates the page against fiction and reports it clean.
+
+### Finish
+
+You are not done until all three of these hold. They are steps, not advice: in a
+live run one build skipped `check` and shipped 53 errors, another offered 36 as
+"non-blocking", and a third drew no phone navigation where its approved mockup had a
+menu and reported "matched exactly".
+
+**1. `check` passes.** Run `{{scripts_path}} check --all` and paste its
+`JIG_CHECK:` line into your report, as printed. `mechanical=fail:<n>` means not done:
+fix every error and run it again. No mechanical finding is non-blocking, and you do
+not get to decide one is. Warnings are listed and either fixed or explained one by
+one. A report with no `JIG_CHECK:` line, or one you typed yourself, is not a finished
+build.
+
+**2. The build matches the approved mockup at each size.** Skip only when
+`mockup: skipped`. Render the page at 360px, 768px and 1280px — with a browser, not in
+your head — and set each render beside the mockup at the same width. Go region by
+region, in the mockup's order:
+
+| Size | Mockup region | In the build? | Same place and order? |
+| --- | --- | --- | --- |
+| phone | header: name + Menu button | yes | yes |
+| phone | plan cards, stacked | yes | no — Pro first |
+
+Every **no** is either fixed now or appended to `deviations:` with a `why`. Never
+write "matches" without the table: the claim is what the table is for. A control the
+mockup draws — a Menu button, a toggle — is in the build only if it works: tap it.
+
+**3. Each size's spec fields are accounted for.** Say which fields the built page
+satisfies and which it does not — **at each size**. A page that satisfies `desktop`
+and was never looked at on a phone has satisfied a third of its spec. Then run the
+self-check at the end of `{{rules_path}}/00-anti-patterns.md`.
+
+Report the `JIG_CHECK:` line, the table, and any new deviations. Then suggest
+`{{command_prefix}}critique`.
+
+## critique
+
+Scrutinise what was built against the rules and its spec. This is **not** a second `check`, and the difference is
+not effort — it is evidence.
+
+`check` reads files. `critique` looks at the page **and** reads the source
+against the rules `check` has no detector for. A hierarchy failure is in no
+file: it is in what the files produce together, so no amount of careful reading
+finds it. That is what the render arm is for.
+
+Every judgment rule says which pass owns it, in `pass:`. The corpus divides
+three ways, and each part needs a different instrument:
+
+| | rules | instrument |
+|---|---|---|
+| mechanical, has a `detector` | a small minority | `check`, deterministic |
+| judgment, `pass: screen` | the render | arm A, looking at the page |
+| judgment, `pass: code` | **the largest group** | arm C, reading the source |
+
+The third one is the reason this command exists in its current form. `check`
+judges only what a detector can decide, which is a fraction of the corpus. Every
+other `pass: code` rule is judgment, and until something reads the source against
+it, it is enforced by nothing but the building agent having remembered it. An
+agent under load does not remember 60-odd rules; it consults the handful it
+thought to search for, and ships the rest unchecked.
+
+No two arms judge the same rule, which is why they can never hand a user
+competing verdicts on one id.
+
+### Refuse rather than guess
+
+- No `DECISIONS.md` with substance → run `{{command_prefix}}decide` first. `critique`
+  judges the page against the project's decisions as well as the rules, and has
+  nothing to judge that half against without them.
+- The user named nothing → ask which page, feature or functionality.
+- There is no `.jig/specs/<surface>.spec.md` → say so and continue **rules-only**,
+  reporting `spec=missing`. Do not invent the spec the page should have had; a
+  spec written after the page, from the page, agrees with it by construction.
+
+### 1. Three assessments that cannot see each other
+
+Run all three. **No arm may see another's output**, and none may see the
+conversation that built the page. Running them in one head anchors them to each
+other; do not shortcut it for cost, speed or context size.
+
+- **A — the reader.** Delegate to a subagent. Give it the URL or file, the spec,
+  the approved mockup (from `mockup_at:`), `DECISIONS.md`, and the corpus. It judges the `pass: screen` rules against the render, **and the `P-` patterns the spec's regions use** — a navigation region means `P-14`. Those patterns are not in `rules.index.json`, so walking the index alone never reaches them. It writes its verdicts to `.jig/critique/<surface>/screen.json` (step 1c). Do
+  **not** give it the build conversation. If it needs that conversation, it is
+  not reviewing the page, it is agreeing with itself.
+- **B — the machine.** Run `check`. Deterministic, same input same output. It
+  judges the rules that carry a `detector`, and nothing else — its own
+  attestation says `judgment=not-run`, and that is a true statement about the
+  rest of the corpus, not a formality.
+- **C — the source reader.** A second subagent, separate from A. Give it the
+  source files, the spec, and the corpus, and no render. It judges every
+  `pass: code` judgment rule — the group `check` cannot reach — and writes its
+  verdicts to `.jig/critique/<surface>/code.json` (step 1c).
+
+**If you cannot delegate an arm, it is skipped. You do not run it yourself.** No
+subagent available, a subagent that cannot read the project's files — either way
+the arm reports `skipped` with the reason, in words, in the report. A live run had
+an agent build a page and then run the reader arm on it in its own head; every
+verdict it wrote cited what the spec *intended* rather than what the page *did*,
+and its one finding asked the builder to confirm it. A skipped arm is an honest
+gap. A self-run arm is a false review that looks like a real one.
+
+Each reader is a subagent for the same reason a writer does not proofread their
+own copy. An agent that built the page knows what it meant, and what it meant is
+invisible in the artifact — which is the one thing a reviewer must not have.
+
+A and C are kept apart for a narrower reason: an arm that has seen the render
+stops reading the source and starts confirming the picture. They answer to
+different evidence and must not share it.
+
+### 1a. Arms A and C walk the index. They do not search it.
+
+**This is not a style preference. It is the difference between covering the
+corpus and sampling it.**
+
+Load `rules.index.json`, filter to the pass the arm owns, and return a verdict
+for **every id in that list**: `ok`, `finding`, or `n/a` with one line of
+reason. A rule that does not apply is still answered — `n/a, this page has no
+form` is a verdict.
+
+Searching the corpus is how a *builder* works, and it is the right method there:
+it finds the rules you can already name. It cannot find the rule for the mistake
+you do not know you are making, which is the only kind of rule worth writing
+down. A pass driven by search returns what the agent thought to look for, and
+reports nothing about everything else — indistinguishable, in the output, from a
+clean page.
+
+The builder cannot do this. It is holding a brief, a spec and a half-written
+page, and it will drop most of the corpus under that load. An arm with one job
+can walk all of it, which is the whole reason the work is split.
+
+**Never narrow the list by guessing relevance before reading.** Filter by `pass`,
+and by mode where a rule is mode-gated. Nothing else. An arm that decides in
+advance which rules are worth checking has reintroduced search with extra
+steps.
+
+### 1b. What makes a verdict real
+
+Every one of these was produced by a live run of this command, by arms that had
+been told to walk the index and believed they were doing it.
+
+**An `n/a` must name what the rule is about.** Not "does not apply" — *what* does
+not apply. `n/a, D-27 is about optical alignment and this page has no icons` is a
+verdict. `n/a, rule context unavailable` is an absence wearing a verdict's shape,
+and the difference is mechanically checkable: run
+`{{command_prefix}}explain <id>` and the rule either resolves or it does not.
+
+One run returned `C-68 — rule not found in accessible corpus` and
+`D-27 — rule context unavailable`. Both resolve instantly. A third described
+`D-25` as being about label spacing; it is about proximity hierarchy. None of
+the three had been read. `C-68` is *non-interactive elements styled like
+interactive ones* — adjacent to the only real finding that arm had raised.
+
+**An id you cannot resolve is a hard stop.** If `explain` fails on an id that is
+in the index, that is a corpus or install defect. Say so, loudly, and stop.
+Recording it as a rule that happens not to apply buries a broken install inside a
+clean-looking report.
+
+**Never treat the count as a target.** The instruction is *return a verdict for
+every id*; `<n>` is the consequence. An arm asked to reach a number will reach
+it — that is how the three fabrications above were produced, in one turn, after a
+reviewer asked for a short pass to be completed. **A pass that comes back short
+is re-run, not topped up.**
+
+**An arm that contradicts itself is re-run, not merged.** A live run's reader
+arm said, in one report, that a toggle hard-codes `60px`/`34px` instead of tokens
+(`A-07`) and that nothing on the page is hard-coded (`H-47`). Two opposite verdicts
+on the same file are not a disagreement to report; they are an instrument that
+cannot be trusted, and every other verdict it returned is suspect with them.
+
+### 1c. Verdicts go in files, and the CLI counts them
+
+Each reader arm writes its own file. The arm reports back only that it wrote it.
+
+```json
+{
+  "rendered": true,
+  "artefacts": [".jig/critique/pricing/360.png", ".jig/critique/pricing/768.png", ".jig/critique/pricing/1280.png"],
+  "verdicts": [
+    { "id": "D-115", "verdict": "ok", "reason": "no sideways scroll at 360, 768 or 1280" },
+    { "id": "P-14", "verdict": "finding", "reason": "menu button at 360 does not open; aria-expanded never set" },
+    { "id": "A-60", "verdict": "n/a", "reason": "A-60 is about competing icons; this page has none" }
+  ]
+}
+```
+
+`screen.json` carries `rendered` and `artefacts`; `code.json` needs only `verdicts`.
+
+**A rendered review is measured, not only described.** At 360, 768 and 1280px, run the
+probe in the browser and save what it returns beside the verdicts:
+
+```
+{{scripts_path}} probe > .jig/probe.js
+# at each width: set the viewport, open the page, evaluate .jig/probe.js, save the
+# JSON it returns as .jig/critique/<surface>/probe-<width>.json
+```
+
+The probe opens the phone menu, presses Escape, measures sideways scroll, and reads
+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.
+Then run:
+
+```
+{{scripts_path}} verdicts <surface>
+```
+
+**It decides whether the review is complete, not you.** It fails on an id that is not
+in the corpus, names every id in the arm's pass that has no verdict, rejects a rule
+filed by the wrong arm or judged twice, rejects an `n/a` whose reason says the rule
+was not read, requires `P-14` when the spec has navigation, and refuses
+`rendered: true` without artefacts that exist. It ends with a `JIG_VERDICTS:` line.
+
+When it fails, **re-run the arm it names**. Do not edit the file to make it pass, and
+do not report an incomplete arm as having run. A live Haiku run of this command
+before it existed produced invented rule ids, `screen=ran:1` filed as a review,
+`code=ran:97` against 67, `ran:100` against both, and arms that reported to the
+wrong agent entirely. Every one of those was forbidden here in prose. Prose did not
+hold; a check does.
+
+The merge reads the two files — not a summary an arm sent back. An arm's message can
+go astray; its file cannot.
+
+### 2. Look at the page
+
+If a browser is available this is **required**, not optional. Use whatever the
+harness provides — a browse skill, Playwright, a headless browser. Reading the
+source and imagining the page is not a render.
+
+- **Operate the page, don't only look at it.** At 360px, open the navigation
+  menu: the links must appear, `aria-expanded` must change, and the control's label
+  or icon must show that it now closes. Use the billing control, the FAQ, anything
+  that changes state, and check it changes. A menu button that renders is not a menu
+  that works: in a live run four of six pages shipped a phone menu that did not open,
+  or no menu at all, and every review that only looked passed them.
+- **Render at every size the spec names** — phone at 360px, tablet at 768px,
+  desktop at 1280px — and judge each size's fields against its own render. A
+  `same-as:` claim is checked like any other field: render that size and see
+  whether the composition really does hold.
+- At every size, measure `document.documentElement.scrollWidth` against
+  `clientWidth`. Greater means the page scrolls sideways at that width, which is a
+  finding however good the rest of it looks.
+- Compare the sizes. Did the phone change the **composition**, or only the
+  **dimensions**? Reordering, stacking, collapsing, a different control — that is
+  composition. The same layout with smaller numbers is not.
+- Check the page is styled at all. A stylesheet that 404s renders a page that
+  passes every file-based check ever written.
+- Run the squint test from `L-01` against the render, not the analogue: render
+  each size once more with `filter: grayscale(1)` on the root, and check that the
+  primary action, the headings and the groups still read in order without colour.
+  Keep the grayscale screenshots with the others; they are artefacts too. The
+  analogue exists for when there is no browser.
+
+If no browser is available, say so in one line and use `L-01`'s analogue. Never
+skip it silently, and never report a render you did not do.
+
+### 3. Compare the page to its spec and its mockup
+
+**The spec**, field by field: for each size, say whether the page rendered at that
+size satisfies each frontmatter field.
+
+**The mockup**, size by size: set each rendered size beside the approved drawing
+at the same width and compare the structure — the regions and their order, what is
+grouped with what, what stacks or moves on the phone. Not the colour, type or
+polish: the mockup is grayscale and low-fidelity on purpose, so its appearance is
+not a target.
+
+A difference from either is a finding **unless** `deviations:` already explains it
+— that is what the recorded deviation is for. A difference explained by neither is
+the more serious finding, because it means the spec has quietly stopped describing
+the page. If `mockup: skipped`, compare to the spec alone and say so.
+
+### 4. Report
+
+Merge both assessments into one report, keyed by rule id, ordered by severity.
+Say explicitly where the two agree, what only the machine found, what only the
+reader found, and which machine findings are false positives. **The disagreement
+is information, not noise to smooth over.**
+
+Say what is right as well as what is wrong — two or three things, and why they
+work. A review that only lists faults tells the reader nothing about what to
+preserve while fixing them.
+
+Then the attestation:
+
+```text
+JIG_CRITIQUE: version=<version> mode=<mode> surface=<name> spec=<confirmed|missing|unconfirmed> mockup=<approved|skipped|missing> rendered=<yes|no> screen=<ran|skipped>:<n> code=<ran|skipped>:<n> mechanical=<pass|fail|skipped>:<n> warnings=<n>
+```
+
+**Take `screen=`, `code=` and `rendered=` from `jig verdicts`, never from your own
+count.** If it reported an arm incomplete, that arm is `skipped` here with the reason,
+until it is re-run and passes.
+
+Three counts because there are three arms, and each can fail independently.
+`mechanical=` is `check`'s result and uses `check`'s own field name deliberately,
+so the two records line up. `screen=` and `code=` are the two reader arms, and
+their `<n>` is **the number of rules the arm returned a verdict for** — not the
+number of findings. An arm that walked the index reports the size of the list it
+walked; an arm reporting far fewer did not walk it, and the number is where that
+shows.
+
+`code=skipped:0` is the state this command was rebuilt to make visible. It used
+to be unsayable: the largest group of rules in the corpus went unjudged and the
+report looked complete.
+
+`rendered=no` is not a detail. Without it a clean report reads as "this page is
+good" when it can only mean "the files are good" — and a page whose stylesheet
+never loaded satisfies every file-based check there is.
+
+`rendered=yes` means **every size the spec names** was rendered. If only some
+were, the report names which, and says what was not seen.
+
+**`rendered=yes` requires an artefact.** A screenshot, a rendered dump, something
+that exists because a browser ran. Reading the source and reasoning about how it
+would look is the `L-01` analogue, and the analogue is `rendered=no`. A live run
+of this command emitted `rendered=yes` on a machine with no browser installed and
+no image written anywhere — turning an honest limitation into a false assurance,
+on the one field a reader leans on hardest. If you did not see the page, say you
+did not see the page.
+
+### 5. Then the cycle goes round again
+
+A critique with findings is not the end of the feature. It is the middle of it.
+Designing every case in advance does not work; fixing a page you can use does. So:
+
+1. Tell the user the findings, and that the next step is `{{command_prefix}}make`
+   to fix them — not the next feature.
+2. `make` fixes them, runs its finish again, and records any spec change in
+   `deviations:`.
+3. Run `{{command_prefix}}critique` again on the same surface.
+4. Repeat until the report has no errors or warnings, or the user has accepted each
+   one that is left **by id, in their own words** ("leave E-65 for now"). Your
+   judgment that a finding is minor is not acceptance.
+
+Only then suggest `{{command_prefix}}spec` for the next feature. Starting the next one
+with findings open means the second feature is built on top of the first one's
+problems, and nobody goes back for them.
+
+## probe
+
+Run `{{scripts_path}} probe`. It prints one JavaScript expression — the render probe —
+for the critique's screen arm to evaluate in a browser at each width. See step 1c of
+`critique`. It changes nothing on its own.
+
+## gate
+
+Not a command to run. In Claude Code, `install` adds a Stop hook that runs
+`{{scripts_path}} gate` whenever you try to finish. If files you changed fail `check`,
+or a critique's verdict files fail `verdicts`, it refuses to let you stop and hands
+you the failures as the reason. **Fix what it names.** Do not edit verdict files to
+satisfy it, and do not report the work as done while it is blocking. After three
+refusals in one session it lets you stop; then tell the user plainly that the work is
+not finished and what is still failing.
+
+It exists because every "run check" and "run verdicts" step in these procedures was
+skipped in a live run, and pages that did not render their styles were reported
+clean.
+
+## verdicts
+
+Run `{{scripts_path}} verdicts <surface>`, passing the argument through, and report its
+output unchanged — every `✗` line and the closing `JIG_VERDICTS:` line.
+
+It exists so that `critique`'s counts are computed rather than written. Read its
+errors as instructions to re-run the arm they name. It never fixes a verdict file,
+and neither do you: a file edited until it passes records nothing about the page.
+
+## decide
+
+Write `DECISIONS.md` beside the token layer — `jig/DECISIONS.md` by default, or
+wherever `brand` in `{{config_file}}` puts the token files.
+
+`spec`, `mockup`, `make` and `critique` are blocked until this exists: `spec` and
+`critique` refuse to start without it, and `mockup` and `make` need a confirmed spec.
+Nothing else is blocked — `install`, `init`, `check` and `explain` run without it.
+`init` comes first, because this file sits beside the token files `init` writes.
+
+### What belongs in it, and what does not
+
+The token layer already holds **values**, and `{{config_file}}` already holds
+**mode**. Neither can hold a **reason**. This file is the reasons.
+
+- ✅ *"Our accent arrives as a whole field or not at all — a full-bleed section,
+  a solid button, a filled state. Never a 2px underline, never an icon tint.
+  Its authority comes from arriving in quantity, rarely."*
+- ❌ *"The accent is `#FF6347`."* — that is a token. Restating it here creates
+  two places to change it, and they will disagree.
+- ❌ *"Use 4.5:1 contrast."* — that is `C-19`, and it is true of every project.
+  A universal rule copied into a project file is a rule that can rot locally.
+
+The test: **could this be derived from the tokens, the mode, or a numbered rule?**
+If yes, it is already written down somewhere better. If no, it is a decision, and
+this is where it lives.
+
+**`decide` is product-wide. `spec` is per screen.** Ask what holds on every
+screen. What one screen contains, who arrives at it, what its FAQ asks, where
+something sits on it — those are `spec`'s questions. Asking them here makes the
+user answer them twice, and a live run did exactly that: one agent gathered a
+page's FAQ and arrival paths under `decide`, the other under `spec`.
+
+One kind of placement **is** a decision: something that must sit in the same
+place on every screen, such as where the menu button lives. That is taste, not
+something a rule can settle, and it belongs here once. Write it as where the thing
+sits **when it appears** — "the Menu button, wherever it appears, sits top right" —
+never as "a menu button on every page". Whether a menu button exists at a width is
+`P-14`'s, decided per size in `spec`: at widths where the links fit there is none. A
+live run recorded "Menu button: top right, same on every page", and all four specs
+read it as a menu button at desktop width too. Placement on a single
+screen is not — and do not ask the owner where an element should go on a screen
+at all. If the design system has a position, it is in the rules; if it has none,
+`spec` settles it.
+
+### How to write it
+
+**Interview, do not infer.** Two or three questions per round, then wait. What
+you are looking for is the places where this project has already chosen
+something, or will have to:
+
+- Round 1 — what is this product, and who is it for in a sentence the team would
+  recognise? What should it never look like? Name real products, not adjectives.
+- Round 2 — for each thing the tokens already set, is there a rule about *how* it
+  is used? Where does the brand colour go, and where is it forbidden? What earns
+  emphasis?
+- Round 3 — what has the team already argued about, or reversed? A decision with
+  a history is the one most worth recording, because it is the one most likely to
+  be re-made wrongly.
+
+**All three rounds run.** Do not write the file after round 2 because the answers
+look complete. Round 3 asks for the one kind of decision a user does not volunteer
+unprompted — the ones with a history — and a live run skipped it for exactly that
+reason. In the arm that did ask, round 3 is where the unresolved items surfaced.
+
+**Round 3 also asks, by name, what is still undecided.** "Is there anything the team
+has not settled yet — something still argued about, or waiting on someone?" Ask it
+even when nothing so far suggests there is. Whatever the answer names goes in the
+**Unresolved** section below, not into a decision the user did not make. Four of six
+files in a live run dropped the one open item the owner had named.
+
+**Write each decision as a named rule with its reason attached**, in the project's
+own vocabulary:
+
+```markdown
+### The Stamp Rule
+
+The accent appears as a whole field or not at all. A full-bleed section, a solid
+button, a filled active state — never a 2px underline, never a small icon tint,
+never a gradient stop. Its authority comes from arriving in quantity, rarely.
+
+**Why:** thinly spread, it reads as decoration and stops meaning anything. The
+audit test: if a coloured element is smaller than a section band, it is probably
+wrong.
+```
+
+A name gives the team something to cite in review. A reason lets a future agent
+tell when the rule does not apply, which a bare instruction never can.
+
+**The reason is the owner's, or it is not written.** Write the `Why:` the user gave,
+in their words or close to them. If they gave none, ask for it. If they still give
+none, write `**Why:** not given` — never a reason you supplied. A live run invented
+reasons for two real reversals; an invented reason is worse than none, because the
+next agent weighs it as the team's and applies the rule where the team never would.
+
+**Record what is still open in its own section, at the end:**
+
+```markdown
+## Unresolved
+
+- **Annual discount on the pricing page.** Undecided between showing it on the
+  toggle and only at checkout; waiting on finance. Until settled, specs do not
+  commit to either — they ask.
+```
+
+Each item says what is undecided, between what, and what it is waiting on. This
+section is not a placeholder and does not fail the gate: an honest "not decided yet"
+is information. `spec` reads it, and asks the user instead of choosing when a screen
+touches an unresolved item. If round 3 surfaced nothing, write `None named by the
+owner.` under the heading, so a reader can tell it was asked.
+
+### Finish
+
+**Before you show it, account for every answer.** List each thing the user said,
+round by round, and the section of the file it went to — a named decision, its
+`Why:`, or **Unresolved**. An answer that went nowhere is either added or shown to
+the user as left out on purpose, with the reason. Then go the other way: every
+`Why:` in the file must trace to something the user said; delete any that does not,
+and ask. Include this mapping in your message, below the file.
+
+Show it and ask the user to confirm it is right before you stop. Leave no
+`[TODO]` markers — the gate treats them as an unwritten file, correctly, because
+a placeholder decision is not a decision.