Client Review Rubric & Editorial Critique Protocol

Client Review Rubric & Editorial Critique Protocol

Document Status: 🟢 Active True Specification (Editorial Governance & Review Protocol)
Authority: Editorial Quality, Client Governance & Automated Critique Engine
Primary Maintainer: SiteSwarm Architecture Council & Human Editorial Operators
Related Epics: #138 (Client Review Rubric & Critique Protocol), #37 (Client Business Intake & Scaffolding Blueprint), #34 (Client App Anatomy & Rendering), #101 (Capability Governance), #108 (Automated AST Linters)
Related Documents: CLIENT_BUSINESS_INTAKE_AND_SCAFFOLDING.md, CLIENT_APPLICATION_ANATOMY.md, CAPABILITY_PACKAGE_ANATOMY.md, ARCHITECTURAL_LINTERS.md, HIGH_LEVEL_DESIGN.md, docs/CAPABILITY_MANAGEMENT.md
Governing Packages: @siteswarm/critique (Headless In-Situ Feedback), @siteswarm/governance (CLI & Dedup Engine)

---

1. Strategic Context & Design Rationale

1.1 The Anti-Pattern of Conversational Ambiguity

In creative agency engagements and autonomous AI development workflows, client draft reviews frequently succumb to subjective, conversational critique traps:

• “Can we make it pop?”
• “It looks a bit AI-generated.”
• “Doesn’t feel right somehow.”
• “Make it look cleaner and more premium.”

These unstructured phrases inflict immediate engineering paralysis:

1. Subjective Ping-Pong: Developers or autonomous coding agents make arbitrary CSS adjustments (nudging padding, tweaking font weights, saturating accent colors) that fail to address the underlying editorial or structural defect.
2. Cognitive Drift & Fatigue: Client stakeholders struggle to articulate why a page feels inauthentic or cluttered, leading to endless review meetings and delayed project sign-offs.
3. Ghost Work & Reversion: AI agents repeatedly overwrite working layouts because the acceptance criteria for “editorial polish” were never codified into measurable invariants.

1.2 The “Red Pen” Editorial Critique Protocol

SiteSwarm replaces ambiguous conversational feedback with the Red Pen Editorial Critique Protocol: a rigorous, 4-axis evaluation framework paired with a calibrated 1-to-5 scoring scale.

flowchart TD
    subgraph FeedbackIngress["Editorial Ingress Channels"]
        Client["Human Client Stakeholder\n(Non-technical review)"]
        Operator["Agency Principal / Human Operator\n('Client Mirror' review)"]
        Overlay["@siteswarm/critique Overlay\n(In-situ visual pin & tag)"]
        Agent["Autonomous Critique Agent\n(AST & copy scan swarm)"]
    end

    subgraph EvaluationAxes["The 4-Axis 'Red Pen' Critique Matrix"]
        Axis1["Axis 1: Tone & Authenticity\n(Humble quiet authority vs. PR cheerleader hype)"]
        Axis2["Axis 2: Visual Restraint & Hierarchy\n(Typographic discipline & whitespace vs. badge carnival)"]
        Axis3["Axis 3: Content Genuineness\n(Factual evidence & code links vs. generic platitudes)"]
        Axis4["Axis 4: Information Architecture & Ergonomics\n(Effortless linear flow vs. accordion mazes)"]
    end

    subgraph ActionPipeline["Calibration & Remediation Pipeline"]
        ScoreCal["1-to-5 Scoring Calibration\n(Veto threshold: Score < 3)"]
        DedupEngine["@siteswarm/governance\nCritique Deduplication Engine"]
        Remediation["Worktree Task Execution\n(Targeted PR branch)"]
    end

    Client --> Axis1 & Axis2 & Axis3 & Axis4
    Operator --> Axis1 & Axis2 & Axis3 & Axis4
    Overlay --> Axis1 & Axis2 & Axis3 & Axis4
    Agent --> Axis1 & Axis2 & Axis3 & Axis4

    Axis1 & Axis2 & Axis3 & Axis4 --> ScoreCal
    ScoreCal --> DedupEngine
    DedupEngine --> Remediation

1.3 Tripartite Operational Utility

This rubric serves three distinct actors within the SiteSwarm ecosystem:

1. The Human Client & Business Stakeholder: Provides non-technical founders, marketing managers, and small business owners with targeted lenses to critique web copy and layouts without feeling intimidated by technical jargon.
2. The Agency Principal / Human Operator: Acts as the authoritative “Client Mirror” during internal quality assurance, auditing agent drafts against uncompromising trade standards before presenting work to the external client.
3. Automated Critique Agents & In-Situ Tools: Powers @siteswarm/critique in-situ browser pins, CLI inspection tools (pnpm swarm critique), and automated LLM-based AST audit swarms to generate deterministic, actionable pull request reviews.

---

2. The 4-Axis ‘Red Pen’ Critique Framework

