Audit Page

WHILE true:
  → Check pacing
  → Claim next page from audit queue
  → Open page, extract new links
  → Run checks (full or light based on pacing)
  → Save results
  → Mark complete in audit queue
  → Print progress
  → Loop (do NOT stop between pages)

Step 1 — Check Pacing

MODE=$(bash "${CLAUDE_PLUGIN_ROOT}/scripts/queue.sh" pacing "<audit_dir>" "<max_pages>")

If done or budget_exhausted, stop and output:

All audit queue pages processed. Run generate-report to create the final report.

Step 2 — Claim Next Page

URL=$(bash "${CLAUDE_PLUGIN_ROOT}/scripts/queue.sh" claim "<audit_dir>" audit "<agent_id>")

If returns EMPTY, the queue is done — stop.

Step 3 — Open Page and Re-extract Links

playwright-cli open "$URL"
playwright-cli eval "await new Promise(r => setTimeout(r, 2000))"

Re-extract links to catch JS-rendered content missed during discovery:

playwright-cli eval "JSON.stringify([...document.querySelectorAll('a[href]')].map(a=>({href:a.href,text:a.textContent.trim()})))"

Why re-extract during audit: Discovery runs playwright-cli eval which may miss links that only appear after full page render (e.g., React hydration, lazy-loaded sections, client-side routing). The 2-second wait in the audit phase gives JS more time to execute. Any new internal links go to the DISCOVERY queue (not audit) so they get properly crawled first:

bash "${CLAUDE_PLUGIN_ROOT}/scripts/queue.sh" add-discovery "<audit_dir>" "<new_url>" <depth> "<current_url>"

Step 4 — Viewports

Full mode: desktop (1920×1080), tablet (768×1024), mobile (375×812) Light mode: desktop (1920×1080) only

Why three viewports matter: Portugal has high mobile usage (~65% of web traffic). A site that works on desktop but breaks on mobile fails a majority of its users. Tablet testing catches layout breakpoints that neither desktop nor mobile reveal (e.g., navigation that collapses too early or too late). EU accessibility regulations (EAA, in force since June 2025) require content to be usable across device types.

For each viewport:

playwright-cli resize <width> <height>

# Screenshot (ALWAYS use the helper — NEVER use > redirect)
bash "${CLAUDE_PLUGIN_ROOT}/scripts/screenshot.sh" "<target_path>.png"

# Snapshot (text output — > redirect IS correct for snapshots)
playwright-cli snapshot > "<audit_dir>/snapshots/<slug>_<viewport>.md"

Step 5 — Run Checks

Every check must produce a finding with: status (pass/warn/fail), description, evidence, and justification for the rating.

ESSENTIAL CHECKS (always run, both full and light mode)

1. Cookie Consent & Tracking (GDPR/ePrivacy)

# Before any consent interaction:
playwright-cli eval "JSON.stringify({cookies: document.cookie, ls: Object.keys(localStorage)})"
playwright-cli network | grep -iE "hubspot|analytics|gtm|facebook|track|pixel|hotjar"

What to check:

• Are cookies set BEFORE user gives consent? (GDPR violation — Art. 5(3) ePrivacy Directive)
• Are tracking scripts (Google Analytics, HubSpot, Facebook Pixel) loaded before consent? (Same violation)
• Is there a cookie banner present? Is it GDPR-compliant (requires opt-in, not just "OK")?
• Does rejecting cookies actually stop tracking? (Test by rejecting, then re-checking)

Why this is critical: Under Portuguese GDPR enforcement (CNPD), setting tracking cookies before consent is a fineable offense. The CNPD has been increasingly active since 2023, issuing fines for exactly this pattern. A missing cookie banner on a commercial Portuguese website is a near-certain compliance gap.

Justification format: "FAIL: 3 tracking cookies (Google Analytics, HubSpot, Facebook) set before any consent interaction. This violates Art. 5(3) of the ePrivacy Directive as transposed into Portuguese law. Evidence: [screenshot reference]"

2. Meta Tags & SEO

playwright-cli eval "JSON.stringify({title:document.title, desc:document.querySelector('meta[name=description]')?.content, canonical:document.querySelector('link[rel=canonical]')?.href, ogTitle:document.querySelector('meta[property=\"og:title\"]')?.content, ogDesc:document.querySelector('meta[property=\"og:description\"]')?.content, ogImage:document.querySelector('meta[property=\"og:image\"]')?.content, lang:document.documentElement.lang, viewport:document.querySelector('meta[name=viewport]')?.content})"

