From da790de20d926bf15e0bbabe3046e88af35b6c97 Mon Sep 17 00:00:00 2001
From: Marcos Paulo <marcos.paulodasilva.mp@gmail.com>
Date: Sat, 5 Sep 2026 07:17:04 +0000
Subject: [PATCH] feat(gates): add token-gap escape hatch to check-tokens

The checker gave agents no legal way to be faithful. Told both 'keep the
site identical' and 'get the gate green', with no token for a legacy
value, they broke the first. Task 10 mapped 12px and 14px both to
var(--step-1) (15px). Task 11 mapped diff-added green to var(--accent),
which is purple -- a diff view that no longer colour-codes.

A marked line keeps its true value and waives its finding:

  /* token-gap: no --step-* covers 12px; owner design-system-keeper */
  font-size: 12px;

The reason is required; a bare marker is rejected. Marked values are
listed on every run, so this is a visible debt queue, not a mute button.
---
 .agents/scripts/check-tokens.mjs | 84 ++++++++++++++++++++++++--------
 1 file changed, 64 insertions(+), 20 deletions(-)

diff --git a/.agents/scripts/check-tokens.mjs b/.agents/scripts/check-tokens.mjs
index efc78f7..fea3e29 100755
--- a/.agents/scripts/check-tokens.mjs
+++ b/.agents/scripts/check-tokens.mjs
@@ -3,6 +3,23 @@
 // the token layer. A rule nobody checks is a suggestion — wire this into
 // `pnpm run verify`.
 //
+// ESCAPE HATCH — `token-gap:`. Some legacy values have no token yet, and only
+// `design-system-keeper` may add one. Without an escape, an agent told both
+// "keep the site identical" and "get the gate green" has to break one of them,
+// and tasks 10 and 11 both broke the first: `#e5eeeb` became `var(--paper)`,
+// diff-added green became `var(--accent)` purple. Substituting a near-miss
+// token is a silent redesign; it is worse than a raw value, because the raw
+// value is at least honest about what it is.
+//
+// So: mark the line, keep the true value, stay green.
+//
+//   /* token-gap: no --step-* covers 12px; owner design-system-keeper */
+//   font-size: 12px;
+//
+// Marked values are counted and listed on every run — they are a visible debt
+// queue, not a way to make the finding disappear. The marker needs a reason;
+// a bare `token-gap:` does not count.
+//
 // Usage: node .agents/scripts/check-tokens.mjs [srcDir]
 
 import { readdirSync, readFileSync, statSync } from 'node:fs';
@@ -24,35 +41,62 @@ const targets = ARGS.length
   : walk('src');
 
 const findings = [];
+const gaps = [];
+
+// A finding is waived when its own line, or the line above it, carries a
+// `token-gap:` marker with a reason after the colon.
+const MARKER = /token-gap:([^\n]*)/;
+// The reason is what is left after the marker once the comment terminator and
+// punctuation are stripped. `/* token-gap: */` is not a reason.
+const reason = (line) => {
+  const found = MARKER.exec(line ?? '');
+  if (!found) return null;
+  const text = found[1]
+    .replace(/\*\/\s*$/, '')
+    .replace(/[\s*/]+$/, '')
+    .trim();
+  return /[a-z0-9]/i.test(text) ? [null, text] : null;
+};
+const waiver = (lines, index) =>
+  reason(lines[index]) || (index > 0 ? reason(lines[index - 1]) : null);
 
 for (const path of targets) {
   if (!['.astro', '.css'].includes(extname(path))) continue;
   if (TOKEN_FILES.some((allowed) => path.endsWith(allowed))) continue;
 
-  readFileSync(path, 'utf8')
-    .split('\n')
-    .forEach((line, index) => {
-      const at = `${path}:${index + 1}`;
+  const lines = readFileSync(path, 'utf8').split('\n');
+  lines.forEach((line, index) => {
+    const at = `${path}:${index + 1}`;
+    const waived = waiver(lines, index);
+    const record = (finding) => {
+      if (waived) gaps.push(`${at}: ${finding.slice(at.length + 2)} [${waived[1]}]`);
+      else findings.push(finding);
+    };
 
-      // Raw hex — the drifted-palette failure mode this whole layer exists to stop.
-      const hex = line.match(/#[0-9a-fA-F]{3,8}\b/g);
-      if (hex) findings.push(`${at}: raw hex ${hex.join(', ')} — use a token from tokens.css`);
+    // Raw hex — the drifted-palette failure mode this whole layer exists to stop.
+    const hex = line.match(/#[0-9a-fA-F]{3,8}\b/g);
+    if (hex) record(`${at}: raw hex ${hex.join(', ')} — use a token from tokens.css`);
 
-      // rgb()/hsl() literals are the same problem wearing a different hat.
-      if (/\b(rgba?|hsla?)\(\s*\d/.test(line))
-        findings.push(`${at}: raw colour function — use a token`);
+    // rgb()/hsl() literals are the same problem wearing a different hat.
+    if (/\b(rgba?|hsla?)\(\s*\d/.test(line)) record(`${at}: raw colour function — use a token`);
 
-      // Hard-coded font sizes bypass the type scale.
-      const fontSize = line.match(/font-size:\s*\d+(\.\d+)?px/);
-      if (fontSize) findings.push(`${at}: hard-coded ${fontSize[0]} — use var(--step-*)`);
+    // Hard-coded font sizes bypass the type scale.
+    const fontSize = line.match(/font-size:\s*\d+(\.\d+)?px/);
+    if (fontSize) record(`${at}: hard-coded ${fontSize[0]} — use var(--step-*)`);
 
-      // Ad-hoc breakpoints are how sixteen of them accumulated last time.
-      const media = line.match(/@media[^{]*?\(\s*(?:max|min)-width:\s*(\d+px)/);
-      if (media && !ALLOWED_BREAKPOINTS.includes(media[1]))
-        findings.push(
-          `${at}: breakpoint ${media[1]} is not a named one (${ALLOWED_BREAKPOINTS.join(', ')})`,
-        );
-    });
+    // Ad-hoc breakpoints are how sixteen of them accumulated last time.
+    const media = line.match(/@media[^{]*?\(\s*(?:max|min)-width:\s*(\d+px)/);
+    if (media && !ALLOWED_BREAKPOINTS.includes(media[1]))
+      record(
+        `${at}: breakpoint ${media[1]} is not a named one (${ALLOWED_BREAKPOINTS.join(', ')})`,
+      );
+  });
+}
+
+if (gaps.length) {
+  console.log(`token check: ${gaps.length} marked token-gap(s) awaiting design-system-keeper:\n`);
+  gaps.forEach((gap) => console.log(`  ${gap}`));
+  console.log('');
 }
 
 if (findings.length) {