@event4u/agent-config 10.2.0 → 10.3.0

package/src/scripts/design_slop_rules.ts

@@ -17,6 +17,14 @@
  * dependency-free approach. Council 2026-06-28 assumed those libs were present;
  * for THIS package, pattern-based is the correct, frugal adaptation.
  *
+ * WHAT THE NEGATIVE FIXTURES ARE NOT: each rule ships one positive and one
+ * negative fixture, and the suite asserts both exist. That is a PRESENCE guard —
+ * "this regex stays quiet on one clean snippet crafted for it" — and it is NOT a
+ * false-positive RATE. Nineteen green negatives say nothing about how often a
+ * rule fires on clean UI it has never seen. Reading them as an FP measurement is
+ * the mistake that makes the registry look better-evidenced than it is; the rate
+ * is measured against the clean corpus under `internal/bench/corpora/`, not here.
+ *
  * Severity is a REBUTTABLE PRESUMPTION, never a hard block:
  *   P0 — objective failure (none here; those live in lint_design_quality)
  *   P1 — high-confidence tell (e.g. the side-stripe signature)
@@ -437,7 +445,7 @@ export const SLOP_RULES: SlopRule[] = [
     },
   },
   {
-    id: "slop-lock-shape",
+    id: "slop-v8-lock-shape",
     catalogId: "V8",
     severity: "P2",
     engines: ["css"],
@@ -464,27 +472,6 @@ export const SLOP_RULES: SlopRule[] = [
       return [];
     },
   },