What to check:

• Title: present, under 60 chars, contains brand name, unique per page
• Meta description: present, 120-160 chars, contains primary keywords
• Canonical URL: present, points to correct page (prevents duplicate content)
• Open Graph tags: title, description, image (for social sharing)
• Language attribute: <html lang="pt"> or appropriate variant
• Viewport meta: present with width=device-width (required for mobile rendering)

Why this matters: Missing meta tags directly impact SEO visibility. For Portuguese businesses, the lang attribute is especially important because it signals to Google which language results to show the page in. Missing OG tags mean shared links appear as blank cards on social media — a significant UX issue for marketing-driven sites.

Justification format: "WARN: Meta description is 42 characters ('Bem-vindo ao nosso site'). Best practice is 120-160 characters to maximize search result click-through. This description is too short to convey the page's value proposition in search results."

3. Console Errors

playwright-cli console warning

What to check:

• JavaScript errors (TypeError, ReferenceError, etc.) — indicate broken functionality
• Deprecation warnings — indicate technical debt and future breakage risk
• Mixed content warnings — indicate HTTP resources on HTTPS pages (security issue)
• CORS errors — indicate broken API calls or resource loading failures

Why this matters: Console errors on a production site indicate either broken functionality that affects users or security issues (mixed content). They're also a signal of code quality — a site with zero console errors demonstrates professional development practices.

Justification format: "FAIL: 2 JavaScript errors found. TypeError at main.js:142 breaks the contact form submission handler. Mixed content warning for http://cdn.example.pt/logo.png — loading HTTP resources on HTTPS page creates a security vulnerability and triggers browser warnings."

4. Link Validation

playwright-cli eval "JSON.stringify([...document.querySelectorAll('a[href]')].map(a=>({href:a.href,text:a.textContent.trim(),target:a.target})))"

What to check:

• Internal links: do they resolve? (Check against known pages from discovery)
• External links: do they have rel="noopener noreferrer" when target="_blank"? (Security best practice)
• Mailto/tel links: properly formatted?
• Anchor links: do target IDs exist on the page?
• Empty links: <a href="#"> or <a href=""> (usability issue)

Why this matters: Broken links directly impact user experience and SEO. Google penalizes pages with many broken links. For accessibility (WCAG 2.2 AA), links must have descriptive text — "click here" fails SC 2.4.4. External links without noopener on target="_blank" create a security vulnerability (reverse tabnapping).

5. Basic Accessibility

playwright-cli snapshot  # Check heading structure, ARIA, labels
playwright-cli eval "JSON.stringify({headings:[...document.querySelectorAll('h1,h2,h3,h4,h5,h6')].map(h=>({tag:h.tagName,text:h.textContent.trim()})), images_no_alt:[...document.querySelectorAll('img:not([alt])')].length, inputs_no_label:[...document.querySelectorAll('input:not([aria-label]):not([id])')].length, lang:document.documentElement.lang})"

What to check:

• Heading hierarchy: single H1, logical H2→H3→H4 order (no skipping levels)
• Images: all must have alt text (WCAG 2.2 SC 1.1.1)
• Form inputs: all must have associated labels (WCAG 2.2 SC 1.3.1)
• Language attribute: <html lang="pt"> must be present (WCAG 2.2 SC 3.1.1)
• Color contrast: text must meet 4.5:1 ratio (WCAG 2.2 SC 1.4.3)
• Focus visibility: interactive elements must show focus indicators (WCAG 2.2 SC 2.4.7)

Why this matters: The European Accessibility Act (EAA, EU 2019/882) became enforceable in June 2025. Commercial websites serving EU consumers must meet WCAG 2.2 AA. Non-compliance exposes the business to legal action. Portugal's national accessibility body (AMA) has been conducting audits of public and commercial sites.

Justification format: "FAIL: 5 images missing alt text. Under WCAG 2.2 SC 1.1.1 (Non-text Content) and the European Accessibility Act (in force since June 2025), all meaningful images must have descriptive alt text. This is a legal compliance gap for any commercial site serving EU consumers."

6. Desktop Screenshots

Handled in Step 4. Evidence for all other checks.

7. Link Extraction

Handled in Step 3. New links go to discovery queue.

FULL-MODE ONLY CHECKS (skipped in light mode)

8. Privacy Policy Check

What to check:

• Is there a link to a privacy policy? Where? (Footer, cookie banner, forms)
• Does the privacy policy mention: data controller identity, DPO contact, legal bases for processing, data subject rights (access, deletion, portability), cookie policy, third-party data sharing?
• Is it written in Portuguese? (Required for Portuguese consumers under consumer protection law)
• Is it up to date? (References to GDPR, not just pre-2018 legislation)

