fix(scripts): harden layer-order parsing and clarify doc-refs skip message

Address two Greptile P2 maintainability findings on the new gates:

- check-layer-order.js: strip CSS comments before locating the @layer
  declaration so an `@layer` mention inside a file-header comment can't be
  mistaken for the real declaration (which would land the terminator search on
  a comment semicolon and silently extract the wrong layers). Added a
  regression test.
- check-doc-refs.js: the success line unconditionally read "token-count claims
  match" even when token-index.json was absent and the count check was skipped
  (a local pre-build run). Now it says the check was skipped in that case, so
  the OK message never implies validation that didn't run.

Full suite: 129 unit tests pass.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Dr51QC66ZtLKW6S2CWbiWi

Author: claude

scripts/check-doc-refs.js

@@ -164,8 +164,13 @@ if (countFindings.length > 0) {
 if (failed) process.exit(1);
 
 const tokenAllow = Object.values(allow).reduce((n, s) => n + s.size, 0);
+// Only claim the count check ran when token-index.json was actually present;
+// otherwise say it was skipped so a local pre-build run doesn't imply the
+// "N design tokens" prose was validated when it wasn't.
+const countNote = typeof tokenTotal === 'number'
+  ? 'token-count claims match'
+  : 'token-count check skipped (docs/token-index.json absent — run `npm run build`)';
 console.log(
   `check:doc-refs OK — ${docs.length} hand-written docs scanned, ` +
-  `all --sf-*/.sf- references live or allowlisted (${tokenAllow} allowlisted); ` +
-  'token-count claims match.',
+  `all --sf-*/.sf- references live or allowlisted (${tokenAllow} allowlisted); ${countNote}.`,
 );

scripts/check-layer-order.js

@@ -20,6 +20,7 @@
  */
 import fs from 'node:fs';
 import path from 'node:path';
+import { stripComments } from './lib/parse.js';
 
 const slashedRoot = process.env.SLASHED_ROOT?.trim();
 const ROOT = slashedRoot
@@ -41,7 +42,10 @@ const read = (rel) => {
 const layersIn = (text) => [...text.matchAll(/slashed\.([a-z]+)/g)].map((m) => m[1]);
 
 // ── Source of truth: the @layer declaration in core/layers.css ───────────────
-const layersCss = read('core/layers.css');
+// Strip CSS comments first so an `@layer` that appears inside a file-header
+// comment (e.g. "/* keep @layer in sync with architecture.md */") can't be
+// mistaken for the real declaration.
+const layersCss = stripComments(read('core/layers.css'));
 const declStart = layersCss.indexOf('@layer');
 if (declStart === -1) fail('no @layer declaration found in core/layers.css.');
 const declEnd = layersCss.indexOf(';', declStart);

tests/check-layer-order.test.js

@@ -67,6 +67,18 @@ describe('check-layer-order failure cases', () => {
     assert.equal(r.status, 1, 'expected exit 1 for a wrong specificity ladder');
     assert.match(r.stderr, /Specificity ladder .* not the reverse/);
   });
+
+  test('ignores an @layer mention inside a comment before the real declaration', () => {
+    // A file-header comment naming @layer must not be parsed as the declaration.
+    const dir = buildFixture();
+    fs.writeFileSync(
+      path.join(dir, 'core', 'layers.css'),
+      '/* keep @layer in sync with architecture.md; order matters */\n' +
+        `@layer\n${LAYERS.map((l) => `  slashed.${l}`).join(',\n')};\n`,
+    );
+    const r = runGate(dir);
+    assert.equal(r.status, 0, `comment @layer must be ignored:\n${r.stderr}`);
+  });
 });
 
 after(() => {