jig-ui 0.14.1 → 0.15.0

package/CHANGELOG.md

@@ -1,5 +1,47 @@
 # Changelog
 
+## 0.15.0
+
+The gate holds an agent on warnings, waits while it asks the owner a question,
+and reaches projects where the skill is installed globally.
+
+### Changed
+
+- **`gate` blocks on warnings in the files the agent changed**, not only on
+  mechanical errors. One em dash survived two runs of fresh agents on a real
+  site: the first saw the warning, called it pre-existing, and finished. The
+  gate still reads only changed files, so old warnings elsewhere never trap an
+  agent, and it now also runs when a changed file carries interface text.
+- **The skill asks the user to run each command.** `decide`, `spec`, `mockup`,
+  `make` and `critique` hold their procedures in the command, not in the
+  skill. An agent told in prose to "run decide" made up five questions of its
+  own and wrote a `DECISIONS.md` with no direction and no `## Unresolved`
+  section.
+
+### Added
+
+- **`jig-allow <ID>: <why>`** waives one warning, on its own line or the line
+  above, in any comment syntax. Some warnings are a detector's guess: `A-01`
+  cannot tell a chosen violet from a default one. Warnings only, a reason is
+  required, and `check` lists every waiver it honoured, with its reason, on
+  every run. Waived findings are left out of `warnings=`.
+- **`install --agent claude --hook` on a global install** writes only this
+  project's Stop hook. The hook was written only by a project install, which is
+  refused while the skill is global, so most projects never had a gate.
+
+### Fixed
+
+- **A question to the owner is not a finish.** After `decide`, `spec` or
+  `mockup`, a stop whose last message asks a question is allowed, and the
+  command's output is checked on the stop after the answer. Before, the gate
+  refused `decide`'s first question because `DECISIONS.md` did not exist yet,
+  and on the second refusal the agent wrote the file itself with no answers.
+- **The gate finds `DECISIONS.md` beside the token layer** that `brand` in
+  `jig.config.json` names. It looked in three fixed places, rejected a
+  correctly placed file, and the agent moved the file to satisfy it.
+- **`jig seo` says an endpoint is not a page**, so `pages=` can be checked
+  against a site's route files.
+
 ## 0.14.1
 
 `jig seo` cites only what a rule says.

package/README.md

@@ -53,10 +53,19 @@ Every agent supports both scopes.
 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.
+have a `check` error or warning, 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.
+
+A warning that is right as it stands is waived on its own line, in a comment
+reading `jig-allow <ID>: <why>` (`/* jig-allow A-01: the brand is violet */`). The
+reason is required, an error cannot be waived, and `check` lists every waiver it
+honoured, with its reason, on every run.
+
+The skill and the hook are installed separately. With Jig installed globally, run
+`install --agent claude --hook` in a project to add only that project's hook: a
+global hook would run on every stop in every project on the machine.
 
 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

package/dist/index.js

@@ -2,9 +2,9 @@
 
 // src/index.ts
 import { Command } from "commander";
-import { readFileSync as readFileSync30 } from "fs";
+import { readFileSync as readFileSync31 } from "fs";
 import { homedir as homedir2 } from "os";
-import { join as join37 } from "path";
+import { join as join38 } from "path";
 
 // src/paths.ts
 import { existsSync } from "fs";
@@ -568,11 +568,19 @@ function install(opts) {
     } catch {
       globalManifest = null;
     }
+    if (globalManifest && opts.hook && opts.agent === "claude") {
+      return {
+        written: [],
+        skipped: [],
+        stopHook: installStopHook(opts.projectRoot, opts.version),
+        hookOnly: `Jig's skill is installed globally for 'claude' (${globalReferenceDir} under your home directory), so it stays there. Added only this project's Stop hook.`
+      };
+    }
     if (globalManifest) {
       return {
         written: [],
         skipped: [],
-        warning: `Jig is already installed globally for '${opts.agent}' (${globalReferenceDir} under your home directory). Installing again at project scope would leave two contradicting '${opts.agent}' skills. Run 'jig update' to refresh the global install instead, or choose a different --agent for this project.`
+        warning: `Jig is already installed globally for '${opts.agent}' (${globalReferenceDir} under your home directory). Installing again at project scope would leave two contradicting '${opts.agent}' skills. Run 'jig update' to refresh the global install instead, or choose a different --agent for this project.` + (opts.agent === "claude" ? ` To add only this project's Stop hook, run install again with --hook.` : "")
       };
     }
   }
@@ -1455,8 +1463,8 @@ function sectionsOf(entries) {
 }
 
 // src/commands/check.ts
-import { existsSync as existsSync14, readFileSync as readFileSync18 } from "fs";
-import { join as join23 } from "path";
+import { existsSync as existsSync14, readFileSync as readFileSync19 } from "fs";
+import { join as join24 } from "path";
 
 // src/check/files.ts
 import { execFileSync } from "child_process";
@@ -1689,6 +1697,11 @@ function formatReport(findings, meta) {
       lines.push(`    ${meta.exempt.slice(0, 8).join(", ")}${n > 8 ? `, and ${n - 8} more` : ""}`);
     }
   }
+  if (meta.waived && meta.waived.length > 0) {
+    lines.push("");
+    lines.push(`  ${plural(meta.waived.length, "warning")} waived in the source with jig-allow:`);
+    for (const w of meta.waived) lines.push(`    ${w.ruleId.padEnd(6)}${w.file}:${w.line}  "${w.reason}"`);
+  }
   if (meta.unscanned && meta.unscanned.count > 0) {
     const exts = meta.unscanned.extensions.join(", ");
     lines.push("");
@@ -3779,6 +3792,46 @@ function applyExemptions(files, patterns) {
   };
 }
 