Why this matters: GDPR Art. 13-14 require specific information to be provided to data subjects. A missing or incomplete privacy policy is one of the most common GDPR violations cited by the CNPD.

9. Legal Information Check

What to check:

• Company identification: name, NIPC (tax ID), registered office address
• For e-commerce: terms of sale, return policy, payment methods, delivery info
• Contact information: email, phone, physical address
• Copyright notice

Why this matters: Portuguese Decree-Law 7/2004 (transposing EU E-Commerce Directive) requires all commercial websites to display company identification. Missing NIPC or registered address is a legal violation.

10. Livro de Reclamações Online

What to check:

• Is there a link to the Livro de Reclamações Online (https://www.livroreclamacoes.pt)?
• Is the link visible and accessible from every page? (Usually in footer)
• Does the link work?

Why this matters: Portuguese Decree-Law 156/2005 (updated by DL 74/2017) REQUIRES all businesses providing goods or services to Portuguese consumers to display a link to the electronic complaints book. This is a legal obligation, not a best practice. Non-compliance can result in fines from ASAE (food/economic authority).

11. E-Commerce Checks (if applicable)

What to check:

• Price display: includes VAT? (Required in Portugal)
• 14-day withdrawal right: clearly stated? (EU Consumer Rights Directive / DL 24/2014)
• Payment methods displayed before checkout
• Delivery costs visible before checkout
• Terms and conditions accessible before purchase

12. Content Quality Score

Score 7 dimensions (1-10 each) with detailed justification:

Justification format: "Originality: 4/10 — The services page contains generic descriptions that could apply to any agency ('We deliver creative solutions for your brand'). No case studies, specific methodologies, or unique value propositions are mentioned."

13. Spelling & Grammar

Check content in the page's language (Portuguese and/or English). Note: Portuguese spelling follows the 2009 Acordo Ortográfico — both pre- and post-agreement spellings may be valid.

14. Image Quality Check

What to check:

• All images have alt text (accessibility)
• Images use modern formats (WebP, AVIF) or optimized JPEG/PNG
• Images have width/height attributes (prevents layout shift — CLS metric)
• Images use lazy loading (loading="lazy") for below-fold content
• Image file sizes are reasonable (<500KB for photos, <100KB for icons)

15. Form Testing

What to check:

• Empty submit: does validation trigger? Are error messages clear and in Portuguese?
• Fill with test data: does submission work? What feedback is shown?
• Accessibility: are form fields labelled? Can the form be completed with keyboard only?
• Email field: does it validate email format?
• GDPR: is there a consent checkbox before data submission?

16-17. Navigation & Keyboard Accessibility

Tab through the page. Every interactive element must be reachable and show a visible focus indicator. The navigation must work on all viewports.

18-19. Network Tracking & Console Deep Dive

Deeper analysis of third-party scripts, tracking pixels, and error patterns across viewports.

20. Heuristic Evaluation (Nielsen's 10)

Score each heuristic 0-4 with specific evidence:

• H1: Visibility of system status
• H2: Match between system and real world
• H3: User control and freedom
• H4: Consistency and standards
• H5: Error prevention
• H6: Recognition rather than recall
• H7: Flexibility and efficiency
• H8: Aesthetic and minimalist design
• H9: Help users recognize and recover from errors
• H10: Help and documentation

Calculate weighted average (0–40 total, express as 0–10). Note the weakest heuristic with evidence.

21. Visual Design Scoring

Rate 5 dimensions (1-10 each) with specific evidence from the screenshots:

Calculate average (overall visual design score). Include a written summary: what visual impression does the site give a first-time visitor?

22. First Impression Test

Simulate a user landing on this page for the first time (5-second rule). Answer all five questions with evidence:

1. Purpose clarity: What does this company do? (Rate 1–10)
2. Action clarity: What should the user do next? Is the primary CTA obvious? (Rate 1–10)
3. Trust signals: Would a visitor trust this site? List trust signals present (reviews, certifications, team, address, HTTPS) and absent. (Rate 1–10)
4. Audience fit: Who is this page for? Is the target audience immediately clear? (Rate 1–10)
5. Value proposition: Is the unique benefit stated above the fold? (Rate 1–10)

Overall first impression score = average of the 5 ratings.

24. AI Content Detection

Assess whether the page content shows signs of being AI-generated without meaningful human editing. Look for the following signals:

playwright-cli eval "JSON.stringify({h1:document.querySelector('h1')?.textContent?.trim(), bodyText:document.body.innerText.substring(0,3000)})"

AI content signals to check:

• Formulaic sentence structure: sentences all follow the same pattern ("We are committed to X. Our team delivers Y. We pride ourselves on Z.")
• Lack of specifics: generic claims with no numbers, names, dates, or concrete evidence ("We help businesses grow")
• Same tone across all pages: copy on Home, About, Services, and Blog reads identically — no voice variation
• Weasel words and hedging: excessive use of "innovative", "comprehensive", "cutting-edge", "seamless", "state-of-the-art"
• Missing brand voice: content could belong to any company in the same industry
• No local/cultural signals: for Portuguese sites — no Portuguese idioms, no reference to local context, no localized examples
• Unusual coherence: paragraphs are each individually correct but don't build on each other

Output: Rate AI risk as low / medium / high with a confidence level and specific evidence strings quoted from the page. A high rating means the page likely contains unedited AI output.

Justification format: "AI Risk: HIGH (confidence: 85%) — The services page uses 4 of 7 AI signals. Example: 'We leverage cutting-edge technology to deliver seamless solutions for your business needs.' No specific services, tools, case studies, or client industries are mentioned. The same phrase structure ('We + verb + adjective + noun') repeats 8 times in the first paragraph."

25. Content Coherence Check

Verify that the page's content is internally consistent and matches its stated purpose:

playwright-cli eval "JSON.stringify({title:document.title, h1:document.querySelector('h1')?.textContent?.trim(), metaDesc:document.querySelector('meta[name=description]')?.content, h2s:[...document.querySelectorAll('h2')].map(h=>h.textContent.trim()), ogTitle:document.querySelector('meta[property=\"og:title\"]')?.content})"

What to check:

• Title ↔ H1 alignment: Do they cover the same topic? Mismatches (e.g., title says "Contact Us" but H1 says "Get Your Free Quote") confuse both users and search engines.
• Meta description ↔ page body: Does the meta description accurately represent the page's actual content? A description that doesn't match the body is misleading and hurts CTR.
• H1 ↔ body content: Is the H1 a promise the body content fulfils? A blog post titled "5 Ways to Improve Your SEO" must actually list 5 specific ways.
• Page purpose ↔ content: What is this page supposed to do (sell, inform, convert, support)? Does the actual content serve that purpose?
• Internal contradictions: Claims in one section that contradict another (e.g., "founded in 2010" in About vs "15 years of experience" in 2026 — that's consistent, but "over 500 clients" in hero and "our 12 clients" in a case studies section is not).
• OG metadata ↔ actual content: Is the social sharing title/description an accurate representation of what visitors will find?

Output: Pass / Warn / Fail with specific evidence for each sub-check.

Justification format: "FAIL — Title is 'Serviços de Marketing Digital' but H1 is 'Transforme o Seu Negócio'. The H1 gives no indication this is a marketing services page. Meta description says 'Especialistas em SEO, PPC e Social Media' but the page body only mentions 'marketing solutions' with no specific services listed — creating a mismatch between what search engines promise and what users find."

26. Web Vitals & Performance (full mode only)

Measure Core Web Vitals and page load timings. Run this after the page has been open for at least 3 seconds so LCP and CLS have time to finalize:

# Give LCP and CLS time to finalize
playwright-cli eval "await new Promise(r => setTimeout(r, 3000))"

# Collect all performance metrics in one eval
playwright-cli eval "JSON.stringify((() => {
  const nav = performance.getEntriesByType('navigation')[0];
  const paint = performance.getEntriesByType('paint');
  const fcp = paint.find(e => e.name === 'first-contentful-paint');
  const lcpEntries = performance.getEntriesByType('largest-contentful-paint');
  const lcp = lcpEntries.length ? lcpEntries[lcpEntries.length - 1] : null;
  let cls = 0;
  performance.getEntriesByType('layout-shift').forEach(e => { if (!e.hadRecentInput) cls += e.value; });
  const longTasks = performance.getEntriesByType('longtask');
  const tbt = longTasks.reduce((s, t) => s + Math.max(0, t.duration - 50), 0);
  const resources = performance.getEntriesByType('resource');
  return {
    ttfb:      nav ? Math.round(nav.responseStart - nav.requestStart) : null,
    fcp:       fcp ? Math.round(fcp.startTime) : null,
    lcp:       lcp ? Math.round(lcp.startTime) : null,
    cls:       Math.round(cls * 1000) / 1000,
    tbt:       Math.round(tbt),
    dcl:       nav ? Math.round(nav.domContentLoadedEventEnd - nav.startTime) : null,
    load:      nav ? Math.round(nav.loadEventEnd - nav.startTime) : null,
    lcp_el:    lcp ? lcp.element?.tagName : null,
    resources: resources.length,
    transfer_kb: nav ? Math.round(nav.transferSize / 1024) : null,
    slow_resources: resources.filter(r => r.duration > 1000).map(r => ({url: r.name.split('/').pop(), ms: Math.round(r.duration)}))
  };
})())"