Every page, section, component, and copy block must be evaluated against four distinct, non-overlapping axes.

                           Axis 1: Tone & Authenticity
                                      ▲
                                      │
                                      │
   Axis 4: IA & Ergonomics ───────────┼───────────► Axis 2: Visual Restraint
                                      │
                                      │
                                      ▼
                          Axis 3: Content Genuineness

---

2.1 Axis 1: Tone & Authenticity

Core Question: Does the voice reflect humble, quiet authority, or does it sound like synthetic corporate PR / cheerleader copy?

The Pathology: Synthetic “AI Slop” & Cheerleader Copy

Synthetic copy is obsessed with hyperbole, exclamation marks, and vacuous corporate optimism. It masks a lack of domain depth with inflated marketing jargon:

• Overuses buzzwords: “empower”, “revolutionize”, “game-changing”, “cutting-edge”, “seamlessly optimize”, “unleash”, “next-generation”.
• Relies on cheerleading exclamation marks (“Welcome to the future of baking!”).
• Speaks in detached, passive, third-person corporate euphemisms rather than grounded first-person craft.

The Ideal: Humble, Quiet Authority

Grounded copy speaks like a seasoned practitioner who has spent twenty years mastering their craft. It relies on factual descriptions, understated confidence, and plainspoken nouns and verbs:

• Describes concrete actions and physical realities: “We bake every morning starting at 3:30 AM using stone-ground organic wheat.”
• Explains constraints honestly rather than promising impossible perfection.
• Treats the reader like an intelligent peer, avoiding condescending hype or hollow flattery.

Heuristic Inspection Signals

Evaluation Signal	❌ Defect (Synthetic / Hype)	✅ Standard (Quiet Authority)
Superlatives	“The premier, world-class leader in HVAC solutions”	“Installing and maintaining commercial heat pumps in Tri-County since 1998”
Adverb Density	“Seamlessly, effortlessly, exponentially streamlines your workflow”	“Runs in 20ms at edge locations without visitor sessions”
Punctuation	Exclamation points in hero titles and feature cards (“Book now!”)	Confident periods or unpunctuated declarative phrases
Brand Perspective	Abstract corporate speak (“Our mission is client synergy”)	Direct trade commitment (“We repair European engines using OEM diagnostics”)

---

2.2 Axis 2: Visual Restraint & Typographic Hierarchy

Core Question: Is there typographic discipline and breathing room, or visual noise from badges, hairline borders, and conflicting font weights?

The Pathology: The “AI Template” Visual Carnival

Amateur and automated designs compensate for weak layout thinking by layering decorative artifacts:

• Pill Badge Overload: Stacking gratuitous pill badges above every headline ([✨ AI Powered], [🚀 Next-Gen Architecture], [🔥 10x Velocity]).
• Hairline Border Fatigue: Wrapping every paragraph, metric, card, and image in bright 1px solid rgba(255,255,255,0.15) or glowing neon gradient borders.
• Typographic Chaos: Combining three or four disparate font families, five font weights, uppercase tracking on random subheads, and inadequate line heights (leading-none on multi-line body copy).
• Claustrophobic Padding: Squeezing content into tight 8px or 12px boxes, starving elements of whitespace.

The Ideal: Typographic Discipline & Spatial Breathing Room

Elite editorial design relies on deliberate proportion, generous whitespace, and minimal decorative crutches:

• Maximum 2 Font Families: One expressive editorial display font (serif or modern grotesque) paired with an ultra-readable neutral system font for body text.
• Strict Typographic Scale: Clear, proportional scale ratios (e.g., Major Third or Perfect Fourth) with at least a 2.5x size differential between primary titles and body text.
• Generous Whitespace Rhythm: Consistent vertical rhythm using generous 32px, 48px, or 64px section gutters, allowing the eye to scan effortlessly.
• Purposeful Borders: Borders and dividing lines are utilized solely when semantic structural separation is mandatory, never as decorative vanity.

Heuristic Inspection Signals

Evaluation Signal	❌ Defect (Visual Noise)	✅ Standard (Restraint & Discipline)
Header Badges	Multiple multi-colored pill badges above hero H1	Single muted text eyebrow or zero badge
Borders & Dividers	Neon glow borders, drop shadows on every card container	Borderless cards using background tonal shifts or generous negative space
Font Weights	4+ weights (Light, Regular, Medium, SemiBold, Black) in one section	2 weights maximum per section (Regular body + Bold/Medium headings)
Whitespace Breathing	py-6 px-4 crammed hero sections	py-20 px-8 or py-28 spacious layout breathing room

---

2.3 Axis 3: Content Genuineness

Core Question: Are claims backed by real code links, factual architecture diagrams, and grounded case studies, or generic platitudes?

The Pathology: Unsubstantiated Platitudes & Stock Imagery

Generic websites treat content as an afterthought, filling sections with meaningless filler:

