jig-ui 0.18.10 → 0.19.0

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## 0.19.0 (2026-09-27)
+
+A new command, `tweak`, for a small change to a built page that its approved
+mockup does not show.
+
+### Added
+
+- **`/jig tweak`: a small change to a built page, in one pass.** On jig-site
+  half a day's rounds were changes the approved mockup does not show: a word
+  that wrapped, a mark's colour, how a version is written. Each went through
+  `decide`, `spec`, `make` and a full critique of every page it touched, or
+  would have been an edit by hand, which is the drift Jig exists to catch.
+  `tweak` records the decision if the change is one, brings the spec in line if
+  it disagrees, builds the change, and has a reader that did not make it
+  re-judge only the verdicts the change could affect. The gate bounds it: the
+  regions under the spec's `sizes:` must match the ones approved with the
+  mockup, the drawing must be unchanged since its approval, and the tweak may
+  change only the verdicts it names in `tweak.json`, each re-judged and stamped.
+  A change to structure is refused and routed through `spec` and `mockup`.
+- **A critique's lock records each verdict.** `verdicts.lock` now holds a digest
+  per verdict as well as the whole-file checksum, so the gate can tell which
+  verdicts a tweak changed. A lock written before this release is trusted once
+  by the first tweak and rewritten.
+
 ## 0.18.10 (2026-09-26)
 
 The rule against a stranded word holds in every browser, and the probe checks

package/README.md

@@ -250,7 +250,10 @@ Adopting Jig everywhere is not the price of using it anywhere. The rules apply
 to what you point them at:
 
 - **New work follows the loop** — decide, spec, mockup, make, critique — and the
-  Stop hook holds it to that, if you asked for the hook.
+  Stop hook holds it to that, if you asked for the hook. A small change to a
+  built page that its approved mockup does not show (a word, a colour, how text
+  wraps) goes through `tweak` instead: decided, specced, built and re-judged in
+  one pass, with the page's structure held as approved.
 - **Old pages sit where they are.** They are not rewritten, and the default
   `check` says nothing about a file nobody has touched.
 - **`jig.config.json` can exempt paths** you have no intention of revisiting, and

package/dist/index.js

