Add mechanical pre-scan for typeset and layout (#345)

* Add mechanical pre-scan for typeset and layout commands.

Introduce --scope filtering, layout/type rule scopes, DESIGN.md font-size validation, and pre-scan steps in the skill references so agents run detect before LLM judgment.

Fixes #149

Co-authored-by: Cursor <cursoragent@cursor.com>

* Add isolated sub-agent orchestration for typeset and layout pre-scans.

Run the mechanical detector and visual assessment in parallel sub-agents so deterministic findings cannot anchor LLM judgment, matching the critique pattern Paul requested on PR #345.

Co-authored-by: Cursor <cursoragent@cursor.com>

* Fix: reject bare --scope so detect never scans unscoped by mistake.

When --scope had no value, the CLI dropped the flag and ran a full scan instead of failing, which could silently use the wrong rule set during typeset/layout pre-scans.

Co-authored-by: Cursor <cursoragent@cursor.com>

* Fix: require both typeset and layout assessments in sub-agents.

Close a loophole where agents ran only the mechanical pre-scan inline by interpreting "running both" as permitting one inline assessment.

Co-authored-by: Cursor <cursoragent@cursor.com>

---------

Co-authored-by: Abdul Wahab <abdulwahab@Abduls-MacBook-Pro-2.local>
Co-authored-by: Cursor <cursoragent@cursor.com>

cli/engine/detect-antipatterns-browser.js

@@ -123,6 +123,7 @@ const ANTIPATTERNS = [
   {
     id: 'overused-font',
     category: 'slop',
+    scopes: ['type'],
     name: 'Overused font',
     description:
       'Inter, Roboto, Fraunces, Geist, Plus Jakarta Sans, and Space Grotesk are used on so many sites they no longer feel distinctive. Each new wave of AI-generated UIs converges on the same handful of faces. Choose a face that gives your interface personality.',
@@ -132,6 +133,7 @@ const ANTIPATTERNS = [
   {
     id: 'single-font',
     category: 'slop',
+    scopes: ['type'],
     name: 'Single font for everything',
     description:
       'Only one font family is used for the entire page. Pair a distinctive display font with a refined body font to create typographic hierarchy.',
@@ -141,6 +143,7 @@ const ANTIPATTERNS = [
   {
     id: 'flat-type-hierarchy',
     category: 'slop',
+    scopes: ['type'],
     name: 'Flat type hierarchy',
     description:
       'Font sizes are too close together — no clear visual hierarchy. Use fewer sizes with more contrast (aim for at least a 1.25 ratio between steps).',
@@ -177,6 +180,7 @@ const ANTIPATTERNS = [
   {
     id: 'nested-cards',
     category: 'slop',
+    scopes: ['layout'],
     name: 'Nested cards',
     description:
       'Cards inside cards create visual noise and excessive depth. Flatten the hierarchy — use spacing, typography, and dividers instead of nesting containers.',
@@ -186,6 +190,7 @@ const ANTIPATTERNS = [
   {
     id: 'monotonous-spacing',
     category: 'slop',
+    scopes: ['layout'],
     name: 'Monotonous spacing',
     description:
       'The same spacing value used everywhere — no rhythm, no variation. Use tight groupings for related items and generous separations between sections.',
@@ -213,6 +218,7 @@ const ANTIPATTERNS = [
   {
     id: 'icon-tile-stack',
     category: 'slop',
+    scopes: ['layout'],
     name: 'Icon tile stacked above heading',
     description:
       'A small rounded-square icon container above a heading is the universal AI feature-card template — every generator outputs this exact shape. Try a side-by-side icon and heading, or let the icon sit in flow without its own container.',
@@ -222,6 +228,7 @@ const ANTIPATTERNS = [
   {
     id: 'italic-serif-display',
     category: 'slop',
+    scopes: ['type'],
     name: 'Italic serif display headline',
     description:
       'Oversized italic serif (Fraunces, Recoleta, Playfair, Newsreader-italic) as the primary hero headline reads as taste in isolation but has become the universal AI-startup landing page hero. Set roman, or move to a non-serif display face. Editorial / magazine register may legitimately want this — judge by context.',
@@ -231,6 +238,7 @@ const ANTIPATTERNS = [
   {
     id: 'hero-eyebrow-chip',
     category: 'slop',
+    scopes: ['type'],
     name: 'Hero eyebrow / pill chip',
     description:
       'A tiny uppercase letter-spaced label sitting immediately above an oversized hero headline — or the same shape rendered as a pill chip — is now the default AI SaaS hero. Drop the eyebrow, integrate the kicker into the headline, or run it as a navigation breadcrumb instead.',
@@ -240,6 +248,7 @@ const ANTIPATTERNS = [
   {
     id: 'repeated-section-kickers',
     category: 'slop',
+    scopes: ['type'],
     severity: 'advisory',
     name: 'Repeated section kicker labels',
     description:
@@ -250,6 +259,7 @@ const ANTIPATTERNS = [
   {
     id: 'numbered-section-markers',
     category: 'slop',
+    scopes: ['layout'],
     severity: 'advisory',
     name: 'Numbered section markers (01 / 02 / 03)',
     description:
@@ -287,6 +297,7 @@ const ANTIPATTERNS = [
   {
     id: 'oversized-h1',
     category: 'slop',
+    scopes: ['type'],
     name: 'Oversized hero headline',
     description:
       'A full-sentence headline set at display size ends up dominating the viewport, leaving no room for anything else above the fold. A punchy one- or two-word headline at that size is fine — the problem is a long headline blown up too large. Set long headlines smaller, or tighten the copy.',
@@ -296,6 +307,7 @@ const ANTIPATTERNS = [
   {
     id: 'extreme-negative-tracking',
     category: 'slop',
+    scopes: ['type'],
     name: 'Crushed letter spacing',
     description:
       'Letter-spacing pulled tighter than the point where characters keep their own shapes costs legibility. Tighten display type optically, not destructively.',
@@ -341,6 +353,7 @@ const ANTIPATTERNS = [
   {
     id: 'line-length',
     category: 'quality',
+    scopes: ['type', 'layout'],
     name: 'Line length too long',
     description:
       'Text lines wider than ~80 characters are hard to read. The eye loses its place tracking back to the start of the next line. Add a max-width (65ch to 75ch) to text containers.',
@@ -350,6 +363,7 @@ const ANTIPATTERNS = [
   {
     id: 'cramped-padding',
     category: 'quality',
+    scopes: ['layout'],
     name: 'Cramped padding',
     description:
       'Text is too close to the edge of its container. Two shapes: (1) an element with its own text where the padding is too low for the font size, and (2) a wrapper with text-bearing children and near-zero padding against a visible boundary (border, outline, or non-transparent background) — children land flush against the boundary line. Add at least 8px (ideally 12–16px) of padding inside bordered, outlined, or colored containers.',
@@ -359,6 +373,7 @@ const ANTIPATTERNS = [
   {
     id: 'body-text-viewport-edge',
     category: 'quality',
+    scopes: ['layout'],
     name: 'Body text touching viewport edge',
     description:
       'Body paragraphs render flush against the left or right viewport edge with no container providing horizontal padding. Wrap content in a container with at least 16px (ideally 24-32px) of horizontal padding, or apply max-width with mx-auto.',
@@ -366,6 +381,7 @@ const ANTIPATTERNS = [
   {
     id: 'tight-leading',
     category: 'quality',
+    scopes: ['type'],
     name: 'Tight line height',
     description:
       'Line height below 1.3x the font size makes multi-line text hard to read. Use 1.5 to 1.7 for body text so lines have room to breathe.',
@@ -373,6 +389,7 @@ const ANTIPATTERNS = [
   {
     id: 'skipped-heading',
     category: 'quality',
+    scopes: ['type'],
     name: 'Skipped heading level',
     description:
       'Heading levels should not skip (e.g. h1 then h3 with no h2). Screen readers use heading hierarchy for navigation. Skipping levels breaks the document outline.',
@@ -380,6 +397,7 @@ const ANTIPATTERNS = [
   {
     id: 'justified-text',
     category: 'quality',
+    scopes: ['type'],
     name: 'Justified text',
     description:
       'Justified text without hyphenation creates uneven word spacing ("rivers of white"). Use text-align: left for body text, or enable hyphens: auto if you must justify.',
@@ -387,6 +405,7 @@ const ANTIPATTERNS = [
   {
     id: 'tiny-text',
     category: 'quality',
+    scopes: ['type'],
     name: 'Tiny body text',
     description:
       'Body text below 12px is hard to read, especially on high-DPI screens. Use at least 14px for body content, 16px is ideal.',
@@ -394,6 +413,7 @@ const ANTIPATTERNS = [
   {
     id: 'all-caps-body',
     category: 'quality',
+    scopes: ['type'],
     name: 'All-caps body text',
     description:
       'Long passages in uppercase are hard to read. We recognize words by shape (ascenders and descenders), which all-caps removes. Reserve uppercase for short labels and headings.',
@@ -403,6 +423,7 @@ const ANTIPATTERNS = [
   {
     id: 'wide-tracking',
     category: 'quality',
+    scopes: ['type'],
     name: 'Wide letter spacing on body text',
     description:
       'Letter spacing above 0.05em on body text disrupts natural character groupings and slows reading. Reserve wide tracking for short uppercase labels only.',
@@ -410,6 +431,7 @@ const ANTIPATTERNS = [
   {
     id: 'text-overflow',
     category: 'quality',
+    scopes: ['layout'],
     name: 'Content overflowing its container',
     description:
       'Content renders wider than its container, spilling out or forcing a horizontal scrollbar. Let text wrap, constrain widths, or give the region a deliberate scroll affordance.',
@@ -419,6 +441,7 @@ const ANTIPATTERNS = [
   {
     id: 'clipped-overflow-container',
     category: 'quality',
+    scopes: ['layout'],
     name: 'Positioned child clipped by overflow container',
     description:
       'A clipping container (overflow hidden or clip) wrapping an absolutely-positioned child cuts off tooltips, menus, and popovers that need to escape. Let the overflow be visible, or move the positioned layer out of the clip.',
@@ -428,6 +451,7 @@ const ANTIPATTERNS = [
   {
     id: 'design-system-font',
     category: 'quality',
+    scopes: ['type'],
     name: 'Font outside DESIGN.md',
     description:
       'A font is used that is not declared in DESIGN.md typography. Use the documented type system or update DESIGN.md if this is an intentional brand addition.',
@@ -454,6 +478,17 @@ const ANTIPATTERNS = [
     skillSection: 'Visual Details',
     skillGuideline: 'border radius outside the project design system',
   },
+  {
+    id: 'design-system-font-size',
+    category: 'quality',
+    severity: 'advisory',
+    scopes: ['type'],
+    name: 'Font size outside DESIGN.md',
+    description:
+      'A literal font-size is off the type ramp documented in DESIGN.md typography. Use a documented size step or update the design system if the new step is intentional.',
+    skillSection: 'Typography',
+    skillGuideline: 'font size outside the project design system',
+  },
 
   // ── Provider tells: opt-in via --gpt / --gemini (gated off by default) ──
   {