Core Web Vitals thresholds (Google):

Pass/warn/fail mapping: Good → pass · Needs Improvement → warn · Poor → fail

What to note beyond thresholds:

• lcp_el: what element triggered LCP? An IMG is good; DIV with background-image is often a CLS risk. H1 means the hero image may not be loading.
• slow_resources: any individual resource taking >1000ms is a red flag (unoptimized image, slow third-party script)
• transfer_kb: total page weight. Over 3MB is a fail for mobile users; over 1MB is a warn.
• Images missing width/height cause CLS — cross-reference with image_quality_check
• Third-party scripts (analytics, chat widgets) inflating TBT — cross-reference with network_tracking check

Why this matters for Portuguese/EU sites: Google's CWV directly impact search rankings (Core Web Vitals became a ranking signal in 2021). Sites with poor LCP or CLS rank lower in Portuguese search results. The EAA (June 2025) also implies performance obligations — a page that takes 5s to load on mobile fails users with lower-end devices, disproportionately affecting accessibility.

Justification format: "LCP: FAIL (4200ms) — Page takes 4.2 seconds for the largest element (hero IMG) to render. Google's threshold is 2.5s for a 'Good' rating. This directly impacts search ranking. The hero image (1.2MB) is not optimised — consider WebP format and lazy loading for below-fold images. CLS: WARN (0.18) — Layout shifts likely caused by images without explicit width/height attributes (see image_quality_check findings). TBT: FAIL (780ms) — Two third-party scripts (HubSpot, Google Tag Manager) block the main thread for 780ms total, degrading interactivity."