• Unverified Metrics: Inventing random round numbers without methodology (“99.9% customer happiness”, “10,000+ businesses transformed”).
• Generic Feature Grids: Six generic feature cards labeled “Fast”, “Secure”, “Reliable”, “Innovative”, “Customizable”, and “Scalable”.
• Stock Photography Cliches: Stock photos of smiling business models pointing at transparent glass boards or fake handshakes.
• Hollow Social Proof: Anonymous testimonials attributed to “John D., Tech CEO” without company links, verified project dates, or authentic project artifacts.

The Ideal: Grounded Architectural Reality & Tangible Artifacts

Authentic websites prove their assertions with tangible, verifiable artifacts:

• Verifiable Technical Contracts: Direct references to source code repositories, open-source capability packages (@siteswarm/lead-capture), live uptime monitors, or verified benchmark traces.
• Real Operational Mechanics: Step-by-step architectural diagrams showing how requests flow through edge nodes, cloudflare service bindings, and database schemas.
• Specific Case Studies: Real clients, named stakeholders, exact project timelines, before/after operational numbers, and linkable live deployments.
• Genuine Photography & Trade Assets: Actual workshop photos, raw code screenshots, genuine customer reviews, or honest blueprints.

Heuristic Inspection Signals

Evaluation Signal	❌ Defect (Unsubstantiated Fluff)	✅ Standard (Factual & Grounded)
Claims & Metrics	“100x efficiency improvement across enterprise stacks”	“Reduced edge TTFB from 340ms to 18ms by eliminating session KV”
Architecture Proof	Generic cloud icons connected with wavy arrows	Concrete Mermaid diagrams with verified package names and endpoints
Feature Descriptions	“Scalable cloud solutions built for tomorrow”	“Static Astro SSG pre-rendered at build time with Cloudflare Pages”
Testimonials	“Great service! Highly recommended! — Jane”	Linked client case studies with verified before/after Lighthouse scores

---

2.4 Axis 4: Information Architecture & Ergonomics

Core Question: Does the story flow effortlessly, or are visitors forced to click accordions and jump through navigational hurdles?

The Pathology: The “Accordion Trap” & Friction Labyrinth

Weak information architecture attempts to hide content complexity behind user-hostile interactive hurdles:

• The Accordion Trap: Hiding essential information (pricing tiers, service menus, core business hours, shipping policies) inside collapsed <details> accordions, forcing the visitor into an exhausting game of 20 clicks.
• Modal Interruption: Bombarding visitors with newsletter popups, cookie banners that obscure half the viewport, or multi-step wizard modals for simple contact inquiries.
• Broken Visual Scanning: Jumping between 1-column, 4-column, 2-column, and 5-column grids haphazardly, disrupting the natural downward reading scan.
• Hostile Mobile Ergonomics: Unreachable navigation targets, tiny tap targets (<44px), horizontal scroll blowouts, or fixed sticky headers that consume 40% of the mobile viewport.

The Ideal: Effortless, Linear Scannability

Superior information architecture delivers an unhindered narrative journey from page entry to conversion:

• Linear Narrative Progression: A clear, sequential story: (1) What this is, (2) The core trade difference, (3) Concrete evidence & offerings, (4) Transparent pricing/process, (5) Frictionless contact.
• Zero-Click Content Visibility: Crucial information is visible immediately on first read. Accordions are reserved strictly for secondary, optional FAQ edge cases.
• Frictionless Ergonomics: Prominent, single-step contact inputs (<form action="/api/leads">), tap-friendly phone links (tel:+1...), and thumb-zone navigation on mobile viewports.
• Instantaneous Edge Transitions: Sub-20ms edge document delivery and instant anchor scrolling without client-side hydration lockup.

Heuristic Inspection Signals

Evaluation Signal	❌ Defect (Friction Labyrinth)	✅ Standard (Effortless Flow)
Content Accessibility	Essential service specs hidden in 8 collapsed tabs	Flat, scannable typographic sections or clear tabular comparisons
Contact Flow	4-step modal wizard asking for 12 form fields	Simple inline lead capture form (Name, Phone/Email, Message)
Reading Scan	Haphazard layout shifts, nested card containers	Disciplined top-to-bottom vertical narrative flow
Mobile Tap Targets	Tiny links grouped closely together (<30px)	Minimum 44x44px accessible touch targets with clear hit states

---

3. Scoring & Calibration Scale (1 to 5)

Editorial reviews must assign a discrete score from 1 to 5 across each of the 4 axes. Fractional scores are not permitted during raw entry; an aggregate score is calculated as the arithmetic mean across all four axes.

┌────────────────────────────────────────────────────────────────────────┐
│  SCORE 1   │  Immediate Veto: Critical AI Slop, Visual Gimmicks, Broken│
├────────────┼───────────────────────────────────────────────────────────┤
│  SCORE 2   │  Distracting Clutter: Buzzwordy, Accordion Traps, Unproven│
├────────────┼───────────────────────────────────────────────────────────┤
│  SCORE 3   │  Acceptable Baseline: Technically Clean, Lacks Restraint  │
├────────────┼───────────────────────────────────────────────────────────┤
│  SCORE 4   │  Polished Professional: Grounded, Disciplined, Frictionless│
├────────────┼───────────────────────────────────────────────────────────┤
│  SCORE 5   │  Exceptional Editorial Benchmark: Humble Mastery & Depth  │
└────────────────────────────────────────────────────────────────────────┘