+// src/check/waiver.ts
+import { readFileSync as readFileSync16 } from "fs";
+import { join as join21 } from "path";
+var WAIVER = /jig-allow\s+([A-Z]-\d+(?:\s*,\s*[A-Z]-\d+)*)\s*:(.*)$/;
+function readWaiver(line) {
+  const m = WAIVER.exec(line);
+  if (!m) return void 0;
+  const reason = m[2].replace(/\s*(\*\/\s*\}?|-->|#\})\s*$/, "").trim();
+  if (!/\w/.test(reason)) return void 0;
+  return { ids: m[1].split(/\s*,\s*/), reason };
+}
+function applyWaivers(root, findings) {
+  const lines = /* @__PURE__ */ new Map();
+  const linesOf = (file) => {
+    let cached = lines.get(file);
+    if (!cached) {
+      try {
+        cached = readFileSync16(join21(root, file), "utf8").split("\n");
+      } catch {
+        cached = [];
+      }
+      lines.set(file, cached);
+    }
+    return cached;
+  };
+  const kept = [];
+  const waived = [];
+  for (const f of findings) {
+    if (f.severity !== "warning") {
+      kept.push(f);
+      continue;
+    }
+    const source = linesOf(f.file);
+    const waiver = [source[f.line - 1], source[f.line - 2]].map((l) => l === void 0 ? void 0 : readWaiver(l)).find((w) => w?.ids.includes(f.ruleId));
+    if (waiver) waived.push({ ...f, reason: waiver.reason });
+    else kept.push(f);
+  }
+  return { findings: kept, waived };
+}
+
 // src/check/responsive.ts
 var MEDIA_RE = /@media\b([^{]*)\{/gi;
 var VIEWPORT_FEATURE_RE = /\b(?:min-|max-)?(?:width|height|aspect-ratio|orientation|resolution)\b|\b(?:any-)?(?:pointer|hover)\b/i;
@@ -3821,8 +3874,8 @@ function hasMenuToggle(raw) {
 }
 
 // src/check/mode-wiring.ts
-import { existsSync as existsSync12, readFileSync as readFileSync16 } from "fs";
-import { dirname as dirname6, join as join21 } from "path";
+import { existsSync as existsSync12, readFileSync as readFileSync17 } from "fs";
+import { dirname as dirname6, join as join22 } from "path";
 var MODES = ["editorial", "product", "operator"];
 function configProblems(config) {
   const problems = [];
@@ -3844,10 +3897,10 @@ function configProblems(config) {
 }
 function modeWiringProblems(projectRoot) {
   let config;
-  const path = join21(projectRoot, "jig.config.json");
+  const path = join22(projectRoot, "jig.config.json");
   if (!existsSync12(path)) return [];
   try {
-    config = JSON.parse(readFileSync16(path, "utf8"));
+    config = JSON.parse(readFileSync17(path, "utf8"));
   } catch {
     return [{ mode: "", barrel: "jig.config.json", message: "jig.config.json is not valid JSON, so nothing in it applies" }];
   }
@@ -3858,14 +3911,14 @@ function modeWiringProblems(projectRoot) {
   if (modes.length === 0) return [];
   const dir = dirname6(config.brand);
   const rel = (f) => dir === "." ? f : `${dir}/${f}`;
-  if (!existsSync12(join21(projectRoot, rel("theme.css")))) return [];
+  if (!existsSync12(join22(projectRoot, rel("theme.css")))) return [];
   const problems = [];
   modes.forEach((mode, i) => {
     const barrel = rel(i === 0 ? "theme.css" : `theme.${mode}.css`);
     const modeFile = `mode.${mode}.css`;
     let body;
     try {
-      body = readFileSync16(join21(projectRoot, barrel), "utf8");
+      body = readFileSync17(join22(projectRoot, barrel), "utf8");
     } catch {
       problems.push({ mode, barrel, message: `jig.config.json declares ${mode}, but ${barrel} does not exist` });
       return;
@@ -3877,7 +3930,7 @@ function modeWiringProblems(projectRoot) {
         barrel,
         message: `jig.config.json declares ${mode}, but ${barrel} imports ${imported ? `mode.${imported}.css` : "no mode file"} \u2014 the page is styled at ${imported ?? "no"} density`
       });
-    } else if (!existsSync12(join21(projectRoot, rel(modeFile)))) {
+    } else if (!existsSync12(join22(projectRoot, rel(modeFile)))) {
       problems.push({ mode, barrel, message: `jig.config.json declares ${mode}, but ${rel(modeFile)} does not exist` });
     }
   });
@@ -3885,8 +3938,8 @@ function modeWiringProblems(projectRoot) {
 }
 
 // src/check/token-audit.ts
-import { existsSync as existsSync13, readdirSync as readdirSync9, readFileSync as readFileSync17 } from "fs";
-import { join as join22 } from "path";
+import { existsSync as existsSync13, readdirSync as readdirSync9, readFileSync as readFileSync18 } from "fs";
+import { join as join23 } from "path";
 var TEXT_FLOOR = 4.5;
 var UI_FLOOR = 3;
 var FOREGROUNDS = [
@@ -3942,24 +3995,24 @@ function floorFor(token) {
 function tokenFiles(projectRoot) {
   const read = (rel) => {
     try {
-      return readFileSync17(join22(projectRoot, ...rel.split("/")), "utf8");
+      return readFileSync18(join23(projectRoot, ...rel.split("/")), "utf8");
     } catch {
       return null;
     }
   };
-  const statePath = join22(projectRoot, ".jig", "state.json");
+  const statePath = join23(projectRoot, ".jig", "state.json");
   if (existsSync13(statePath)) {
     try {
-      const state = JSON.parse(readFileSync17(statePath, "utf8"));
+      const state = JSON.parse(readFileSync18(statePath, "utf8"));
       const recorded = Object.keys(state.files ?? {}).filter((f) => f.endsWith(".css")).sort();
       const out = recorded.map((path) => ({ path, source: read(path) })).filter((f) => f.source !== null);
       if (out.length > 0) return out;
     } catch {
     }
   }
-  const legacy = join22(projectRoot, ".jig", "tokens");
+  const legacy = join23(projectRoot, ".jig", "tokens");
   if (!existsSync13(legacy)) return [];
-  return readdirSync9(legacy).filter((f) => f.endsWith(".css")).sort().map((f) => ({ path: `.jig/tokens/${f}`, source: readFileSync17(join22(legacy, f), "utf8") }));
+  return readdirSync9(legacy).filter((f) => f.endsWith(".css")).sort().map((f) => ({ path: `.jig/tokens/${f}`, source: readFileSync18(join23(legacy, f), "utf8") }));
 }
 function auditTokenLayer(projectRoot) {
   const files = tokenFiles(projectRoot);
@@ -4027,15 +4080,15 @@ function auditTokenLayer(projectRoot) {
 }
 
 // src/commands/check.ts
-var LEGACY_INDEX_REL = join23(".jig", "rules.index.json");
+var LEGACY_INDEX_REL = join24(".jig", "rules.index.json");
 function resolveIndexPath(projectRoot) {
-  const legacy = join23(projectRoot, LEGACY_INDEX_REL);
+  const legacy = join24(projectRoot, LEGACY_INDEX_REL);
   if (existsSync14(legacy)) return legacy;
-  return join23(assetRoot(), "rules.index.json");
+  return join24(assetRoot(), "rules.index.json");
 }
 function resolveMode(projectRoot) {
   try {
-    const config = JSON.parse(readFileSync18(join23(projectRoot, "jig.config.json"), "utf8"));
+    const config = JSON.parse(readFileSync19(join24(projectRoot, "jig.config.json"), "utf8"));
     const modes = [...new Set((config.surfaces ?? []).map((s) => s.mode).filter(Boolean))];
     if (modes.length === 1) return modes[0];
     return modes.length > 1 ? "mixed" : "unknown";
@@ -4052,14 +4105,14 @@ function summariseUnscanned(files) {
 }
 function countSpecs() {
   try {
-    return loadSpecs(join23(assetRoot(), "rules")).length;
+    return loadSpecs(join24(assetRoot(), "rules")).length;
   } catch {
     return 0;
   }
 }
 function check(opts) {
   const indexPath = resolveIndexPath(opts.projectRoot);
-  const index = validateIndex(JSON.parse(readFileSync18(indexPath, "utf8")));
+  const index = validateIndex(JSON.parse(readFileSync19(indexPath, "utf8")));
   const selection = selectFiles(opts.projectRoot, opts.all);
   const exemptions = readExemptions(opts.projectRoot);
   const { scanned: files, exempt, byPattern } = applyExemptions(selection.files, exemptions);
@@ -4069,7 +4122,7 @@ function check(opts) {
   const projectParticipates = stylesheets.some((f) => {
     if (!hasExtension(f, CSS_EXTENSIONS)) return false;
     try {
-      return participatesInTokenLayer(readFileSync18(join23(opts.projectRoot, f), "utf8"), tokens);
+      return participatesInTokenLayer(readFileSync19(join24(opts.projectRoot, f), "utf8"), tokens);
     } catch {
       return false;
     }
@@ -4077,7 +4130,7 @@ function check(opts) {
   const projectResponsive = stylesheets.some((f) => {
     if (!isStyleBearing(f)) return false;
     try {
-      const raw = readFileSync18(join23(opts.projectRoot, f), "utf8");
+      const raw = readFileSync19(join24(opts.projectRoot, f), "utf8");
       return isResponsive(maskComments(maskNonStyleRegions(raw, f)), raw);
     } catch {
       return false;
@@ -4086,14 +4139,14 @@ function check(opts) {
   const viewportFitCover = stylesheets.some((f) => {
     if (!isStyleBearing(f)) return false;
     try {
-      return /viewport-fit\s*=\s*cover|viewportFit\s*:\s*['"]cover['"]/i.test(readFileSync18(join23(opts.projectRoot, f), "utf8"));
+      return /viewport-fit\s*=\s*cover|viewportFit\s*:\s*['"]cover['"]/i.test(readFileSync19(join24(opts.projectRoot, f), "utf8"));
     } catch {
       return false;
     }
   });
   const projectMenuToggle = stylesheets.some((f) => {
     try {
-      return hasMenuToggle(readFileSync18(join23(opts.projectRoot, f), "utf8"));
+      return hasMenuToggle(readFileSync19(join24(opts.projectRoot, f), "utf8"));
     } catch {
       return false;
     }
@@ -4101,14 +4154,14 @@ function check(opts) {
   const declaredProperties = collectDeclaredProperties(opts.projectRoot, stylesheets, Object.keys(tokens));
   const withStyles = files.filter((f) => {
     try {
-      const src = readFileSync18(join23(opts.projectRoot, f), "utf8");
+      const src = readFileSync19(join24(opts.projectRoot, f), "utf8");
       return hasExtension(f, CSS_EXTENSIONS) ? src.trim().length > 0 : maskNonStyleRegions(src, f).trim().length > 0;
     } catch {
       return false;
     }
   }).length;
   const resolvedMode = resolveMode(opts.projectRoot);
-  const findings = runChecks(opts.projectRoot, files, index, tokens, bucketFilter, projectParticipates, resolvedMode, projectResponsive, viewportFitCover, projectMenuToggle, declaredProperties);
+  const detected = runChecks(opts.projectRoot, files, index, tokens, bucketFilter, projectParticipates, resolvedMode, projectResponsive, viewportFitCover, projectMenuToggle, declaredProperties);
   const TOKEN_RULE = {
     "--text-prose": "B-75",
     "--size-touch-target": "E-51"
@@ -4116,7 +4169,7 @@ function check(opts) {
   for (const problem of auditTokenLayer(opts.projectRoot)) {
     const ruleId = TOKEN_RULE[problem.token] ?? "C-19";
     const entry = index.find((e) => e.id === ruleId);
-    findings.push({
+    detected.push({
       ruleId,
       detector: "token-layer",
       bucket: entry?.bucket ?? "mechanical",
@@ -4126,6 +4179,7 @@ function check(opts) {
       message: problem.message
     });
   }
+  const { findings, waived } = applyWaivers(opts.projectRoot, detected);
   const hasError = findings.some((f) => f.bucket === "mechanical" && f.severity === "error");
   const cssFiles = files.filter((f) => /\.(css|scss|less)$/i.test(f));
   const noTokenLayer = (
@@ -4133,7 +4187,7 @@ function check(opts) {
     // told to add a token @import it has nowhere to put.
     cssFiles.length > 0 && cssFiles.every((f) => {
       try {
-        return !participatesInTokenLayer(readFileSync18(join23(opts.projectRoot, f), "utf8"), tokens);
+        return !participatesInTokenLayer(readFileSync19(join24(opts.projectRoot, f), "utf8"), tokens);
       } catch {
         return true;
       }
@@ -4154,18 +4208,19 @@ function check(opts) {
     exempt,
     exemptPatterns: byPattern,
     scope: selection.mode,
-    modeUnwired: modeWiringProblems(opts.projectRoot)
+    modeUnwired: modeWiringProblems(opts.projectRoot),
+    waived
   });
-  return { findings, report, hasError };
+  return { findings, report, hasError, waived };
 }
 
 // src/commands/init.ts
-import { existsSync as existsSync15, mkdirSync as mkdirSync6, readdirSync as readdirSync10, readFileSync as readFileSync22, rmSync as rmSync2, writeFileSync as writeFileSync5 } from "fs";
-import { dirname as dirname7, isAbsolute, join as join27, resolve as resolve2, sep as sep3 } from "path";
+import { existsSync as existsSync15, mkdirSync as mkdirSync6, readdirSync as readdirSync10, readFileSync as readFileSync23, rmSync as rmSync2, writeFileSync as writeFileSync5 } from "fs";
+import { dirname as dirname7, isAbsolute, join as join28, resolve as resolve2, sep as sep3 } from "path";
 
 // src/init/detect.ts
-import { readFileSync as readFileSync19 } from "fs";
-import { join as join24 } from "path";
+import { readFileSync as readFileSync20 } from "fs";
+import { join as join25 } from "path";
 var TAILWIND_CONFIG_RE = /^tailwind\.config\.(js|ts|mjs|cjs)$/;
 var TAILWIND_V4_IMPORT_RE = /@import\s+["']tailwindcss["']/;
 var TAILWIND_V4_THEME_RE = /@theme\b/;
@@ -4182,7 +4237,7 @@ var FRAMEWORK_DEPS = [
 function detectFramework(projectRoot) {
   let pkg;
   try {
-    pkg = JSON.parse(readFileSync19(join24(projectRoot, "package.json"), "utf8"));
+    pkg = JSON.parse(readFileSync20(join25(projectRoot, "package.json"), "utf8"));
   } catch {
     return void 0;
   }
@@ -4200,7 +4255,7 @@ function detect(projectRoot) {
   for (const f of cssFiles) {
     let source;
     try {
-      source = readFileSync19(join24(projectRoot, f), "utf8");
+      source = readFileSync20(join25(projectRoot, f), "utf8");
     } catch {
       continue;
     }
@@ -4235,8 +4290,8 @@ function isIgnored(projectRoot, relPath) {
 }
 
 // src/init/derive.ts
-import { readFileSync as readFileSync20 } from "fs";
-import { join as join25 } from "path";
+import { readFileSync as readFileSync21 } from "fs";
+import { join as join26 } from "path";
 var DEFAULT_PROPOSAL = {
   h: 264,
   s: 0,
@@ -4269,7 +4324,7 @@ function fromCssCustomProperties(projectRoot, cssFiles) {
   for (const file of cssFiles) {
     let source;
     try {
-      source = readFileSync20(join25(projectRoot, file), "utf8");
+      source = readFileSync21(join26(projectRoot, file), "utf8");
     } catch {
       continue;
     }
@@ -4318,7 +4373,7 @@ function balancedBraceBody(source, openIdx) {
 function fromTailwindConfig(projectRoot, tailwindConfigFile) {
   let source;
   try {
-    source = readFileSync20(join25(projectRoot, tailwindConfigFile), "utf8");
+    source = readFileSync21(join26(projectRoot, tailwindConfigFile), "utf8");
   } catch {
     return null;
   }
@@ -4374,7 +4429,7 @@ function fromLiteralFrequency(projectRoot, cssFiles) {
   for (const file of cssFiles) {
     let source;
     try {
-      source = readFileSync20(join25(projectRoot, file), "utf8");
+      source = readFileSync21(join26(projectRoot, file), "utf8");
     } catch {
       continue;
     }
@@ -4534,8 +4589,8 @@ function relativeImportPath(fromAbsDir, toAbsFile) {
 }
 
 // src/init/project-name.ts
-import { readFileSync as readFileSync21 } from "fs";
-import { basename, join as join26 } from "path";
+import { readFileSync as readFileSync22 } from "fs";
+import { basename, join as join27 } from "path";
 function slugify(name) {
   const withoutScope = name.replace(/^@[^/]+\//, "");
   const slug = withoutScope.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
@@ -4543,7 +4598,7 @@ function slugify(name) {
 }
 function deriveProjectSlug(projectRoot) {
   try {
-    const pkg = JSON.parse(readFileSync21(join26(projectRoot, "package.json"), "utf8"));
+    const pkg = JSON.parse(readFileSync22(join27(projectRoot, "package.json"), "utf8"));
     if (typeof pkg.name === "string" && pkg.name.trim()) return slugify(pkg.name);
   } catch {
   }
@@ -4697,9 +4752,9 @@ function isValidSurfaceArray(v) {
 function loadEffectiveConfig(projectRoot, configAbsPath, fallbackBrand, fallbackSurfaces) {
   if (!existsSync15(configAbsPath)) return { brand: fallbackBrand, surfaces: fallbackSurfaces };
   try {
-    const parsed = JSON.parse(readFileSync22(configAbsPath, "utf8"));
+    const parsed = JSON.parse(readFileSync23(configAbsPath, "utf8"));
     const brandCandidate = typeof parsed.brand === "string" && parsed.brand ? parsed.brand : void 0;
-    const brandResolves = brandCandidate ? existsSync15(join27(projectRoot, ...brandCandidate.split("/"))) : false;
+    const brandResolves = brandCandidate ? existsSync15(join28(projectRoot, ...brandCandidate.split("/"))) : false;
     return {
       brand: brandResolves ? brandCandidate : fallbackBrand,
       surfaces: isValidSurfaceArray(parsed.surfaces) ? parsed.surfaces : fallbackSurfaces
@@ -4712,7 +4767,7 @@ function configuredBrandPath(projectRoot, configAbsPath) {
   if (!existsSync15(configAbsPath)) return { path: null };
   let declared;
   try {
-    declared = JSON.parse(readFileSync22(configAbsPath, "utf8")).brand;
+    declared = JSON.parse(readFileSync23(configAbsPath, "utf8")).brand;
   } catch {
     return { path: null };
   }
@@ -4742,7 +4797,7 @@ function defaultTokenDir(detection) {
 function readConfiguredSurfaces(configAbsPath) {
   if (!existsSync15(configAbsPath)) return null;
   try {
-    const parsed = JSON.parse(readFileSync22(configAbsPath, "utf8"));
+    const parsed = JSON.parse(readFileSync23(configAbsPath, "utf8"));
     return isValidSurfaceArray(parsed.surfaces) ? parsed.surfaces : null;
   } catch {
     return null;
@@ -4752,7 +4807,7 @@ function isCssModule(path) {
   return /\.module\.(css|scss)$/i.test(path);
 }
 function legacyBrandFile(projectRoot) {
-  const dir = join27(projectRoot, ".jig", "tokens");
+  const dir = join28(projectRoot, ".jig", "tokens");
   if (!existsSync15(dir)) return void 0;
   const found = readdirSync10(dir).find((f) => /^brand\.[\w.-]+\.css$/.test(f));
   return found ? relKey(".jig", "tokens", found) : void 0;
@@ -4784,7 +4839,7 @@ var LEGACY_PAIR_RE = new RegExp(
   `@import\\s+["'][^"']*brand\\.[\\w.-]+\\.css["'];?\\r?\\n?\\s*@import\\s+["'][^"']*mode\\.(?:${MODES2.join("|")})\\.css["'];?\\r?\\n?`
 );
 function wireBarrel(absPath, barrelImport) {
-  const content = existsSync15(absPath) ? readFileSync22(absPath, "utf8") : "";
+  const content = existsSync15(absPath) ? readFileSync23(absPath, "utf8") : "";
   const line = `@import "${barrelImport}";`;
   if (content.includes(line)) return { status: "already-present" };
   const legacy = LEGACY_PAIR_RE.exec(content);
@@ -4872,7 +4927,7 @@ async function init(opts) {
     }
   }
   if (opts.yes) {
-    const declared = readConfiguredSurfaces(join27(opts.projectRoot, "jig.config.json"));
+    const declared = readConfiguredSurfaces(join28(opts.projectRoot, "jig.config.json"));
     const inEffect = declared ?? surfaces;
     const map = inEffect.map((x) => `'${x.match}' \u2192 ${x.mode}`).join(", ");
     log(
@@ -4891,7 +4946,7 @@ Brand colour adjusted to clear the 4.5:1 contrast floor: l:${originalL}% \u2192
   const finalColor = { h: proposal.h, s: proposal.s, l: proposal.l };
   const projectSlug = deriveProjectSlug(opts.projectRoot);
   const configRelPath = "jig.config.json";
-  const configAbsPath = join27(opts.projectRoot, configRelPath);
+  const configAbsPath = join28(opts.projectRoot, configRelPath);
   const configuredBrand = configuredBrandPath(opts.projectRoot, configAbsPath);
   if (configuredBrand.refused) {
     log(
@@ -4925,7 +4980,7 @@ The token layer is at ${currentDir}/, and this project's layout suggests ${would
     }
   }
   const brandRelPath = relocateTo ?? configuredBrand.path ?? priorBrand ?? relKey(...defaultTokenDir(detection), brandFileName(projectSlug));
-  const brandAbsPath = join27(opts.projectRoot, ...brandRelPath.split("/"));
+  const brandAbsPath = join28(opts.projectRoot, ...brandRelPath.split("/"));
   const tokensRelDir = brandRelPath.split("/").slice(0, -1);
   log(
     `Token layer: ${tokensRelDir.join("/") || "."}/ \u2014 ` + (configuredBrand.path ? "from jig.config.json." : priorBrand ? "the layout this project already had. Set `brand` in jig.config.json to move it." : findWireTarget(detection) ? "beside the stylesheet being wired. Set `brand` in jig.config.json to put it elsewhere." : "no stylesheet found to follow, so the project root. Set `brand` in jig.config.json to move it.")
@@ -4958,7 +5013,7 @@ ${configRelPath} already exists and was not created by 'jig init' (or has been e
     if (configAction !== "written") log(`  ${configRelPath} exists and is not jig-tracked \u2014 leaving it alone (re-run without --yes to refresh).`);
   }
   if (brandAction === "written") {
-    const defaultCssRaw = readFileSync22(join27(opts.packageRoot, "tokens", "brand.default.css"), "utf8");
+    const defaultCssRaw = readFileSync23(join28(opts.packageRoot, "tokens", "brand.default.css"), "utf8");
     const content = renderBrandFile(defaultCssRaw, projectSlug, opts.version, proposal);
     mkdirSync6(dirname7(brandAbsPath), { recursive: true });
     writeFileSync5(brandAbsPath, content, "utf8");
@@ -4966,7 +5021,7 @@ ${configRelPath} already exists and was not created by 'jig init' (or has been e
   }
   if (relocateTo && configAction !== "written") {
     try {
-      const existing = JSON.parse(readFileSync22(configAbsPath, "utf8"));
+      const existing = JSON.parse(readFileSync23(configAbsPath, "utf8"));
       const content = `${JSON.stringify({ ...existing, brand: brandRelPath }, null, 2)}
 `;
       writeFileSync5(configAbsPath, content, "utf8");
@@ -4985,12 +5040,12 @@ ${configRelPath} already exists and was not created by 'jig init' (or has been e
   } else if (configAction === "merged") {
     let existing = {};
     try {
-      existing = JSON.parse(readFileSync22(configAbsPath, "utf8"));
+      existing = JSON.parse(readFileSync23(configAbsPath, "utf8"));
     } catch {
       existing = {};
     }
     const existingBrand = typeof existing.brand === "string" ? existing.brand : void 0;
-    const brandStillResolves = existingBrand ? existsSync15(join27(opts.projectRoot, ...existingBrand.split("/"))) : false;
+    const brandStillResolves = existingBrand ? existsSync15(join28(opts.projectRoot, ...existingBrand.split("/"))) : false;
     const existingSurfaces = Array.isArray(existing.surfaces) && existing.surfaces.length > 0 ? existing.surfaces : void 0;
     const merged = {
       brand: brandStillResolves ? existingBrand : brandRelPath,
@@ -5005,12 +5060,12 @@ ${configRelPath} already exists and was not created by 'jig init' (or has been e
   }
   const effectiveConfig = loadEffectiveConfig(opts.projectRoot, configAbsPath, brandRelPath, surfaces);
   const primaryMode = effectiveConfig.surfaces[0]?.mode ?? "product";
-  const wiringBrandAbsPath = join27(opts.projectRoot, ...effectiveConfig.brand.split("/"));
+  const wiringBrandAbsPath = join28(opts.projectRoot, ...effectiveConfig.brand.split("/"));
   const declaredModes = [...new Set(effectiveConfig.surfaces.map((s) => s.mode))];
   const modeAbsPaths = {};
   for (const mode of declaredModes) {
     const modeFileName = `mode.${mode}.css`;
-    const modeAbsPath2 = join27(opts.projectRoot, ...tokensRelDir, modeFileName);
+    const modeAbsPath2 = join28(opts.projectRoot, ...tokensRelDir, modeFileName);
     modeAbsPaths[mode] = modeAbsPath2;
     const modeRelPath = relKey(...tokensRelDir, modeFileName);
     const modeState = fileState(opts.projectRoot, modeAbsPath2, modeRelPath, initManifest);
@@ -5018,7 +5073,7 @@ ${configRelPath} already exists and was not created by 'jig init' (or has been e
     if (modeState.existsOnDisk && !modeState.tracked) modeAction = "skipped-untracked";
     else if (modeState.modified) modeAction = "skipped-edited";
     if (modeAction === "written") {
-      const modeSourceRaw = readFileSync22(join27(opts.packageRoot, "tokens", modeFileName), "utf8");
+      const modeSourceRaw = readFileSync23(join28(opts.packageRoot, "tokens", modeFileName), "utf8");
       const content = vendorHeader(modeFileName, opts.version, "css", null) + modeSourceRaw;
       mkdirSync6(dirname7(modeAbsPath2), { recursive: true });
       writeFileSync5(modeAbsPath2, content, "utf8");
@@ -5032,7 +5087,7 @@ ${configRelPath} already exists and was not created by 'jig init' (or has been e
   const barrelFor = (mode) => mode === primaryMode ? "theme.css" : `theme.${mode}.css`;
   for (const mode of declaredModes) {
     const rel = relKey(...tokensRelDir, barrelFor(mode));
-    const abs = join27(opts.projectRoot, ...tokensRelDir, barrelFor(mode));
+    const abs = join28(opts.projectRoot, ...tokensRelDir, barrelFor(mode));
     const state = fileState(opts.projectRoot, abs, rel, initManifest);
     if (state.existsOnDisk && (!state.tracked || state.modified)) {
       log(`  ${rel} exists and is not jig-tracked (or has been edited) \u2014 leaving it alone.`);
@@ -5047,7 +5102,7 @@ ${configRelPath} already exists and was not created by 'jig init' (or has been e
     const declared = declaredTokenNames(
       [brandAbsPath, modeAbsPath].map((f) => {
         try {
-          return readFileSync22(f, "utf8");
+          return readFileSync23(f, "utf8");
         } catch {
           return "";
         }
@@ -5072,7 +5127,7 @@ ${configRelPath} already exists and was not created by 'jig init' (or has been e
       log(`  This changes how components are written. Both styles are correct.`);
       const answer = (await prompt("  Generate it? [y/N]: ")).toLowerCase();
       if (answer === "y" || answer === "yes") {
-        const abs = join27(opts.projectRoot, ...tokensRelDir, "utilities.css");
+        const abs = join28(opts.projectRoot, ...tokensRelDir, "utilities.css");
         const state = fileState(opts.projectRoot, abs, rel, initManifest);
         if (state.existsOnDisk && (!state.tracked || state.modified)) {
           log(`  ${rel} exists and is not jig-tracked (or has been edited) \u2014 leaving it alone.`);
@@ -5083,8 +5138,8 @@ ${configRelPath} already exists and was not created by 'jig init' (or has been e
           files[rel] = checksum(content);
           const target = findWireTarget(detection);
           const importPath = target ? relativeImportPath(
-            dirname7(join27(opts.projectRoot, target)),
-            join27(opts.projectRoot, ...tokensRelDir, "utilities.css")
+            dirname7(join28(opts.projectRoot, target)),
+            join28(opts.projectRoot, ...tokensRelDir, "utilities.css")
           ) : `./${rel}`;
           log(`  Wrote ${rel}. Import it in the stylesheet that imports Tailwind:`);
           log(`    @import "tailwindcss";`);
@@ -5102,11 +5157,11 @@ ${configRelPath} already exists and was not created by 'jig init' (or has been e
   writeInitManifest(opts.projectRoot, { version: opts.version, modes: declaredModes, files });
   if (relocateTo && currentBrand) {
     const oldDir = currentBrand.split("/").slice(0, -1);
-    const oldAbsDir = join27(opts.projectRoot, ...oldDir);
+    const oldAbsDir = join28(opts.projectRoot, ...oldDir);
     if (existsSync15(oldAbsDir)) {
       for (const name of readdirSync10(oldAbsDir).filter((f) => f.endsWith(".css"))) {
         const rel = relKey(...oldDir, name);
-        const abs = join27(oldAbsDir, name);
+        const abs = join28(oldAbsDir, name);
         const state = fileState(opts.projectRoot, abs, rel, initManifest);
         if (!state.tracked || state.modified) {
           log(`  ${rel} was edited \u2014 left in place. Delete it yourself once you have moved anything you need.`);
@@ -5120,21 +5175,21 @@ ${configRelPath} already exists and was not created by 'jig init' (or has been e
   const wireTarget = findWireTarget(detection);
   let wiring;
   if (wireTarget) {
-    const targetAbsDir = dirname7(join27(opts.projectRoot, wireTarget));
+    const targetAbsDir = dirname7(join28(opts.projectRoot, wireTarget));
     const barrelImport = relativeImportPath(
       targetAbsDir,
-      join27(opts.projectRoot, ...tokensRelDir, "theme.css")
+      join28(opts.projectRoot, ...tokensRelDir, "theme.css")
     );
     const snippet = `@import "${barrelImport}";`;
     try {
       if (relocateTo && currentBrand) {
-        const abs = join27(opts.projectRoot, wireTarget);
+        const abs = join28(opts.projectRoot, wireTarget);
         const oldDirName = currentBrand.split("/").slice(0, -1).join("/");
-        const before = existsSync15(abs) ? readFileSync22(abs, "utf8") : "";
+        const before = existsSync15(abs) ? readFileSync23(abs, "utf8") : "";
         const after = before.split("\n").filter((l) => !(l.includes("@import") && l.includes(oldDirName))).join("\n");
         if (after !== before) writeFileSync5(abs, after, "utf8");
       }
-      const outcome = wireBarrel(join27(opts.projectRoot, wireTarget), barrelImport);
+      const outcome = wireBarrel(join28(opts.projectRoot, wireTarget), barrelImport);
       wiring = { target: wireTarget, status: outcome.status, snippet };
       const verb = outcome.status === "wired" ? "Wired" : outcome.status === "rewired" ? "Rewired" : "Already present in";
       log(`
@@ -5151,7 +5206,7 @@ Could not write to ${wireTarget}: ${err.message}`);
   } else {
     const barrelImport = relativeImportPath(
       opts.projectRoot,
-      join27(opts.projectRoot, ...tokensRelDir, "theme.css")
+      join28(opts.projectRoot, ...tokensRelDir, "theme.css")
     );
     const snippet = `@import "${barrelImport}";`;
     wiring = { target: null, status: "print-only", snippet };
@@ -5160,7 +5215,7 @@ Could not write to ${wireTarget}: ${err.message}`);
     if (pasteTargets.length > 0) {
       log("Paste the block for whichever of these is your global stylesheet:");
       for (const target of pasteTargets) {
-        const dir = dirname7(join27(opts.projectRoot, target));
+        const dir = dirname7(join28(opts.projectRoot, target));
         const forTarget = `@import "${relativeImportPath(dir, wiringBrandAbsPath)}";
 @import "${relativeImportPath(dir, modeAbsPath)}";`;
         log(`
@@ -5207,28 +5262,28 @@ Could not write to ${wireTarget}: ${err.message}`);
 }
 
 // src/commands/verdicts.ts
-import { existsSync as existsSync20, readFileSync as readFileSync26 } from "fs";
-import { join as join33, resolve as resolve4 } from "path";
+import { existsSync as existsSync20, readFileSync as readFileSync27 } from "fs";
+import { join as join34, resolve as resolve4 } from "path";
 
 // src/rules/citations.ts
-import { join as join28 } from "path";
+import { join as join29 } from "path";
 function citableIds(packageRoot2) {
-  const rulesDir = join28(packageRoot2, "rules");
+  const rulesDir = join29(packageRoot2, "rules");
   const ids = [
-    ...loadRules(rulesDir, join28(packageRoot2, "rules.index.json")).map((r) => r.id),
+    ...loadRules(rulesDir, join29(packageRoot2, "rules.index.json")).map((r) => r.id),
     ...loadSpecs(rulesDir).map((s) => s.id)
   ];
   return [...new Set(ids)].sort();
 }
 
 // src/probe/check.ts
-import { existsSync as existsSync18, readdirSync as readdirSync13, readFileSync as readFileSync24 } from "fs";
-import { join as join31 } from "path";
+import { existsSync as existsSync18, readdirSync as readdirSync13, readFileSync as readFileSync25 } from "fs";
+import { join as join32 } from "path";
 
 // src/probe/save.ts
-import { existsSync as existsSync17, mkdirSync as mkdirSync7, readdirSync as readdirSync12, readFileSync as readFileSync23, writeFileSync as writeFileSync6 } from "fs";
+import { existsSync as existsSync17, mkdirSync as mkdirSync7, readdirSync as readdirSync12, readFileSync as readFileSync24, writeFileSync as writeFileSync6 } from "fs";
 import { fileURLToPath as fileURLToPath2 } from "url";
-import { join as join30, relative as relative3, resolve as resolve3 } from "path";
+import { join as join31, relative as relative3, resolve as resolve3 } from "path";
 
 // src/probe/script.ts
 var PROBE_VERSION = 5;
@@ -5375,7 +5430,7 @@ var PROBE_SCRIPT = `(async () => {
 import { spawn } from "child_process";
 import { existsSync as existsSync16, mkdtempSync, readdirSync as readdirSync11, rmSync as rmSync3 } from "fs";
 import { homedir, tmpdir } from "os";
-import { join as join29 } from "path";
+import { join as join30 } from "path";
 var CHROME_ENV = ["JIG_CHROME", "CHROME_PATH", "PUPPETEER_EXECUTABLE_PATH", "CHROMIUM_PATH"];
 var CHROME_COMMANDS = ["google-chrome", "google-chrome-stable", "chromium", "chromium-browser", "microsoft-edge", "brave-browser"];
 var CHROME_APPS = [
@@ -5387,10 +5442,10 @@ var CHROME_APPS = [
 ];
 function cachedBrowsers() {
   const roots = [
-    join29(homedir(), ".cache", "ms-playwright"),
-    join29(homedir(), "Library", "Caches", "ms-playwright"),
-    join29(homedir(), "AppData", "Local", "ms-playwright"),
-    join29(homedir(), ".cache", "puppeteer", "chrome")
+    join30(homedir(), ".cache", "ms-playwright"),
+    join30(homedir(), "Library", "Caches", "ms-playwright"),
+    join30(homedir(), "AppData", "Local", "ms-playwright"),
+    join30(homedir(), ".cache", "puppeteer", "chrome")
   ];
   const found = [];
   for (const root of roots) {
@@ -5410,7 +5465,7 @@ function cachedBrowsers() {
         ["chrome-win", "chrome.exe"],
         ["chrome-win64", "chrome.exe"]
       ]) {
-        const candidate = join29(root, entry, ...rel);
+        const candidate = join30(root, entry, ...rel);
         if (existsSync16(candidate)) found.push(candidate);
       }
     }
@@ -5433,7 +5488,7 @@ function which(command) {
   const dirs = (process.env.PATH ?? "").split(process.platform === "win32" ? ";" : ":");
   for (const dir of dirs) {
     if (!dir) continue;
-    const candidate = join29(dir, command);
+    const candidate = join30(dir, command);
     if (existsSync16(candidate)) return candidate;
   }
   return void 0;
@@ -5445,7 +5500,7 @@ async function runProbe(opts) {
       "No browser found to run the probe. Install one, or set JIG_CHROME to a Chrome, Chromium or Edge binary. A project with Playwright or Puppeteer already has one, and Jig will find it."
     );
   }
-  const profile = mkdtempSync(join29(tmpdir(), "jig-probe-"));
+  const profile = mkdtempSync(join30(tmpdir(), "jig-probe-"));
   const child = spawn(chrome, [
     "--headless=new",
     "--remote-debugging-port=0",
@@ -5558,11 +5613,11 @@ function saveProbe(opts) {
     throw new Error(`The probe ran at ${url || "no url"}, which is not a file in this project. Open the page you built \u2014 a file:// URL under the project \u2014 and probe that.`);
   }
   probe.pageFile = relative3(opts.projectRoot, page).split("\\").join("/");
-  probe.pageChecksum = checksum(readFileSync23(page, "utf8"));
+  probe.pageChecksum = checksum(readFileSync24(page, "utf8"));
   probe.recordedAt = (/* @__PURE__ */ new Date()).toISOString();
-  const dir = join30(opts.projectRoot, ".jig", "critique", opts.surface);
+  const dir = join31(opts.projectRoot, ".jig", "critique", opts.surface);
   mkdirSync7(dir, { recursive: true });
-  const path = join30(dir, `probe-${width}.json`);
+  const path = join31(dir, `probe-${width}.json`);
   writeFileSync6(path, JSON.stringify(probe), "utf8");
   return { path: `.jig/critique/${opts.surface}/probe-${width}.json`, width, page: probe.pageFile };
 }
@@ -5591,17 +5646,17 @@ async function runAndSaveProbes(opts) {
   return saved;
 }
 async function ensureProbes(opts) {
-  const dir = join30(opts.projectRoot, ".jig", "critique", opts.surface);
+  const dir = join31(opts.projectRoot, ".jig", "critique", opts.surface);
   const abs = resolve3(opts.projectRoot, opts.page);
   let current;
   try {
-    current = checksum(readFileSync23(abs, "utf8"));
+    current = checksum(readFileSync24(abs, "utf8"));
   } catch {
     return { recorded: [], reason: `${opts.page} could not be read` };
   }
   const missing = PROBE_WIDTHS.filter((width) => {
     try {
-      const probe = JSON.parse(readFileSync23(join30(dir, `probe-${width}.json`), "utf8"));
+      const probe = JSON.parse(readFileSync24(join31(dir, `probe-${width}.json`), "utf8"));
       return probe.jigProbe !== PROBE_VERSION || probe.pageChecksum !== current;
     } catch {
       return true;
@@ -5616,9 +5671,9 @@ async function ensureProbes(opts) {
   return { recorded: missing };
 }
 function critiquedSurfaces(projectRoot) {
-  const root = join30(projectRoot, ".jig", "critique");
+  const root = join31(projectRoot, ".jig", "critique");
   if (!existsSync17(root)) return [];
-  return readdirSync12(root).filter((surface) => existsSync17(join30(root, surface, "screen.json")) || existsSync17(join30(root, surface, "code.json")));
+  return readdirSync12(root).filter((surface) => existsSync17(join31(root, surface, "screen.json")) || existsSync17(join31(root, surface, "code.json")));
 }
 
 // src/probe/check.ts
@@ -5630,7 +5685,7 @@ function stampProblem(projectRoot, file, p) {
   if (!page) return `${file} names a page outside this project (${p.url ?? "no url"}).`;
   let current;
   try {
-    current = readFileSync24(page, "utf8");
+    current = readFileSync25(page, "utf8");
   } catch {
     return `${file} was taken on ${p.pageFile}, which no longer exists.`;
   }
@@ -5644,7 +5699,7 @@ function readProbes(projectRoot, dir, errors) {
   const probes = [];
   for (const f of readdirSync13(dir).filter((n) => /^probe-\d+\.json$/.test(n)).sort()) {
     try {
-      const p = JSON.parse(readFileSync24(join31(dir, f), "utf8"));
+      const p = JSON.parse(readFileSync25(join32(dir, f), "utf8"));
       if (p.jigProbe !== PROBE_VERSION || typeof p.width !== "number") {
         errors.push(`${f} is not output of \`jig probe\` (version ${PROBE_VERSION}). Re-run the probe; do not write it by hand.`);
         continue;
@@ -5736,13 +5791,19 @@ function probeContradictions(probes, verdictOf, indexable = true) {
 }
 
 // src/check/decisions.ts
-import { existsSync as existsSync19, readFileSync as readFileSync25 } from "fs";
-import { join as join32 } from "path";
+import { existsSync as existsSync19, readFileSync as readFileSync26 } from "fs";
+import { join as join33, posix as posix3 } from "path";
 var HEADING3 = /^(#{2,3})\s+(.+?)\s*$/gm;
 var NOT_A_DECISION = /^(unresolved|open questions?|undecided|contents?|index)$/i;
 function decisionsFile(projectRoot) {
-  for (const candidate of ["jig/DECISIONS.md", "DECISIONS.md", "src/jig/DECISIONS.md", "src/styles/jig/DECISIONS.md", ".jig/DECISIONS.md"]) {
-    if (existsSync19(join32(projectRoot, candidate))) return candidate;
+  const candidates = ["jig/DECISIONS.md", "DECISIONS.md", "src/jig/DECISIONS.md", "src/styles/jig/DECISIONS.md", ".jig/DECISIONS.md"];
+  try {
+    const brand = JSON.parse(readFileSync26(join33(projectRoot, "jig.config.json"), "utf8")).brand;
+    if (typeof brand === "string" && brand.includes("/")) candidates.unshift(`${posix3.dirname(brand.replace(/^\.\//, ""))}/DECISIONS.md`);
+  } catch {
+  }
+  for (const candidate of candidates) {
+    if (existsSync19(join33(projectRoot, candidate))) return candidate;
   }
   return void 0;
 }
@@ -5751,7 +5812,7 @@ function decisionNames(projectRoot) {
   if (!path) return [];
   let body;
   try {
-    body = readFileSync25(join32(projectRoot, path), "utf8");
+    body = readFileSync26(join33(projectRoot, path), "utf8");
   } catch {
     return [];
   }
@@ -5770,17 +5831,17 @@ var ABSENCE = /\b(rule (not found|does not exist)|context unavailable|cannot (fi
 function readJson(path, errors) {
   if (!existsSync20(path)) return null;
   try {
-    return JSON.parse(readFileSync26(path, "utf8"));
+    return JSON.parse(readFileSync27(path, "utf8"));
   } catch (e) {
     errors.push(`${path}: not valid JSON (${e.message})`);
     return {};
   }
 }
 function specIndexable(projectRoot, surface) {
-  const path = join33(projectRoot, ".jig", "specs", `${surface}.spec.md`);
+  const path = join34(projectRoot, ".jig", "specs", `${surface}.spec.md`);
   let front = "";
   try {
-    front = readFileSync26(path, "utf8").split(/^---\s*$/m)[1] ?? "";
+    front = readFileSync27(path, "utf8").split(/^---\s*$/m)[1] ?? "";
   } catch {
   }
   const declared = /^\s*indexable\s*:\s*(\w+)/im.exec(front)?.[1]?.toLowerCase();
@@ -5790,9 +5851,9 @@ function specIndexable(projectRoot, surface) {
   return mode !== "product" && mode !== "operator";
 }
 function specNeedsNav(projectRoot, surface) {
-  const path = join33(projectRoot, ".jig", "specs", `${surface}.spec.md`);
+  const path = join34(projectRoot, ".jig", "specs", `${surface}.spec.md`);
   if (!existsSync20(path)) return false;
-  const front = readFileSync26(path, "utf8").split(/^---\s*$/m)[1] ?? "";
+  const front = readFileSync27(path, "utf8").split(/^---\s*$/m)[1] ?? "";
   const navField = [...front.matchAll(/^\s*nav:\s*(.+)$/gim)].some((m) => !/^\s*(none|n\/a|-)\b/i.test(m[1]));
   const navRegion = /^\s*-\s*(nav|navigation)\s*:/im.test(front);
   return navField || navRegion;
@@ -5843,7 +5904,7 @@ function checkArm(name, file, required, otherPass, extraAllowed, extraRequired,
 function checkDecisions(projectRoot, dir, errors) {
   const required = decisionNames(projectRoot);
   if (required.length === 0) return { state: "ran", judged: 0, total: 0, findings: 0 };
-  const file = readJson(join33(dir, "decisions.json"), errors);
+  const file = readJson(join34(dir, "decisions.json"), errors);
   if (!file) {
     errors.push(
       `decisions.json is missing. Every decision in DECISIONS.md is judged against the built page, one verdict each: ${required.slice(0, 4).join(", ")}${required.length > 4 ? `, and ${required.length - 4} more` : ""}. A page can satisfy every rule and still break what this project decided.`
@@ -5888,7 +5949,7 @@ function checkDecisions(projectRoot, dir, errors) {
 function verifyVerdicts(opts) {
   const root = opts.packageRoot ?? assetRoot();
   const errors = [];
-  const index = JSON.parse(readFileSync26(join33(root, "rules.index.json"), "utf8"));
+  const index = JSON.parse(readFileSync27(join34(root, "rules.index.json"), "utf8"));
   const judgment = index.filter((r) => r.bucket === "judgment");
   const screenIds = judgment.filter((r) => r.pass === "screen").map((r) => r.id);
   const codeIds = judgment.filter((r) => r.pass === "code").map((r) => r.id);
@@ -5897,9 +5958,9 @@ function verifyVerdicts(opts) {
     ...judgment.map((r) => [r.id, r.pass ?? ""])
   ]);
   const specIds = new Set(citableIds(root).filter((id) => /^[PMLRT]-\d+$/.test(id)));
-  const dir = join33(opts.projectRoot, ".jig", "critique", opts.surface);
-  const screenFile = readJson(join33(dir, "screen.json"), errors);
-  const codeFile = readJson(join33(dir, "code.json"), errors);
+  const dir = join34(opts.projectRoot, ".jig", "critique", opts.surface);
+  const screenFile = readJson(join34(dir, "screen.json"), errors);
+  const codeFile = readJson(join34(dir, "code.json"), errors);
   const screenExtraRequired = specNeedsNav(opts.projectRoot, opts.surface) ? ["P-14"] : [];
   const screen = checkArm("screen", screenFile, screenIds, passOf, specIds, screenExtraRequired, errors);
   const code = checkArm("code", codeFile, codeIds, passOf, specIds, [], errors);
@@ -5934,20 +5995,20 @@ function verifyVerdicts(opts) {
 }
 
 // src/commands/gate.ts
-import { existsSync as existsSync22, mkdirSync as mkdirSync8, readdirSync as readdirSync15, readFileSync as readFileSync28, writeFileSync as writeFileSync7 } from "fs";
+import { existsSync as existsSync22, mkdirSync as mkdirSync8, readdirSync as readdirSync15, readFileSync as readFileSync29, writeFileSync as writeFileSync7 } from "fs";
 import { createHash as createHash2 } from "crypto";
-import { join as join35 } from "path";
+import { join as join36 } from "path";
 
 // src/check/spec-shape.ts
-import { existsSync as existsSync21, readFileSync as readFileSync27, readdirSync as readdirSync14, statSync as statSync2 } from "fs";
-import { join as join34 } from "path";
+import { existsSync as existsSync21, readFileSync as readFileSync28, readdirSync as readdirSync14, statSync as statSync2 } from "fs";
+import { join as join35 } from "path";
 function newestSpec(projectRoot) {
-  const dir = join34(projectRoot, ".jig", "specs");
+  const dir = join35(projectRoot, ".jig", "specs");
   if (!existsSync21(dir)) return void 0;
   const files = readdirSync14(dir).filter((f) => f.endsWith(".md"));
   if (files.length === 0) return void 0;
-  const newest = files.map((f) => ({ f, at: statSync2(join34(dir, f)).mtimeMs })).sort((a, b) => b.at - a.at)[0].f;
-  return { path: `.jig/specs/${newest}`, slug: newest.replace(/\.spec\.md$|\.md$/, ""), body: readFileSync27(join34(dir, newest), "utf8") };
+  const newest = files.map((f) => ({ f, at: statSync2(join35(dir, f)).mtimeMs })).sort((a, b) => b.at - a.at)[0].f;
+  return { path: `.jig/specs/${newest}`, slug: newest.replace(/\.spec\.md$|\.md$/, ""), body: readFileSync28(join35(dir, newest), "utf8") };
 }
 function specProblems(spec) {
   const parts = spec.body.split(/^---\s*$/m);
@@ -6019,7 +6080,7 @@ function lastJigCommand(transcriptPath) {
   if (!transcriptPath || !existsSync22(transcriptPath)) return void 0;
   let text;
   try {
-    text = readFileSync28(transcriptPath, "utf8");
+    text = readFileSync29(transcriptPath, "utf8");
   } catch {
     return void 0;
   }
@@ -6033,14 +6094,41 @@ function lastJigCommand(transcriptPath) {
   }
   return found;
 }
+function lastAssistantText(transcriptPath) {
+  if (!transcriptPath || !existsSync22(transcriptPath)) return void 0;
+  let found;
+  try {
+    for (const line of readFileSync29(transcriptPath, "utf8").split("\n")) {
+      if (!line.includes('"assistant"')) continue;
+      let entry;
+      try {
+        entry = JSON.parse(line);
+      } catch {
+        continue;
+      }
+      if (entry.type !== "assistant" || !Array.isArray(entry.message?.content)) continue;
+      const text = entry.message.content.filter((c) => c.type === "text" && c.text).map((c) => c.text).join("");
+      if (text.trim()) found = text;
+    }
+  } catch {
+    return void 0;
+  }
+  return found;
+}
+function asksOwner(text) {
+  if (!text) return false;
+  const last = text.trim().split("\n").filter((l) => l.trim()).pop() ?? "";
+  return /\?\s*$/.test(last.replace(/[*_`"')\]\s]+$/, ""));
+}
+var ASKS_THE_OWNER = /* @__PURE__ */ new Set(["decide", "spec", "mockup"]);
 function commandProblems(root, command) {
   const problems = [];
   const spec = newestSpec(root);
   if (command === "decide") {
-    const file = ["jig/DECISIONS.md", "DECISIONS.md", ".jig/DECISIONS.md"].map((p) => join35(root, p)).find((p) => existsSync22(p));
-    if (!file) problems.push("decide wrote no DECISIONS.md beside the token layer.");
+    const found = decisionsFile(root);
+    if (!found) problems.push("decide wrote no DECISIONS.md beside the token layer.");
     else {
-      const body = readFileSync28(file, "utf8");
+      const body = readFileSync29(join36(root, found), "utf8");
       if (!/^##\s+Unresolved\s*$/im.test(body)) {
         problems.push("DECISIONS.md has no `## Unresolved` section. Round 3 asks by name what is still undecided; write what the owner named, or `None named by the owner.`");
       }
@@ -6061,13 +6149,13 @@ function commandProblems(root, command) {
     const at = /^\s*mockup_at\s*:\s*(.+)$/im.exec(front)?.[1]?.trim().replace(/^["']|["']$/g, "") ?? "";
     if (/^approved/i.test(mockup)) {
       if (!at) problems.push(`${spec.path}: \`mockup_at:\` is empty. Record where the approved drawing is.`);
-      else if (!/^https?:/i.test(at) && !existsSync22(join35(root, at))) problems.push(`${spec.path}: \`mockup_at: ${at}\` does not exist.`);
+      else if (!/^https?:/i.test(at) && !existsSync22(join36(root, at))) problems.push(`${spec.path}: \`mockup_at: ${at}\` does not exist.`);
       else if (!/^https?:/i.test(at) && !at.startsWith(".jig/mockups/")) problems.push(`The drawing is at ${at}. A mockup lives in .jig/mockups/, outside what check scans and outside what ships.`);
     }
   }
   if (command === "critique") {
-    const dir = join35(root, ".jig", "critique");
-    const surfaces = existsSync22(dir) ? readdirSync15(dir).filter((s) => existsSync22(join35(dir, s, "screen.json")) || existsSync22(join35(dir, s, "code.json"))) : [];
+    const dir = join36(root, ".jig", "critique");
+    const surfaces = existsSync22(dir) ? readdirSync15(dir).filter((s) => existsSync22(join36(dir, s, "screen.json")) || existsSync22(join36(dir, s, "code.json"))) : [];
     for (const surface of surfaces) {
       const v = verifyVerdicts({ projectRoot: root, surface });
       if (v.ok && v.decisions.state !== "ran" && v.decisions.total > 0) {
@@ -6089,36 +6177,43 @@ function surfacePage(projectRoot, surface) {
   const declared = /^\s*surface\s*:\s*(.+)$/im.exec(front)?.[1]?.trim().replace(/^["']|["']$/g, "");
   const candidates = [declared, `${surface}.html`, declared ? `${declared.replace(/^\//, "")}.html` : void 0].filter((c) => !!c && /\.\w+$/.test(c) === (c === declared ? /\.\w+$/.test(c) : true));
   for (const candidate of candidates) {
-    if (candidate && existsSync22(join35(projectRoot, candidate))) return candidate;
+    if (candidate && existsSync22(join36(projectRoot, candidate))) return candidate;
   }
   return void 0;
 }
 function gate(opts) {
   const root = opts.projectRoot;
-  if (!existsSync22(join35(root, "jig.config.json")) && !existsSync22(join35(root, ".jig"))) {
+  if (!existsSync22(join36(root, "jig.config.json")) && !existsSync22(join36(root, ".jig"))) {
     return { block: false, reason: "" };
   }
   const command = lastJigCommand(opts.input.transcript_path);
-  const problems = command ? commandProblems(root, command).map((p) => `/jig ${command}: ${p}`) : [];
+  const waiting = command !== void 0 && ASKS_THE_OWNER.has(command) && asksOwner(lastAssistantText(opts.input.transcript_path));
+  const problems = command && !waiting ? commandProblems(root, command).map((p) => `/jig ${command}: ${p}`) : [];
   const selection = selectFiles(root, false);
-  const changedStyles = selection.mode === "changed" && selection.files.some((f) => isStyleBearing(f));
-  if (changedStyles) {
+  const changedUi = selection.mode === "changed" && selection.files.some((f) => isStyleBearing(f) || isReaderText(f));
+  if (changedUi) {
     const result = check({ projectRoot: root, homeDir: "", version: opts.version, all: false, ci: false });
     const errors = result.findings.filter((f) => f.bucket === "mechanical" && f.severity === "error");
-    if (errors.length > 0) {
-      const shown = errors.slice(0, 8).map((f) => `  ${f.ruleId} ${f.file}:${f.line} ${f.message}`);
+    const warnings = result.findings.filter((f) => f.severity === "warning");
+    const blocking = [...errors, ...warnings];
+    if (blocking.length > 0) {
+      const shown = blocking.slice(0, 8).map((f) => `  ${f.severity === "error" ? "error  " : "warning"} ${f.ruleId} ${f.file}:${f.line} ${f.message}`);
+      const counted = [
+        errors.length > 0 ? `${errors.length} mechanical error(s)` : "",
+        warnings.length > 0 ? `${warnings.length} warning(s)` : ""
+      ].filter(Boolean).join(" and ");
       problems.push(
-        `jig check: ${errors.length} mechanical error(s) in the files you changed. Fix every one, then run \`jig check\` again.
-` + shown.join("\n") + (errors.length > shown.length ? `
-  \u2026 and ${errors.length - shown.length} more` : "")
+        `jig check: ${counted} in the files you changed. Fix every one. A warning that is right as it stands can be waived on its own line with a comment reading \`jig-allow <ID>: <why>\`; an error cannot. Then run \`jig check\` again.
+` + shown.join("\n") + (blocking.length > shown.length ? `
+  \u2026 and ${blocking.length - shown.length} more` : "")
       );
     }
   }
-  const critiqueDir = join35(root, ".jig", "critique");
+  const critiqueDir = join36(root, ".jig", "critique");
   if (existsSync22(critiqueDir)) {
     for (const surface of readdirSync15(critiqueDir)) {
-      const dir = join35(critiqueDir, surface);
-      if (!existsSync22(join35(dir, "screen.json")) && !existsSync22(join35(dir, "code.json"))) continue;
+      const dir = join36(critiqueDir, surface);
+      if (!existsSync22(join36(dir, "screen.json")) && !existsSync22(join36(dir, "code.json"))) continue;
       const v = verifyVerdicts({ projectRoot: root, surface });
       if (!v.ok) {
         const shown = v.errors.slice(0, 6).map((e) => `  ${e}`);
@@ -6132,10 +6227,10 @@ function gate(opts) {
   }
   const session = opts.input.session_id ?? "unknown";
   const key = `${session}:${createHash2("sha256").update(problems.join("\n")).digest("hex").slice(0, 12)}`;
-  const stateFile = join35(root, ".jig", "gate.json");
+  const stateFile = join36(root, ".jig", "gate.json");
   let state = {};
   try {
-    state = JSON.parse(readFileSync28(stateFile, "utf8"));
+    state = JSON.parse(readFileSync29(stateFile, "utf8"));
   } catch {
   }
   if (problems.length === 0) {
@@ -6165,15 +6260,15 @@ ${problems.join("\n\n")}`
 }
 function save(file, state) {
   try {
-    mkdirSync8(join35(file, ".."), { recursive: true });
+    mkdirSync8(join36(file, ".."), { recursive: true });
     writeFileSync7(file, JSON.stringify(state), "utf8");
   } catch {
   }
 }
 
 // src/commands/seo.ts
-import { readFileSync as readFileSync29 } from "fs";
-import { join as join36 } from "path";
+import { readFileSync as readFileSync30 } from "fs";
+import { join as join37 } from "path";
 var SITEMAP_FILE = /(^|\/)sitemap(-index)?\.(xml|ts|js|mjs|tsx|jsx|rb|php|py)$/i;
 var ROBOTS_FILE = /(^|\/)robots\.(txt|ts|js|mjs|tsx|jsx)$/i;
 var ROUTE_IN_SITEMAP = /(?:<loc>\s*([^<\s]+)\s*<\/loc>)|(?:url\s*:\s*["'`]([^"'`]+)["'`])/gi;
@@ -6214,7 +6309,7 @@ function seo(opts) {
   for (const file of files) {
     let raw;
     try {
-      raw = readFileSync29(join36(root, file), "utf8");
+      raw = readFileSync30(join37(root, file), "utf8");
     } catch {
       continue;
     }
@@ -6270,7 +6365,7 @@ function seo(opts) {
 
 // src/index.ts
 var packageRoot = getPackageRoot();
-var { version } = JSON.parse(readFileSync30(join37(packageRoot, "package.json"), "utf8"));
+var { version } = JSON.parse(readFileSync31(join38(packageRoot, "package.json"), "utf8"));
 function warnIfUnpublishedPin() {
   if (isPublishedBuild(packageRoot)) return;
   console.warn(
@@ -6315,6 +6410,12 @@ program.command("install").description("Install Jig rules and the agent skill fi
       console.warn(result.warning);
       return;
     }
+    if (result.hookOnly) {
+      console.log(result.hookOnly);
+      if (result.stopHook === true) console.log("  + .claude/settings.json (Stop hook: jig gate blocks finishing while check or a critique fails)");
+      if (result.stopHook === false) console.log("  ! .claude/settings.json is not valid JSON \u2014 the Stop hook was not added. Fix the file and run install again.");
+      return;
+    }
     console.log(`Installed Jig v${version} for ${opts.agent} (${opts.scope} scope)`);
     warnIfUnpublishedPin();
     for (const f of result.written) console.log(`  + ${f}`);
@@ -6456,7 +6557,7 @@ program.command("probe").description("Print the render probe. With --save, read
 program.command("gate").description("Run by the Claude Code Stop hook: block stopping while check or a critique fails.").action(async () => {
   let input = {};
   try {
-    if (!process.stdin.isTTY) input = JSON.parse(readFileSync30(0, "utf8") || "{}");
+    if (!process.stdin.isTTY) input = JSON.parse(readFileSync31(0, "utf8") || "{}");
   } catch {
   }
   const cwd = input.cwd ?? process.cwd();
@@ -6495,7 +6596,7 @@ program.command("init").description("Set the project up to use Jig: a brand file
 });
 function resolveSurfaceMode(projectRoot) {
   try {
-    const config = JSON.parse(readFileSync30(join37(projectRoot, "jig.config.json"), "utf8"));
+    const config = JSON.parse(readFileSync31(join38(projectRoot, "jig.config.json"), "utf8"));
     const modes = [...new Set((config.surfaces ?? []).map((s) => s.mode).filter(Boolean))];
     return modes.length === 1 ? modes[0] : void 0;
   } catch {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jig-ui",
-  "version": "0.14.1",
+  "version": "0.15.0",
   "description": "A design system for coding agents. 130 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

@@ -759,8 +759,9 @@ 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
+not get to decide one is. Every warning is fixed, or waived on its own line with
+`jig-allow <ID>: <why>` (see `gate`); an explanation in your report is not a waiver.
+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
@@ -1162,9 +1163,10 @@ safe to run on the first day and on somebody else's codebase. It audits the whol
 which is what one file cannot: a route whose metadata says `noindex` sitting in
 the sitemap, two pages claiming the same title, a sitemap that lists nothing or
 lists paths instead of full URLs. It counts the pages it found, a dynamic route
-once, and whether a sitemap and a robots file exist; neither is a finding, since
-no rule asks for them and a project with no domain yet cannot write an honest
-sitemap. Do not invent one to clear a count.
+once and an endpoint (`rss.xml.ts`, `[id].txt.ts`, `api/`) not at all, since it
+serves no page. It also counts whether a sitemap and a robots file exist;
+neither is a finding, since no rule asks for them and a project with no domain
+yet cannot write an honest sitemap. Do not invent one to clear a count.
 
 It is not a phase. The per-page half belongs where the copy is decided and
 written — `spec` records whether a page is indexable and what it claims, `make`
@@ -1176,10 +1178,18 @@ positioning it had already dropped.
 ## 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
+`{{scripts_path}} gate` whenever you try to finish. If files you changed have a
+`check` error or warning, 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.
+
+A warning you are sure is right as it stands, because the detector guessed and the
+guess is wrong here, is waived on its own line or the line above, in the file's
+comment syntax: `jig-allow <ID>: <why>`. The reason is what the user reads, so write
+the case, not "intended". An error cannot be waived, a waiver with no reason waives
+nothing, and `check` prints every waiver it honoured. Waiving a warning to get past
+the gate, when the fix was available, is the failure the gate exists to catch. 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.
 

package/templates/SKILL.md.tmpl

@@ -14,18 +14,21 @@ cite the number when you follow or deliberately break one.
    b. `DECISIONS.md` exists beside the token files — `jig/DECISIONS.md` by
       default, or wherever `brand` in `{{config_file}}` puts them — and has
       substance: not empty, no `[TODO]` markers left in it, more than a few
-      lines. If it does not, run `{{command_prefix}}decide` and stop until it has
-      been written. Do not write it yourself from this task's prompt — it records
-      decisions the project has made, and a file you author alone records
-      decisions *you* have made, which is the opposite thing wearing the same
-      name.
+      lines. If it does not, stop and ask the user to run
+      `{{command_prefix}}decide`. The interview lives in that command, not in
+      this file: questions you make up from here are not `decide`, and neither
+      is a file written from their answers. Do not write it yourself from this
+      task's prompt — it records decisions the project has made, and a file you
+      author alone records decisions *you* have made, which is the opposite
+      thing wearing the same name.
 1. Load `{{rules_path}}/00-anti-patterns.md` and `{{rules_path}}/01-modes.md`.
 2. Determine the mode from `{{config_file}}`, or infer it using the procedure in
    `{{rules_path}}/01-modes.md` and state the inference in one line before building.
-3. **Building a page, feature or functionality?** Run it through
+3. **Building a page, feature or functionality?** It goes through
    `{{command_prefix}}spec` → `{{command_prefix}}mockup` (low fidelity) →
    `{{command_prefix}}make` (high fidelity) → `{{command_prefix}}critique`, one at a
-   time. Never design the whole product up front. Critique findings go back to
+   time, each one run by the user. The procedure for each step is in the command,
+   so ask for the step you need rather than doing it from this summary. Never design the whole product up front. Critique findings go back to
    `make`, then `critique` again, until clean or accepted by the user — then the
    next feature.
    **Building a screen rather than a single component?** Read `L-01 · Layout