27. Language & Tone Audit

(Handled by the language-tone skill — run separately or as part of the full audit workflow)

28. Secrets Scan

(Handled by the scan-secrets skill — run separately or as part of the full audit workflow)

23. Issue Evidence

For every 🔴 Critical and 🟠 High issue, capture a targeted screenshot of the specific element:

bash "${CLAUDE_PLUGIN_ROOT}/scripts/screenshot.sh" "<audit_dir>/screenshots/${AID}_${SLUG}_issue_<N>.png" "<element_ref>"

Step 6 — Save Results

Write results to results/page_<slug>.json:

{
  "task_id": "page_<slug>",
  "url": "<url>",
  "audit_mode": "full|light",
  "agent_id": "<agent_id>",
  "completed_at": "<ISO-8601>",
  "viewports_tested": ["desktop", "tablet", "mobile"],
  "checks": { ... },
  "issues": [ ... ],
  "scores": { ... }
}

Every issue MUST include:

• severity: 🔴 🟠 🟡 🔵
• category: which check found it
• description: clear, specific description of the problem
• justification: WHY this is an issue — reference the specific regulation, standard, or best practice
• recommendation: specific action to fix it
• evidence_screenshot: filename of the screenshot showing the issue

Step 7 — Mark Complete

bash "${CLAUDE_PLUGIN_ROOT}/scripts/queue.sh" complete "<audit_dir>" audit "<slug>"

Step 8 — Print Progress and Loop

bash "${CLAUDE_PLUGIN_ROOT}/scripts/queue.sh" status "<audit_dir>" both

Then immediately go back to Step 1. Do NOT stop between pages. Do NOT ask the user for permission to continue.

Enforcement Rules

1. ALWAYS use screenshot.sh — NEVER playwright-cli screenshot > file.png. The redirect saves a text log, not a PNG image.
2. ALWAYS check pacing before each page — the mode can change mid-audit as budget depletes.
3. NEVER stop between pages — the audit runs until the queue is empty or budget is exhausted.
4. EVERY page gets at least a light audit — no page should have zero coverage.
5. EVERY finding must be justified — cite the specific law, regulation, WCAG criterion, or best practice. Generic statements like "this could be improved" are not acceptable.
6. New links found during audit go to DISCOVERY queue — not directly to audit queue. They need link extraction first.