3.1 Detailed Calibration Definitions

Score 1: Immediate Veto (Blatant AI Slop / Critical Defect)

• Definition: Unusable in any professional context. Represents unchecked synthetic AI output or broken structural execution.
• Hallmarks: Glowing gradient borders, 3+ hype badges, cheerleading exclamation marks, broken mobile layouts, unverified stock metrics, or unreadable color contrast.
• Operational Consequence: Hard Gate Blocking. The pull request or draft is immediately vetoed. Zero deployment to staging or client preview is allowed.
• Remediation: Strip all decorative containers, scrap the copy, and restart from clean semantic HTML and the raw client discovery intake facts.

Score 2: Distracting Clutter (Unsubstantiated & Gimmicky)

• Definition: Contains real factual substance, but the user experience is burdened by decorative gimmicks, corporate buzzwords, and navigation traps.
• Hallmarks: Moderate buzzword density (“streamline”, “cutting-edge”), essential information hidden in accordions, unverified client claims, minor visual clutter (multiple competing border colors or pill tags).
• Operational Consequence: Revision Required. Allowed on developer preview branches, but rejected at staging gate.
• Remediation: Expand accordions into visible text, replace buzzwords with plain language, verify or remove unsupported metrics, and eliminate non-essential pill badges.

Score 3: Acceptable Baseline (Competent but Uninspired)

• Definition: Factually accurate, technically robust, and responsive, but lacks editorial character, typographic restraint, or crisp authority.
• Hallmarks: Standard corporate voice (clean but slightly dry or impersonal), conventional card grid layouts, accurate claims without direct links or deep evidence, no egregious badges or broken flows.
• Operational Consequence: Passable for Internal Review. Acceptable for preliminary client discovery check-ins, but requires editorial polish before final production launch.
• Remediation: Elevate typography (refine line-height and scale), inject authentic trade perspective, add concrete links/diagrams, and tighten copy.

Score 4: Polished Professional (Strong Restraint & Clear Voice)

• Definition: Meets high-tier agency standards. Exhibits clear authorial voice, crisp typographic hierarchy, substantiated facts, and frictionless navigation.
• Hallmarks: Humble, confident tone; maximum two font families with generous whitespace; claims backed by concrete data, diagrams, or links; frictionless linear flow; zero accordion traps for core content.
• Operational Consequence: Production Approved. Eligible for immediate client demonstration and production deployment.
• Remediation: Optional minor polish items noted for future iterations.

Score 5: Exceptional Editorial Benchmark (Masterclass in Craft)

• Definition: Golden reference benchmark across the entire SiteSwarm fleet. Exudes quiet mastery, architectural transparency, and effortless beauty.
• Hallmarks: Deeply compelling, understated prose that builds immediate trust; breathtaking typographic discipline; fully transparent architectural and operational disclosures; flawless ergonomics across all devices.
• Operational Consequence: Fleet Exemplar. Promoted as a living blueprint in monorepo documentation and showcased in case study repositories.

---

3.2 Comprehensive Calibration Matrix

Axis	Score 1 (Veto)	Score 2 (Clutter)	Score 3 (Baseline)	Score 4 (Professional)	Score 5 (Benchmark)
Axis 1: Tone & Authenticity	Cheerleader hype, exclamation marks, “revolutionary cutting-edge AI”	Corporate buzzwords (“seamlessly empower”, “synergy”), detached tone	Factual but generic; reads like a dry software manual	Confident, humble, direct; first-person craft, zero buzzwords	Captivating quiet mastery; deeply human, understated authority
Axis 2: Visual Restraint	Neon glows, 4+ pill badges, hairline borders everywhere, 4 fonts	Multiple pill badges, tight margins, 3 font weights, noisy card borders	Clean standard grid, but lacks generous whitespace; default card look	Strict 2-font system, generous 48px+ rhythm, zero vanity badges	Exquisite typographic scale, masterclass in negative space
Axis 3: Content Genuineness	Fake metrics (“100x speed”), stock photos of suits, hollow claims	Unsubstantiated claims (“trusted by leaders”), generic feature lists	Accurate high-level claims, but lacks proof links or diagrams	Concrete metrics (“18ms TTFB”), verified diagrams, real case studies	Complete architectural transparency; open-source links, live logs
Axis 4: IA & Ergonomics	Accordion maze for basic info, broken mobile layout, 5-step modal	Core pricing or services hidden in tabs; sticky banners blocking screen	Linear layout, but several clicks required for simple contact actions	Effortless linear flow; zero accordion traps; 1-click lead capture	Frictionless narrative; instant edge delivery; perfect touch zones

---

4. Concrete Pass vs. Fail Case Studies & Rubric Examples

The following case studies draw from real applications across the SiteSwarm monorepo: apps/bakery, apps/auto-repair, and apps/software-agency.