@@ -46,7 +46,7 @@ import { existsSync as existsSync5, mkdirSync as mkdirSync4, readFileSync as rea
 import { join as join7 } from "path";
 
 // src/adapters/types.ts
-var COMMAND_DESCRIPTION = "Run a Jig design-system command: set the project up, plan and build one feature at a time (decide, spec, mockup, make, critique), check the UI against the rules, or refresh the install.";
+var COMMAND_DESCRIPTION = "Run a Jig design-system command: set the project up, plan and build one feature at a time (decide, spec, mockup, make, critique), make a small change to a built page (tweak), check the UI against the rules, or refresh the install.";
 var SKILL_DESCRIPTION = "Design system rules for generating and reviewing UI. Load before building any interface.";
 function assertSafeRelPath(relPath, adapterName) {
   const isAbsolute2 = relPath.startsWith("/") || /^[A-Za-z]:/.test(relPath);
@@ -6915,6 +6915,7 @@ function sizeBlock2(sizes, size) {
 }
 
 // src/commands/gate.ts
+import { execFileSync as execFileSync4 } from "child_process";
 var MAX_BLOCKS = 3;
 function lastJigCommand(transcriptPath) {
   if (!transcriptPath || !existsSync24(transcriptPath)) return void 0;
@@ -6960,7 +6961,7 @@ function asksOwner(text) {
   const prose = text.replace(/```[\s\S]*?```/g, "").replace(/`[^`\n]*`/g, "");
   return /\?(?=[\s)\]"'*_]|$)/.test(prose);
 }
-var ASKS_THE_OWNER = /* @__PURE__ */ new Set(["decide", "spec", "mockup"]);
+var ASKS_THE_OWNER = /* @__PURE__ */ new Set(["decide", "spec", "mockup", "tweak"]);
 function sessionStart(transcriptPath) {
   if (!transcriptPath || !existsSync24(transcriptPath)) return void 0;
   try {
@@ -6991,7 +6992,7 @@ function surfacesInPlay(root, command, transcriptPath) {
   const all = readdirSync15(critiqueDir, { withFileTypes: true }).filter((d) => d.isDirectory() && !d.name.startsWith("_") && !d.name.startsWith(".")).map((d) => d.name);
   const start = sessionStart(transcriptPath);
   if (start === void 0) return all;
-  const current = command === "critique" ? /^\s*surface\s*:\s*(.+)$/im.exec(newestSpec(root)?.body.split(/^---\s*$/m)[1] ?? "")?.[1]?.trim().replace(/^["']|["']$/g, "") : void 0;
+  const current = command === "critique" || command === "tweak" ? /^\s*surface\s*:\s*(.+)$/im.exec(newestSpec(root)?.body.split(/^---\s*$/m)[1] ?? "")?.[1]?.trim().replace(/^["']|["']$/g, "") : void 0;
   return all.filter((s) => s === current || verdictsMtime(join39(critiqueDir, s)) >= start - 1e3);
 }
 function commandProblems(root, command) {
@@ -7008,7 +7009,7 @@ function commandProblems(root, command) {
       if (/\[TODO\]/.test(body)) problems.push("DECISIONS.md still contains [TODO] markers.");
     }
   }
-  if (command === "spec" || command === "mockup" || command === "make" || command === "critique") {
+  if (command === "spec" || command === "mockup" || command === "make" || command === "critique" || command === "tweak") {
     if (!spec) problems.push(`${command} needs a spec: there is no file in .jig/specs/.`);
     else {
       problems.push(...specProblems(spec));
@@ -7027,6 +7028,7 @@ function commandProblems(root, command) {
     }
     if (at && /\.html?$/i.test(at) && existsSync24(join39(root, at))) problems.push(...mockupDrawingProblems(root, spec.body, at));
   }
+  if (command === "tweak" && spec) problems.push(...tweakProblems(root, spec));
   if (command === "critique") {
     const dir = join39(root, ".jig", "critique");
     const surfaces = existsSync24(dir) ? readdirSync15(dir).filter((s) => existsSync24(join39(dir, s, "screen.json")) || existsSync24(join39(dir, s, "code.json"))) : [];
@@ -7045,6 +7047,68 @@ function commandProblems(root, command) {
   }
   return problems;
 }
+function tweakProblems(root, spec) {
+  const problems = [];
+  const front = spec.body.split(/^---\s*$/m)[1] ?? "";
+  if (!/^\s*confirmed\s*:\s*true\b/im.test(front)) problems.push(`${spec.path} is not confirmed. A tweak changes a page the owner has confirmed; an unconfirmed spec goes through \`spec\`.`);
+  const mockup = /^\s*mockup\s*:\s*(\S+)/im.exec(front)?.[1] ?? "";
+  if (!/^(approved|skipped)/i.test(mockup)) problems.push(`${spec.path}: \`mockup:\` is ${mockup || "empty"}. A tweak changes a page whose drawing the owner has approved (or skipped); take a new page through \`mockup\` and \`make\`.`);
+  else problems.push(...structureSinceApproval(root, spec, front));
+  const surface = /^\s*surface\s*:\s*(.+)$/im.exec(front)?.[1]?.trim().replace(/^["']|["']$/g, "") ?? spec.slug;
+  const record = readTweak(join39(root, ".jig", "critique", surface));
+  if (!record) {
+    problems.push(`.jig/critique/${surface}/tweak.json is missing. It names the change in the owner's words (\`change\`), when it was made (\`at\`) and the rule ids and decisions re-judged for it (\`ids\`).`);
+  } else {
+    if (!record.change) problems.push(`.jig/critique/${surface}/tweak.json has no \`change\`: the owner's words for what changed.`);
+    if (!record.ids.length) problems.push(`.jig/critique/${surface}/tweak.json names nothing to re-judge. A change that no rule and no decision could see needs no tweak; name the ones it can.`);
+    const unjudged = unjudgedTweakIds(join39(root, ".jig", "critique", surface), record);
+    if (unjudged.length) {
+      problems.push(
+        `.jig/critique/${surface}: tweak.json names ${unjudged.slice(0, 6).join(", ")}${unjudged.length > 6 ? " and more" : ""} but no verdict for ${unjudged.length === 1 ? "it" : "them"} carries \`"tweak": "${record.at}"\`. Each named verdict is re-judged on the changed page by a reader that did not make the change.`
+      );
+    }
+  }
+  return problems;
+}
+function structureSinceApproval(root, spec, front) {
+  const git = (args) => execFileSync4("git", args, { cwd: root, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+  let approvedIn;
+  try {
+    approvedIn = git(["log", "-1", "--format=%H", "-G", "^mockup[[:space:]]*:", "--", spec.path]).trim();
+  } catch {
+    return [];
+  }
+  if (!approvedIn) return [];
+  const problems = [];
+  let thenBody = "";
+  try {
+    thenBody = git(["show", `${approvedIn}:./${spec.path}`]);
+  } catch {
+    return [];
+  }
+  const shape = (body) => JSON.stringify(Object.entries(specRegions(body)).sort(([a], [b]) => a.localeCompare(b)).map(([size, regions]) => [size, regions.length, regions.map((r) => r.name ?? "")]));
+  if (shape(thenBody) !== shape(spec.body)) {
+    problems.push(`${spec.path}: the regions under \`sizes:\` differ from the ones approved with the mockup (${approvedIn.slice(0, 7)}). A change to what the page holds is not a tweak: take it through \`spec\` and \`mockup\`.`);
+  }
+  const at = /^\s*mockup_at\s*:\s*(.+)$/im.exec(front)?.[1]?.trim().replace(/^["']|["']$/g, "");
+  if (at && !/^https?:/i.test(at) && existsSync24(join39(root, at))) {
+    try {
+      if (git(["show", `${approvedIn}:./${at}`]) !== readFileSync32(join39(root, at), "utf8")) {
+        problems.push(`${at} has changed since the owner approved it (${approvedIn.slice(0, 7)}). A tweak leaves the drawing as approved; a change the drawing must show goes through \`mockup\`.`);
+      }
+    } catch {
+    }
+  }
+  return problems;
+}
+function readTweak(dir) {
+  try {
+    const raw = JSON.parse(readFileSync32(join39(dir, "tweak.json"), "utf8"));
+    return { at: String(raw.at ?? ""), change: String(raw.change ?? "").trim(), ids: Array.isArray(raw.ids) ? raw.ids.map(String) : [] };
+  } catch {
+    return void 0;
+  }
+}
 function surfacePage(projectRoot, surface) {
   const spec = newestSpec(projectRoot);
   const front = spec?.body.split(/^---\s*$/m)[1] ?? "";
@@ -7135,6 +7199,28 @@ ${problems.join("\n\n")}`
 }
 var VERDICT_FILES = ["screen.json", "code.json", "decisions.json"];
 var LOCK = "verdicts.lock";
+function verdictDigests(dir) {
+  const out = {};
+  for (const f of VERDICT_FILES) {
+    let file;
+    try {
+      file = JSON.parse(readFileSync32(join39(dir, f), "utf8"));
+    } catch {
+      continue;
+    }
+    for (const v of Array.isArray(file.verdicts) ? file.verdicts : []) {
+      const key = String(v.id ?? v.decision ?? "").trim();
+      if (key) out[`${f}:${key}`] = checksum(JSON.stringify(v));
+    }
+  }
+  return out;
+}
+function writeLock(lockPath, dir, now) {
+  try {
+    writeFileSync6(lockPath, JSON.stringify({ checksum: now, verdicts: verdictDigests(dir) }) + "\n", "utf8");
+  } catch {
+  }
+}
 function verdictChecksum(dir) {
   const parts = VERDICT_FILES.map((f) => {
     try {
@@ -7157,18 +7243,22 @@ function verdictGuard(root, command, inPlay) {
     if (!now) continue;
     const lockPath = join39(dir, LOCK);
     if (command === "critique" && (!inPlay || inPlay.includes(surface))) {
-      try {
-        writeFileSync6(lockPath, JSON.stringify({ checksum: now }) + "\n", "utf8");
-      } catch {
-      }
+      writeLock(lockPath, dir, now);
       continue;
     }
-    let locked;
+    let lock = {};
     try {
-      locked = JSON.parse(readFileSync32(lockPath, "utf8")).checksum;
+      lock = JSON.parse(readFileSync32(lockPath, "utf8"));
     } catch {
       continue;
     }
+    const locked = lock.checksum;
+    if (command === "tweak" && (!inPlay || inPlay.includes(surface)) && locked !== now) {
+      const own = tweakVerdictProblems(dir, surface, lock.verdicts);
+      problems.push(...own);
+      if (own.length === 0) writeLock(lockPath, dir, now);
+      continue;
+    }
     if (locked && locked !== now) {
       problems.push(
         `.jig/critique/${surface}: the verdict files changed after \`/jig critique\` wrote them${command ? `, in a session that ran \`/jig ${command}\`` : ""}. Verdicts are the review's, not the builder's: restore them (\`git checkout -- .jig/critique/${surface}\`) and run \`/jig critique\` to judge the fix.`
@@ -7177,6 +7267,40 @@ function verdictGuard(root, command, inPlay) {
   }
   return problems;
 }
+function tweakVerdictProblems(dir, surface, lockedVerdicts) {
+  const record = readTweak(dir);
+  if (!record) {
+    return [`.jig/critique/${surface}: the verdict files changed in a \`/jig tweak\` session with no tweak.json naming what was re-judged.`];
+  }
+  const problems = [];
+  const named = new Set(record.ids.map((id) => id.toLowerCase()));
+  const nowVerdicts = verdictDigests(dir);
+  if (lockedVerdicts) {
+    const keys = /* @__PURE__ */ new Set([...Object.keys(lockedVerdicts), ...Object.keys(nowVerdicts)]);
+    const outside = [...keys].filter((k) => lockedVerdicts[k] !== nowVerdicts[k]).map((k) => k.slice(k.indexOf(":") + 1)).filter((id) => !named.has(id.toLowerCase()));
+    if (outside.length) {
+      problems.push(
+        `.jig/critique/${surface}: a tweak changed verdicts it did not name (${[...new Set(outside)].slice(0, 6).join(", ")}). A tweak re-judges only what its change could affect, listed in tweak.json's \`ids\`; restore the others (\`git checkout -- .jig/critique/${surface}\`).`
+      );
+    }
+  }
+  return problems;
+}
+function unjudgedTweakIds(dir, record) {
+  const stamped = /* @__PURE__ */ new Set();
+  for (const f of VERDICT_FILES) {
+    let file;
+    try {
+      file = JSON.parse(readFileSync32(join39(dir, f), "utf8"));
+    } catch {
+      continue;
+    }
+    for (const v of Array.isArray(file.verdicts) ? file.verdicts : []) {
+      if (record.at && v.tweak === record.at) stamped.add(String(v.id ?? v.decision ?? "").toLowerCase());
+    }
+  }
+  return record.ids.filter((id) => !stamped.has(id.toLowerCase()));
+}
 function save(file, state) {
   try {
     mkdirSync8(join39(file, ".."), { recursive: true });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jig-ui",
-  "version": "0.18.10",
+  "version": "0.19.0",
   "description": "A design system for coding agents. 143 numbered UI rules, brand x mode design tokens, and an installer for Claude Code, Codex, Cursor and opencode.",
   "license": "Apache-2.0",
   "type": "module",

package/templates/COMMAND.md.tmpl

@@ -12,7 +12,7 @@ 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:
+**Agent procedures** — `decide`, `spec`, `mockup`, `make`, `critique`, `tweak`. 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.
 
@@ -26,6 +26,9 @@ spec       what exactly is being built: its smallest useful version, at every sc
 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
+
+tweak      a small change the approved mockup does not show: decided if it is a
+           decision, specced, built, and re-judged where it could matter
 ```
 
 ## init
@@ -1166,6 +1169,85 @@ Only then suggest `{{command_prefix}}spec` for the next feature. Starting the ne
 with findings open means the second feature is built on top of the first one's
 problems, and nobody goes back for them.
 
+## tweak
+
+**A small change to a page that is built, reviewed and drawn,** one the owner's
+approved mockup does not show: a word or a sentence, a colour or its contrast, a
+weight, spacing inside a region, how text wraps, a focus ring. One pass does what
+the full loop would: record the decision if there is one, bring the spec in line,
+build it, and re-judge what the change could affect. There is no mockup step,
+because the drawing stays true, and no full critique, because nothing else moved.
+
+### Refuse rather than guess
+
+- **No confirmed spec for the page, or its `mockup:` is still pending** → this is
+  a page being made, not changed. Run `{{command_prefix}}spec`, `mockup` and
+  `make`.
+- **No critique record for the page yet** (`.jig/critique/<surface>/`) → nothing
+  has been judged, so nothing can be re-judged. Run `{{command_prefix}}critique`.
+- **The change adds, removes, reorders or regroups a region, changes the
+  navigation at any size, or would make the drawing wrong** → it is not a tweak.
+  Say so and name the route: `spec`, then `mockup`, then `make`. The gate checks
+  this whatever you decide: the regions under `sizes:` must match the ones
+  approved with the mockup, and the drawing must be untouched.
+- **It is unclear what the owner wants** → ask one question and stop.
+
+### 1. Decide, if it is a decision
+
+If the change is a ruling of the owner's, or changes one already recorded (a
+colour for a mark, how versions are written), record it in `DECISIONS.md` the way
+`decide` does: the owner's words, dated, and what it changes. If the change
+applies a rule, or answers a finding the rules already settle (a word stranded on
+its own line, `B-106`), there is nothing to decide; do not invent a decision.
+
+### 2. Bring the spec in line, if it disagrees
+
+If the spec says something the change contradicts, or the page will no longer
+look as the spec describes, amend those lines and add a dated **Tweak** entry at
+the end quoting the owner. Their instruction is the confirmation; do not ask for
+it again. Leave `sizes:` regions and the mockup as they are.
+
+### 3. Build it
+
+As `make` builds: the project's tokens and components, inside the structure the
+page already has, and only what the change needs. Run `{{scripts_path}} check`,
+then render and record the page (`{{scripts_path}} probe --run`) at every width
+it records.
+
+### 4. Re-judge what the change could affect
+
+Write `.jig/critique/<surface>/tweak.json`:
+
+```json
+{
+  "at": "2026-09-26T14:02:00Z",
+  "change": "the owner's words for the change",
+  "ids": ["A-60", "C-19", "The GitHub link is GitHub's own mark"]
+}
+```
+
+`ids` names every rule and decision the change could move: the ones that judged
+the thing that changed, not the whole index. A colour change names the contrast
+and emphasis rules and the decision it applies; a reworded label names the copy
+rules for labels and the decision about naming.
+
+Then a reader that did not make the change re-judges exactly those. It is a
+subagent, run in the foreground, given the page, the ids and each rule's text,
+and not this conversation or your reasons for the change. For each id it replaces
+that verdict in `screen.json`, `code.json` or `decisions.json` with its own
+verdict and reason, adding `"tweak": "<at>"`. It changes nothing else. Then run
+`{{scripts_path}} verdicts <surface>`.
+
+The gate holds both ends: it refuses a tweak that changed a verdict it did not
+name, and one that named a verdict it did not re-judge.
+
+### Finish
+
+Report what changed, in the owner's words; the decision and spec lines you
+touched, if any; each re-judged verdict and what it says now; and the
+`JIG_CHECK` line. A re-judged verdict that is a finding goes to the owner: it is
+fixed by another tweak, or by `make` if it needs more.
+
 ## probe
 
 Run `{{scripts_path}} probe`. It prints one JavaScript expression — the render probe —

package/templates/command-metadata.json

@@ -68,5 +68,10 @@
     "description": "Scrutinise what was built against the rules, its spec and its mockup: render it, judge what check cannot, and report by rule id. Needs DECISIONS.md. No CLI — the agent does this.",
     "argumentHint": "<page, feature or functionality, in your own words>",
     "status": "agent"
+  },
+  "tweak": {
+    "description": "A small change to a built page that its approved mockup does not show (wording, a colour, a weight, spacing inside a region, wrapping): records the decision if it is one, brings the spec in line, builds it, and re-judges only the verdicts the change could affect. Refuses a change that moves the page's structure. No CLI — the agent does this.",
+    "argumentHint": "<the change, in your own words>",
+    "status": "agent"
   }
 }