-  {
-    id: "slop-lock-colour",
-    catalogId: "C6",
-    severity: "P3",
-    engines: ["css"],
-    description: "Colour Lock — multiple saturated accent hue families",
-    message: "Several accent hue families read as no single accent identity; lock one (C6 / Colour Lock).",
-    gated: (ctx) => ctx.has("colour lock", "color lock"),
-    detect: ({ content }) => {
-      const buckets = new Set<number>();
-      for (const pm of content.matchAll(/#([0-9a-f]{3}|[0-9a-f]{6})\b/gi)) {
-        const b = hueBucket("#" + (pm[1] ?? ""));
-        if (b !== null) buckets.add(b);
-      }
-      if (buckets.size >= 3) {
-        const idx = content.search(/#[0-9a-f]{3,6}\b/i);
-        return [{ line: lineOf(content, Math.max(0, idx)), snippet: `${buckets.size} distinct accent hue families` }];
-      }
-      return [];
-    },
-  },
   {
     id: "slop-l9-section-monotony",
     catalogId: "L9",
@@ -527,4 +514,145 @@ export const SLOP_RULES: SlopRule[] = [
       return [];
     },
   },
+  // -------------------------------------------------------------------------
+  // Catalog thresholds promoted to rules (road-to-design-detector-evidence
+  // Phase 3). Each entry below already published its number in
+  // docs/guidelines/design-antipatterns.md — the prose is the specification,
+  // nothing here is invented, and each was graded per rule against the clean
+  // corpus rather than as a batch.
+  // -------------------------------------------------------------------------
+  {
+    id: "slop-v4-over-rounded",
+    catalogId: "V4",
+    severity: "P3",
+    engines: ["css"],
+    description: "border-radius > 16px on an element declared under 200px wide",
+    message: "Heavy rounding on a small surface reads as scaffold-default; scale the radius to the element (V4).",
+    gated: (ctx) => ctx.has("pill", "fully rounded", "soft ui", "claymorphism"),
+    detect: ({ content }) =>
+      cssBlocks(content)
+        .filter((b) => {
+          // A pill (9999px / 50% / 999px) and a circle are deliberate shapes,
+          // not over-rounding — the tell is a mid-range radius on a small box.
+          const r = /border-radius\s*:\s*(\d+)px/i.exec(b.body);
+          if (!r?.[1]) return false;
+          const radius = parseInt(r[1], 10);
+          if (radius <= 16 || radius >= 100) return false;
+          // "small" must be declared in the same block; nothing here infers
+          // layout, because inferring it would need a cascade.
+          const size = /(?:^|[;{\s])(?:max-)?(?:width|height)\s*:\s*(\d+)px/i.exec(b.body);
+          return size?.[1] !== undefined && parseInt(size[1], 10) < 200;
+        })
+        .map((b) => ({ line: b.line, snippet: b.selector.slice(0, 80) })),
+  },
+  {
+    id: "slop-c3-dark-glow",
+    catalogId: "C3",
+    severity: "P2",
+    engines: ["css"],
+    description: "Saturated zero-offset glow (box-shadow / text-shadow) in a dark context",
+    message: "A neon glow on dark reads as gaming-UI default rather than a considered accent (C3).",
+    gated: (ctx) => ctx.has("glow", "neon", "cyberpunk", "gaming"),
+    detect: ({ content, lines }) => {
+      // The tell is dark-context-specific, so a file with no dark surface at all
+      // is out of scope — a glow on a light page is a different question.
+      const darkContext =
+        /prefers-color-scheme\s*:\s*dark/i.test(content) ||
+        /\.dark\b|\[data-theme=["']?dark/i.test(content) ||
+        /background(?:-color)?\s*:\s*#(?:0[0-9a-f]{5}|1[0-9a-f]{5}|000|111)\b/i.test(content);
+      if (!darkContext) return [];
+      const out: RawHit[] = [];
+      for (let i = 0; i < lines.length; i++) {
+        const l = lines[i] ?? "";
+        // zero-offset + real blur is the glow signature; an offset shadow is depth.
+        const m = /(?:box|text)-shadow\s*:\s*0\s+0\s+(\d+)px[^;]*?(#[0-9a-f]{3,8})/i.exec(l);
+        if (!m?.[1] || !m[2]) continue;
+        if (parseInt(m[1], 10) < 8) continue;
+        if (hueBucket(m[2]) === null) continue; // a neutral halo is not a neon accent
+        out.push({ line: i + 1, snippet: l.trim().slice(0, 80) });
+      }
+      return out;
+    },
+  },
+  {
+    id: "slop-t9-uppercase-body",
+    catalogId: "T9",
+    severity: "P3",
+    engines: ["css"],
+    description: "text-transform: uppercase applied to body-length text",
+    message: "All-caps destroys word-shape for sustained reading; reserve it for short labels (T9).",
+    gated: (ctx) => ctx.has("all caps", "all-caps", "uppercase display"),
+    detect: ({ content }) =>
+      cssBlocks(content)
+        // Short UI surfaces (labels, buttons, table headers, badges, eyebrows)
+        // are the legitimate home of uppercase and are excluded by selector.
+        .filter((b) => /\b(p|body|article|\.prose|\.body|\.content|\.copy|blockquote|li)\b/i.test(b.selector))
+        .filter((b) => !/label|button|\bth\b|badge|chip|tag|eyebrow|kicker|caption|nav/i.test(b.selector))
+        .filter((b) => /text-transform\s*:\s*uppercase/i.test(b.body))
+        .map((b) => ({ line: b.line, snippet: b.selector.slice(0, 80) })),
+  },
+  {
+    id: "slop-t10-wide-tracking-body",
+    catalogId: "T10",
+    severity: "P3",
+    engines: ["css"],
+    description: "letter-spacing above 0.05em on body-length text",
+    message: "Wide tracking slows sustained reading; it belongs to display type, not body (T10).",
+    gated: (ctx) => ctx.has("wide tracking", "letterspacing", "letter-spacing"),
+    detect: ({ content }) =>
+      cssBlocks(content)
+        .filter((b) => /\b(p|body|article|\.prose|\.body|\.content|\.copy|blockquote|li)\b/i.test(b.selector))
+        .filter((b) => !/label|button|\bth\b|badge|chip|tag|eyebrow|kicker|caption|nav|h[1-6]/i.test(b.selector))
+        .filter((b) => {
+          const em = /letter-spacing\s*:\s*(\d*\.?\d+)(em|rem)/i.exec(b.body);
+          if (em?.[1]) return parseFloat(em[1]) > 0.05;
+          const px = /letter-spacing\s*:\s*(\d*\.?\d+)px/i.exec(b.body);
+          return px?.[1] !== undefined && parseFloat(px[1]) > 0.8;
+        })
+        .map((b) => ({ line: b.line, snippet: b.selector.slice(0, 80) })),
+  },
+  {
+    id: "slop-m1-bounce-easing",
+    catalogId: "M1",
+    severity: "P2",
+    engines: ["css"],
+    description: "Bounce or elastic easing on a UI transition",
+    message: "Overshoot draws attention to the animation instead of the state change (M1).",
+    gated: (ctx) => ctx.has("bounce", "playful motion", "elastic"),
+    detect: ({ lines }) => {
+      const out: RawHit[] = [];
+      for (let i = 0; i < lines.length; i++) {
+        const l = lines[i] ?? "";
+        // Overshoot is decidable from the curve itself: a control point outside
+        // [0,1] on the output axis means the value passes its target and returns.
+        const cb = /cubic-bezier\(\s*[-\d.]+\s*,\s*(-?[\d.]+)\s*,\s*[-\d.]+\s*,\s*(-?[\d.]+)\s*\)/i.exec(l);
+        if (cb?.[1] !== undefined && cb[2] !== undefined) {
+          const y1 = parseFloat(cb[1]);
+          const y2 = parseFloat(cb[2]);
+          if (y1 < 0 || y1 > 1 || y2 < 0 || y2 > 1) {
+            out.push({ line: i + 1, snippet: l.trim().slice(0, 80) });
+            continue;
+          }
+        }
+        if (/(?:transition|animation)[^;]*\b(?:bounce|elastic|back(?:In|Out|InOut))\b/i.test(l)) {
+          out.push({ line: i + 1, snippet: l.trim().slice(0, 80) });
+        }
+      }
+      return out;
+    },
+  },
+  {
+    id: "slop-m3-img-hover-transform",
+    catalogId: "M3",
+    severity: "P3",
+    engines: ["css"],
+    description: "transform or filter animation on an <img> hover",
+    message: "Hover-scaling an image triggers composite plus decode and often shifts layout (M3).",
+    gated: (ctx) => ctx.has("image hover", "hover zoom", "ken burns"),
+    detect: ({ content }) =>
+      cssBlocks(content)
+        .filter((b) => /\bimg\b/i.test(b.selector) && /:hover|:focus-within/i.test(b.selector))
+        .filter((b) => /(?:^|[;{\s])(?:transform|filter)\s*:/i.test(b.body))
+        .map((b) => ({ line: b.line, snippet: b.selector.slice(0, 80) })),
+  },
 ];

package/src/scripts/dispatch_r2_reviewer.ts

@@ -642,7 +642,21 @@ function reviewerPrompt(args: {
  * Writing the hash of the prompt THIS dispatcher built makes the channel
  * attributable: the artefact now records which prompt produced it, so a review
  * run against a different prompt is distinguishable from one run against the
- * dispatcher's. `--verify` re-derives it from the same inputs and compares.
+ * dispatcher's.
+ *
+ * `--verify` / `--verify-current` do NOT re-derive it. {@link runVerify}
+ * re-derives `scope_hash`, `roadmap_hash` and `ac_hash` only — it re-computes
+ * the review's INPUTS from the current repo state, and the prompt is not one of
+ * them (it is not reconstructible from the repo; it is an artefact this
+ * dispatcher wrote). An earlier revision of this comment claimed otherwise for
+ * roughly a year, which is how the field came to be written, parsed, and
+ * compared to nothing.
+ *
+ * What compares it is `check_review_prompt_binding`, against the prompt package
+ * this dispatcher commits beside the artefact (`<slug>.review-input/prompt.md`,
+ * written below) — a different check with a different scope: corpus-wide rather
+ * than current-branch, because a committed prompt and its recorded hash are both
+ * immutable.
  *
  * It does not CLOSE the residual and is not sold as doing so: the same host that
  * authors a steered prompt could hash the steered text. The gain is an

package/src/scripts/hooks/ui_route_nudge_hook.ts

@@ -123,6 +123,45 @@ export function isUiWrite(event: ToolEvent): boolean {
     return isUiPath(event.file) || isUiTreePath(event.file);
 }
 
+/**
+ * The two handover shapes `design-fidelity` routes on a FILE rather than on a
+ * word: its `file_pattern: *design.html` and its
+ * `path_prefix: .claude/design-system/`. Reading one is the agent reaching
+ * rung 1 of the data-basis ladder before it writes.
+ *
+ * A SHARED PREDICATE, NOT A DECISION INPUT HERE. `decide` does not branch on
+ * it: the nudge's behaviour is unchanged by an artifact read, and the phase
+ * that introduced this states `nothing behavioural`. The one consumer is
+ * `report_consultation_rate`, which measures over transcripts. Keeping the
+ * predicate beside `isUiWrite` / `isConsultation` is what stops the analyzer
+ * and the nudge from classifying the same event differently.
+ *
+ * THIS IS A COPY OF THE RULE'S TRIGGERS, NOT A READ OF THEM — same honesty
+ * boundary the header states for `ui_surface.ts`: nothing here parses
+ * `src/rules/*.md`. `ui_route_nudge_artifact_read.test.ts` pins the two against
+ * the rule's own frontmatter so the copy cannot drift silently.
+ *
+ * **Not disjoint from `isConsultation` by construction** —
+ * `src/skills/design-review/references/design.html` satisfies both. Callers
+ * must evaluate the two independently rather than branching on the first hit;
+ * an early return on this predicate silently removes such an event from the
+ * consultation numerator.
+ *
+ * **Known over-count, not fixed here.** A `Grep` / `Glob` whose `path` argument
+ * happens to be the artifact satisfies this predicate although nothing was
+ * read — the same search-is-not-a-read class `isConsultation` was narrowed to
+ * exclude. It is not excluded here because `ToolEvent` carries no tool name,
+ * and adding one would change the shared shape `isConsultation` and `isUiWrite`
+ * are measured through, moving a published rate this branch does not own. The
+ * consequence is stated where it matters: the rate is a CEILING on
+ * read-before-write, and `report_consultation_rate`'s output says so.
+ */
+export function isArtifactRead(event: ToolEvent): boolean {
+    if (event.isWrite || !event.file) return false;
+    const normalized = event.file.replace(/\\/g, '/').toLowerCase();
+    return normalized.endsWith('design.html') || normalized.includes('.claude/design-system/');
+}
+
 export interface SessionState {
     consulted: boolean;
     nudges: number;
@@ -203,8 +242,22 @@ export function decide(
     return { state: { ...state, nudges: state.nudges + 1 }, warn: true };
 }
 
+/**
+ * Did anything worth persisting change?
+ *
+ * Enumerated per field rather than deep-compared. **A new field must be added
+ * here or it does not persist** — a review on this branch caught exactly that
+ * shape: two session fields were computed on every event and written on none,
+ * because the guard tested the two older fields by name. Those fields are gone
+ * (the measurement lives in the analyzer, one implementation instead of two),
+ * but the guard stays enumerated and this note stays with it.
+ */
+export function stateChanged(before: SessionState, after: SessionState): boolean {
+    return before.consulted !== after.consulted || before.nudges !== after.nudges;
+}
+
 export function nudgeReason(file: string): string {
-    return `Non-trivial UI write to ${file} with no design consultation this session. Run \`existing-ui-audit\` first, then the fe-design loop (brief → build → review). Skip only if this is ui-trivial: <=1 file, <=5 lines, no new component, no new state, no new dependency.`;
+    return `Non-trivial UI write to ${file} with no design consultation this session. Run \`existing-ui-audit\` first, then the fe-design loop (brief → inventory, if an artifact was provided → build → review). Skip only if this is ui-trivial: <=1 file, <=5 lines, no new component, no new state, no new dependency.`;
 }
 
 export function main(): number {
@@ -230,7 +283,7 @@ export function main(): number {
 
     const before = readState(root, session);
     const { state, warn } = decide(event, before);
-    if (state.consulted !== before.consulted || state.nudges !== before.nudges) {
+    if (stateChanged(before, state)) {
         writeState(root, session, state);
     }
     if (!warn) return EXIT_ALLOW;

package/src/scripts/lint_design_antipattern_parity.ts

@@ -0,0 +1,201 @@
+/**
+ * Gate: catalog ↔ slop-rule parity (road-to-design-detector-evidence Phase 1).
+ *
+ * `src/scripts/design_slop_rules.ts` states in its header that every rule cites
+ * its catalog id "so prose ↔ rule stay traceable". Nothing enforced that. The
+ * unit test validates the *shape* `/^[A-Z]+\d+$/` and never opens
+ * `docs/guidelines/design-antipatterns.md`, so a rule citing `Z99` passed, and a
+ * catalog entry could silently lose or gain a detector with no signal anywhere.
+ * The tree happened to be consistent; the defect was that consistency was
+ * unguarded, not that it was absent.
+ *
+ * This gate makes the claim true, in both directions:
+ *
+ *   A. every non-`Q*` catalog entry appears exactly once in § Detector status
+ *   B. every § Detector status row names a catalog entry that exists
+ *   C. the set of `backed` rows equals the registry's `catalogId` set
+ *   D. every status is one of the five allowed values
+ *   E. every non-`backed` row carries a reason
+ *
+ * `Q*` entries are out of scope by construction: they are objective floors owned
+ * by `lint_design_quality`, not aesthetic tells, and the status table says so.
+ *
+ * Pure core (`parityFindings`) takes both documents as text, so the failure
+ * paths are unit-testable without the filesystem. Exit 0 = clean, 1 = at least
+ * one finding.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { assertWatchlistResolves, DeadScopeError } from './_lib/scan_scope.js';
+
+const QUIET = process.argv.includes('--quiet');
+const _HERE = fileURLToPath(import.meta.url);
+const REPO = path.resolve(path.dirname(_HERE), '..', '..');
+const CATALOG = path.join(REPO, 'docs', 'guidelines', 'design-antipatterns.md');
+const REGISTRY = path.join(REPO, 'src', 'scripts', 'design_slop_rules.ts');
+
+/** The five statuses § Detector status may use. */
+export const STATUSES = ['backed', 'floor', 'judgment-only', 'deferred', 'candidate'] as const;
+export type Status = (typeof STATUSES)[number];
+
+export interface ParityFinding {
+    kind: string;
+    msg: string;
+}
+
+const ENTRY_ROW = /^\|\s*((?:V|C|T|L|M|CP)\d+)\s*\|/gm;
+const STATUS_ROW = /^\|\s*((?:V|C|T|L|M|CP)\d+)\s*\|\s*([a-z-]*)\s*\|([^|]*)\|/gm;
+const STATUS_SECTION = /^## Detector status$([\s\S]*?)(?=^## )/m;
+const CATALOG_ID = /^\s+catalogId:\s*"([A-Z]+\d+)"/gm;
+
+/** Catalog entry ids outside the § Detector status section. */
+export function catalogEntries(catalogMd: string): string[] {
+    const section = STATUS_SECTION.exec(catalogMd)?.[0] ?? '';
+    const outside = section === '' ? catalogMd : catalogMd.replace(section, '');
+    return [...outside.matchAll(ENTRY_ROW)].map((m) => m[1] as string);
+}
+
+/** `id -> {status, note}` parsed from the § Detector status table. */
+export function statusRows(catalogMd: string): Map<string, { status: string; note: string }> {
+    const section = STATUS_SECTION.exec(catalogMd)?.[1] ?? '';
+    const out = new Map<string, { status: string; note: string }>();
+    for (const m of section.matchAll(STATUS_ROW)) {
+        out.set(m[1] as string, { status: (m[2] ?? '').trim(), note: (m[3] ?? '').trim() });
+    }
+    return out;
+}
+
+/** `catalogId` values declared by the rule registry. */
+export function registryCatalogIds(registryTs: string): string[] {
+    return [...registryTs.matchAll(CATALOG_ID)].map((m) => m[1] as string);
+}
+
+/** Pure invariant check over both documents. */
+export function parityFindings(catalogMd: string, registryTs: string): ParityFinding[] {
+    const out: ParityFinding[] = [];
+
+    if (STATUS_SECTION.exec(catalogMd) === null) {
+        return [
+            {
+                kind: 'no-status-section',
+                msg: 'design-antipatterns.md has no `## Detector status` section — the parity claim has nothing to check against',
+            },
+        ];
+    }
+
+    const entries = catalogEntries(catalogMd);
+    const seen = new Set<string>();
+    for (const id of entries) {
+        if (seen.has(id)) out.push({ kind: 'duplicate-entry', msg: `${id}: appears more than once in the catalog tables` });
+        seen.add(id);
+    }
+
+    const rows = statusRows(catalogMd);
+
+    // A — every catalog entry is classified.
+    for (const id of seen) {
+        if (!rows.has(id)) {
+            out.push({ kind: 'unclassified', msg: `${id}: catalog entry missing from § Detector status` });
+        }
+    }
+    // B — every classified row names a real entry.
+    for (const id of rows.keys()) {
+        if (!seen.has(id)) {
+            out.push({ kind: 'orphan-status', msg: `${id}: § Detector status row names an entry that no catalog table defines` });
+        }
+    }
+    // D + E — status vocabulary and reasons.
+    for (const [id, row] of rows) {
+        if (!(STATUSES as readonly string[]).includes(row.status)) {
+            out.push({
+                kind: 'bad-status',
+                msg: `${id}: status '${row.status || '(empty)'}' is not one of ${STATUSES.join(', ')}`,
+            });
+            continue;
+        }
+        if (row.status !== 'backed' && row.note === '') {
+            out.push({ kind: 'missing-reason', msg: `${id}: status '${row.status}' carries no reason` });
+        }
+    }
+
+    // C — backed set equals the registry set, both directions.
+    const backed = new Set([...rows].filter(([, r]) => r.status === 'backed').map(([id]) => id));
+    const registry = new Set(registryCatalogIds(registryTs));
+    for (const id of backed) {
+        if (!registry.has(id)) {
+            out.push({ kind: 'backed-without-rule', msg: `${id}: marked backed but no registry rule declares that catalogId` });
+        }
+    }
+    for (const id of registry) {
+        if (!backed.has(id)) {
+            const known = rows.get(id);
+            out.push({
+                kind: 'rule-without-backed',
+                msg: known
+                    ? `${id}: a registry rule declares this catalogId but § Detector status marks it '${known.status}'`
+                    : `${id}: a registry rule declares this catalogId and no catalog entry carries it`,
+            });
+        }
+    }
+
+    return out;
+}
+
+function _print(s: string): void {
+    if (!QUIET) process.stdout.write(`${s}\n`);
+}
+
+export function main(): number {
+    try {
+        assertWatchlistResolves({
+            gate: 'lint_design_antipattern_parity',
+            candidates: [path.relative(REPO, CATALOG), path.relative(REPO, REGISTRY)],
+            repoRoot: REPO,
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            process.stderr.write(`❌  ${exc.message}\n`);
+            return 1;
+        }
+        throw exc;
+    }
+
+    const catalogMd = fs.readFileSync(CATALOG, 'utf-8');
+    const registryTs = fs.readFileSync(REGISTRY, 'utf-8');
+    const findings = parityFindings(catalogMd, registryTs);
+
+    const entries = catalogEntries(catalogMd).length;
+    const backed = [...statusRows(catalogMd).values()].filter((r) => r.status === 'backed').length;
+
+    if (findings.length === 0) {
+        _print(`✅  catalog ↔ rule parity OK — ${entries} entries classified, ${backed} detector-backed`);
+        return 0;
+    }
+    _print(`❌  catalog ↔ rule parity — ${findings.length} finding(s):`);
+    for (const f of findings) _print(`  - ${f.msg}`);
+    return 1;
+}
+
+function _isCliEntry(): boolean {
+    if (process.argv[1] === undefined) {
+        return false;
+    }
+    const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+    if (import.meta.url === argvUrl) {
+        return true;
+    }
+    try {
+        const here = fs.realpathSync(fileURLToPath(import.meta.url));
+        const argv = fs.realpathSync(path.resolve(process.argv[1]));
+        return here === argv;
+    } catch {
+        return false;
+    }
+}
+
+if (_isCliEntry()) {
+    process.exit(main());
+}