---

4.1 Axis 1 Case Study: Tone & Authenticity

• Subject: Artisan Sourdough Bakery (apps/bakery)
• Context: Hero headline and introductory opening paragraph.

❌ Fail Example (Scored: 1.0)

# Welcome to Artisan Crumb: Revolutionizing the Breakfast Paradigm! 🥐✨

At Artisan Crumb, we are unleashing a cutting-edge culinary revolution! Our world-class,
award-winning, next-generation artisanal sourdough technology seamlessly empowers your palate
with unmatched flavor synergies! We don't just bake bread—we disrupt the entire morning routine!
Experience breakfast perfection today!

Critique Notes:

• Pathology: Over-the-top cheerleader hype, exclamation marks on every sentence, absurd buzzwords (“culinary revolution”, “sourdough technology”, “palate synergies”, “disrupt”).
• Client Reaction: The client is a genuine baker with flour on their hands. This copy makes them look like an insecure tech grifter. Immediate Veto.

✅ Pass Example (Scored: 5.0)

# Bread baked every morning starting at 3:30 AM.

Three ingredients: organic stone-ground flour, filtered water, and sea salt.
Naturally fermented for 36 hours and baked on hearth stones.

Our bakery opens at 7:00 AM Tuesday through Sunday. When today's bake sells out,
the doors close until tomorrow morning.

Critique Notes:

• Why It Passes: Quiet, grounded authority. Concrete physical details (3:30 AM, three ingredients, 36-hour fermentation, hearth stones). Zero hype, zero exclamation points. Builds deep, instant trust.

---

4.2 Axis 2 Case Study: Visual Restraint & Typographic Hierarchy

• Subject: European Auto Repair Specialists (apps/auto-repair)
• Context: Core services overview section.

❌ Fail Example (Scored: 1.5)

<!-- Visual Noise: Badges, neon glowing borders, tight padding, conflicting fonts -->
<div class="py-6 px-4 font-sans">
  <div class="inline-flex items-center gap-2 px-3 py-1 rounded-full bg-gradient-to-r from-blue-500 to-purple-600 text-white text-xs font-black uppercase tracking-widest shadow-lg shadow-blue-500/30">
    <span>🔥 #1 GERMAN AUTO MASTERS</span>
  </div>
  <h2 class="text-3xl font-extrabold uppercase tracking-tight text-transparent bg-clip-text bg-gradient-to-r from-cyan-400 to-blue-600 mt-2">
    OUR PREMIER ELITE SERVICES
  </h2>
  <div class="grid grid-cols-1 md:grid-cols-3 gap-3 mt-4">
    <div class="p-3 rounded-xl border border-cyan-400/60 bg-slate-900 shadow-[0_0_15px_rgba(6,182,212,0.3)] font-mono">
      <h3 class="text-lg font-bold text-cyan-300">DIAGNOSTICS & TUNING</h3>
      <p class="text-xs text-slate-300 font-serif leading-tight mt-1">Full ECU scanning with hyper-accurate sensors.</p>
    </div>
  </div>
</div>

Critique Notes:

• Pathology: Gratuitous gradient pill badge (🔥 #1 GERMAN AUTO MASTERS), gradient text clip, cyan neon box shadow, conflicting font families (sans, mono, serif in one card), cramped p-3 and py-6 padding.
• Remediation: Strip all neon shadows and gradient badges. Adopt crisp monochromatic typography with generous spatial breathing room.

✅ Pass Example (Scored: 4.5)

<!-- Typographic Discipline: Clean hierarchy, muted borders, generous whitespace -->
<section class="py-24 px-8 max-w-6xl mx-auto font-sans">
  <p class="text-xs uppercase tracking-widest font-mono text-zinc-500 mb-3">
    Specialized Engineering Services
  </p>
  <h2 class="text-4xl font-normal tracking-tight text-zinc-900 mb-16">
    Factory-grade diagnostics and maintenance for BMW, Porsche, and Mercedes-Benz.
  </h2>

  <div class="grid grid-cols-1 md:grid-cols-3 gap-12 border-t border-zinc-200 pt-12">
    <div>
      <h3 class="text-lg font-medium text-zinc-900 mb-2">Factory Diagnostics</h3>
      <p class="text-sm text-zinc-600 leading-relaxed">
        Direct fault-code interrogation using dealer-level ISTA, PIWIS, and Xentry hardware systems.
      </p>
    </div>
  </div>
</section>

Critique Notes:

• Why It Passes: Monospace eyebrow provides technical credibility without screaming. Headline is understated and spacious. Divider line is subtle neutral zinc. Generous py-24 breathing room.

---

4.3 Axis 3 Case Study: Content Genuineness

• Subject: Custom Software Development Agency (apps/software-agency)
• Context: Technical architecture and performance guarantees page.

❌ Fail Example (Scored: 1.0)

### Why We Are Better
- **Unrivaled Scalability**: We empower your business with 99.999% cloud native uptime.
- **10x Velocity**: Our proprietary agile synergy accelerates time-to-market.
- **Enterprise Security**: Military-grade encryption protects every single asset.
- **Loved by Everyone**: Over 50,000 satisfied developers use our platform every minute.

Critique Notes:

• Pathology: Unsubstantiated platitudes. What cloud native? How is 99.999% measured? Who are the 50,000 developers? What is “military-grade” encryption? Pure fluff that immediately repels sophisticated engineering buyers.

✅ Pass Example (Scored: 5.0)

### Edge Performance & Technical Invariants

1. **Sub-20ms Edge Response Time**:
   All public marketing routes are pre-rendered statically (`output: "static"`) and deployed to
   Cloudflare Workers. Static assets are served directly from global edge caches with zero cold starts.
   Inspect our live [Synthetic TTFB Benchmark Report](/audits/paradigm-stress-test-report/).

2. **Zero-Session KV Elimination (ADR-0003)**:
   We omit Astro's default session KV binding (`SESSION`), preventing namespace sprawl and
   eliminating ephemeral preview quota exhaustion. State mutations flow through private service bindings.

3. **Automated AST Architectural Governance**:
   Every pull request is validated by `@siteswarm/governance` static linters (`pnpm run lint:arch`),
   guaranteeing zero cross-tenant imports and zero hardcoded runtime configs.

Critique Notes:

• Why It Passes: Deep, verifiable technical honesty. Links directly to living monorepo documents (ADR-0003, PARADIGM_STRESS_TEST_REPORT.md), quotes real architectural flags (output: "static"), and explains the concrete operational mechanisms.

---

4.4 Axis 4 Case Study: Information Architecture & Ergonomics

• Subject: Multi-Provider Medical & Therapy Practice
• Context: Insurance coverage and appointment scheduling flow.

❌ Fail Example (Scored: 1.5)

<!-- The Accordion Trap: Hiding critical patient information inside disclosure triangles -->
<div class="space-y-2">
  <details class="border p-2 rounded">
    <summary class="cursor-pointer font-bold">Do You Take Blue Cross Blue Shield?</summary>
    <p class="p-2 text-sm">Click here to download our 24-page PDF coverage matrix.</p>
  </details>
  <details class="border p-2 rounded">
    <summary class="cursor-pointer font-bold">What Are Your Emergency Hours?</summary>
    <p class="p-2 text-sm">Our on-call clinician can be reached by filling out our 4-step wizard modal.</p>
  </details>
  <button onclick="openModalStep1()" class="w-full py-2 bg-blue-600 text-white rounded">
    Launch Appointment Scheduling Wizard (Step 1 of 5)
  </button>
</div>

Critique Notes:

• Pathology: Anxious patients looking for emergency hours or insurance acceptance are trapped in accordions, forced to download PDFs, and confronted by a 5-step modal wizard. Severe ergonomic failure.

✅ Pass Example (Scored: 4.5)

<!-- Flat, Frictionless Ergonomics: Immediate clarity, zero clicks required -->
<section class="max-w-4xl mx-auto py-16 px-6">
  <!-- Prominent Emergency Header Bar -->
  <div class="bg-red-50 border-l-4 border-red-600 p-4 mb-12 flex justify-between items-center">
    <div>
      <p class="text-sm font-semibold text-red-900">Immediate Crisis Support (24/7)</p>
      <p class="text-xs text-red-700">Clinician on duty available by phone at all times.</p>
    </div>
    <a href="tel:5550192834" class="px-4 py-2 bg-red-600 text-white font-mono text-sm rounded hover:bg-red-700">
      Call (555) 019-2834
    </a>
  </div>

  <!-- Transparent Insurance Table -->
  <h2 class="text-2xl font-normal text-zinc-900 mb-6">In-Network Insurance Providers</h2>
  <div class="grid grid-cols-2 md:grid-cols-4 gap-4 mb-16">
    <div class="p-4 bg-zinc-50 rounded border border-zinc-200 text-sm font-medium text-zinc-800">
      Blue Cross Blue Shield
    </div>
    <div class="p-4 bg-zinc-50 rounded border border-zinc-200 text-sm font-medium text-zinc-800">
      Aetna Choice POS II
    </div>
    <div class="p-4 bg-zinc-50 rounded border border-zinc-200 text-sm font-medium text-zinc-800">
      United Healthcare
    </div>
    <div class="p-4 bg-zinc-50 rounded border border-zinc-200 text-sm font-medium text-zinc-800">
      Medicare Part B
    </div>
  </div>

  <!-- Single-Step Frictionless Contact -->
  <form action="/api/leads" method="POST" class="max-w-md space-y-4">
    <h3 class="text-lg font-medium text-zinc-900">Request an Initial Consultation</h3>
    <input type="text" name="name" placeholder="Your Name" required class="w-full p-3 border rounded text-sm" />
    <input type="tel" name="phone" placeholder="Phone Number" required class="w-full p-3 border rounded text-sm" />
    <button type="submit" class="w-full py-3 bg-zinc-900 text-white text-sm font-medium rounded">
      Send Appointment Request
    </button>
  </form>
</section>

Critique Notes:

• Why It Passes: Zero accordions. Emergency phone number is visible instantly with a one-tap tel: action. In-network insurance list is immediately readable in a clean flat grid. Appointment request requires exactly two fields and one submit button.

---

5. Integration with SiteSwarm Ecosystem & @siteswarm/critique

The Red Pen Rubric is not a passive PDF document; it is tightly coupled to the SiteSwarm tooling and package runtime.

sequenceDiagram
    autonumber
    actor Reviewer as Client or Human Operator
    participant Overlay as @siteswarm/critique (In-Situ UI)
    participant Storage as .swarm/critiques/<app>.json / Cloudflare KV
    participant CLI as pnpm swarm critique:dedup
    actor Agent as Autonomous AI Coding Agent

    Reviewer->>Overlay: Click component & select tag (e.g. "Too Buzzwordy", "Remove Badge")
    Reviewer->>Overlay: Type structured feedback & assign axis score
    Overlay->>Storage: POST /api/critique (CritiqueItem payload)
    Note over Storage: Critique records persisted with selector & text snippet
    Agent->>CLI: pnpm swarm critique --app <appId>
    CLI->>Storage: Query open critique records
    Storage-->>CLI: Return raw critique list
    CLI->>CLI: Deduplicate records by semantic key
    CLI-->>Agent: Output prioritized remediation worklist
    Agent->>Agent: Refactor Astro markup & copy to satisfy Rubric

5.1 Tag Mappings to the 4 Axes

The @siteswarm/critique package (packages/capabilities/critique/src/types.ts) provides standardized critique tags that map directly onto the 4 axes:

Standard Critique Tag	Primary Axis	Typical Score Impact	Typical Remediation
Too Buzzwordy	Axis 1 (Tone & Authenticity)	-1 to -2	Replace marketing superlatives with concrete craft and operational nouns.
Remove Badge	Axis 2 (Visual Restraint)	-1 to -2	Delete decorative pill badge or convert to subtle muted text eyebrow.
Needs Restraint	Axis 2 (Visual Restraint)	-1 to -2	Reduce border count, eliminate drop shadows/gradients, increase whitespace.
Copy Edit	Axis 3 (Content Genuineness)	-0.5 to -1	Add missing links, factual metrics, or verify case study details.
Formatting Issue	Axis 4 (IA & Ergonomics)	-1 to -2	Unpack accordion traps, fix broken mobile wrapping, enlarge tap targets.
Love This	All Axes (Positive Anchor)	+1 (Validates 4-5)	Preserves section as an untouchable anchor; agents must not alter this pattern.

5.2 Deduplication & Storage Architecture

Critique items logged through the browser overlay or CLI are stored either locally (.swarm/critiques/<appId>.json) or on Cloudflare Edge KV for remote staging instances.

The deduplication engine (packages/governance/src/cli/critique.ts) computes a normalized semantic key:

getCritiqueDeduplicationKey({
  selector: item.selector,
  componentName: item.componentName,
  tags: item.tags,
  comment: item.comment,
  textSnippet: item.textSnippet,
});

This prevents duplicate feedback loops when multiple reviewers flag the same glowing card or buzzword headline.

---

6. Standardized Critique Submission Templates

6.1 Template A: Human Operator & Client Review Ticket (Markdown)

Use this template when logging review issues in GitHub or preparing review summaries for clients.

### 📋 SiteSwarm Editorial Critique Ticket

**Application**: `apps/<client-slug>`
**Page / Route**: `/services` (or URL preview)
**Reviewer**: `Jane Doe (Client Stakeholder)`
**Target Component / Selector**: `section#hero > h1`

---

#### 🎯 4-Axis Evaluation & Scoring

| Evaluation Axis | Score (1-5) | Key Observations & Defects |
| :--- | :---: | :--- |
| **Axis 1: Tone & Authenticity** | `2` | Headline uses "revolutionizing breakfast" which sounds like tech PR rather than an artisan bakery. |
| **Axis 2: Visual Restraint** | `2` | Two competing gradient pill badges above the title. Neon border on bread cards. |
| **Axis 3: Content Genuineness** | `3` | Mentions "thousands of happy customers" without naming our local market or flour source. |
| **Axis 4: IA & Ergonomics** | `4` | Good linear flow, but the daily bread schedule is hidden inside an accordion. |
| **Composite Score** | **2.75 / 5.0** | **Status: Revision Required (Score < 3.5)** |

---

#### 🏷️ Selected Critique Tags
- [x] `Too Buzzwordy`
- [x] `Remove Badge`
- [x] `Needs Restraint`
- [ ] `Love This`
- [x] `Formatting Issue`
- [ ] `Copy Edit`

---

#### ✍️ Concrete Remediation Instructions
1. **Headline Rewrite**: Replace hero text with: *"Bread baked every morning starting at 3:30 AM."*
2. **Badge Removal**: Remove the `[🔥 #1 Sourdough]` badge completely.
3. **Card Restyle**: Remove `border-cyan-500` and drop shadow from `.product-card`. Use subtle `border-zinc-200`.
4. **Accordion Unpack**: Expand the hours and daily bread schedule into a permanent visible 2-column table.

---

6.2 Template B: @siteswarm/critique Automated In-Situ Agent Payload (JSON)

Conforms strictly to packages/capabilities/critique/src/schemas.ts and types.ts:

{
  "tenantId": "bakery",
  "environment": "staging",
  "url": "https://staging.artisanbread.com/menu",
  "componentName": "BreadSchedule",
  "selector": "main > section.schedule-section",
  "textSnippet": "Revolutionizing the breakfast landscape with cutting-edge sourdough technology...",
  "tags": [
    "Too Buzzwordy",
    "Remove Badge",
    "Formatting Issue"
  ],
  "comment": "Score: 2/5. Fails Axis 1 (hyperbolic PR voice) and Axis 4 (hours hidden inside collapsed <details> tag). Expand schedule table and replace copy with factual fermentation details.",
  "authorName": "editorial-critique-agent"
}

---

6.3 Template C: Monorepo Fleet Editorial Audit Scorecard

Used by the SiteSwarm Architecture Council to certify production readiness across client apps:

# 🏛️ Fleet Editorial Audit Scorecard: [App Name]

**Workspace**: `apps/<app-id>`
**Audit Date**: `2026-10-04`
**Auditor**: `SiteSwarm Editorial Quality Council`

| Page Route | Axis 1 (Tone) | Axis 2 (Visual) | Axis 3 (Content) | Axis 4 (Ergonomics) | Page Avg | Gate Status |
| :--- | :---: | :---: | :---: | :---: | :---: | :---: |
| `/` (Homepage) | 4.5 | 4.0 | 4.0 | 5.0 | **4.38** | 🟢 PASS |
| `/services` | 4.0 | 4.5 | 4.0 | 4.0 | **4.13** | 🟢 PASS |
| `/about` | 5.0 | 4.5 | 5.0 | 4.5 | **4.75** | 🟢 PASS |
| `/contact` | 4.0 | 4.0 | 4.5 | 5.0 | **4.38** | 🟢 PASS |

### Fleet Quality Gate Verification:
- [x] All page averages are $\ge 4.0$
- [x] Zero individual axis scores $< 3.0$
- [x] Zero unresolved `Too Buzzwordy` or `Remove Badge` critique records
- [x] Mobile responsiveness verified at 375px and 768px viewports
- **Final Verdict**: 🚀 **Approved for Client Production Deployment**

---

7. Operational Review Workflow & Governance Lifecycle

To guarantee that editorial standards are never compromised during high-velocity development, client applications must traverse four mandatory governance gates:

stateDiagram-v2
    [*] --> DraftInception: Intake checklist & dynamic scaffolding
    DraftInception --> AgentSelfAudit: Initial Astro authoring & copy generation

    state AgentSelfAudit {
        [*] --> CheckLinters: pnpm run lint:arch
        CheckLinters --> CheckRubric: AST & copy self-scan
        CheckRubric --> [*]
    }

    AgentSelfAudit --> StagingDeploy: Score >= 3 across all axes
    AgentSelfAudit --> DraftInception: Score < 3 (Self-remediation)

    StagingDeploy --> EditorialReview: In-Situ Review (@siteswarm/critique)

    state EditorialReview {
        HumanReview: Client & Operator Review
        TagFeedback: Tag "Too Buzzwordy" / "Remove Badge"
        DedupFeedback: pnpm swarm critique:dedup
        HumanReview --> TagFeedback
        TagFeedback --> DedupFeedback
    }

    EditorialReview --> ProductionApproved: Composite Score >= 4.0
    EditorialReview --> RemediationSprint: Composite Score < 4.0
    RemediationSprint --> EditorialReview: Targeted worktree fixes applied

    ProductionApproved --> [*]: Production Edge Deploy

The 4 Governance Gates

1. Gate 1: Pre-Commit Self-Audit (Developer & AI Agent):

   • Before requesting a human review, the authoring agent or developer must self-score all pages against the 4 axes.
   • Any score below 3.0 (e.g., leftover placeholder badges, ungrounded metrics) must be resolved immediately.

2. Gate 2: Staging Deployment Gate:

   • pnpm run lint:arch must pass with zero violations.
   • Core documentation synchronization (npx tsx apps/docs/scripts/sync-docs.ts) must complete without broken links.

3. Gate 3: In-Situ Editorial Pinning (@siteswarm/critique):

   • The human operator and client review the live staging build.
   • Feedback is logged via in-situ pins directly on the live DOM, populating standardized tags (Too Buzzwordy, Remove Badge, Needs Restraint).

4. Gate 4: Production Certification Gate:

   • No client website is deployed to production with an open critical critique ticket or an aggregate rubric score under 4.0 / 5.0.
   • Certified websites are cataloged as living blueprints for future client onboardings.