---
title: Audit conformité spec — SEO / IA / indexation (specification.website)
date: 2026-06-01
status: design-approved
---

# Audit conformité spec — SEO / IA / indexation

## Contexte

Le site Acieb v2 est orienté SEO/GEO (cf. `/llms.txt`, `/llms-full.txt`, `/services.md`,
`app/robots.ts`, `app/sitemap.ts`, `lib/json-ld.tsx`, headers `next.config.ts`). On veut
**vérifier que l'implémentation est conforme à la "checklist parfaite"** pour les moteurs de
recherche (Google), l'indexation, et les moteurs IA (ChatGPT/Perplexity/Gemini/Claude).

Référentiel canonique = **The Website Specification** (`specification.website`), exposé via le
MCP `specification-website` (tools : `get_categories`, `list_topics`, `get_checklist`,
`get_topic`, `search`). Chaque item a un statut : `required` (le contrat plateforme casse sans),
`recommended` (site moderne), `optional` (contextuel), `avoid` (obsolète/nuisible).

Sortie attendue : un **rapport de gaps** + un **plan d'attaque priorisé** (qui alimentera ensuite
un plan d'implémentation via writing-plans).

## Décisions (validées)

| Dimension | Choix |
|---|---|
| Périmètre | **10 catégories** : foundations, seo, accessibility, security, well-known, agent-readiness, performance, privacy, resilience, i18n (~128 topics) |
| Statuts | **required + recommended** (à satisfaire) + **avoid** (à NE PAS avoir, flag si présent) ; `optional` ignoré |
| Vérification | **Statique (code) + runtime (headers/HTML servis, routes spéciales) + Lighthouse (CWV)** |
| Exécution | **Fan-out parallèle, subagent max** : harness runtime isolé + 10 agents catégorie en // + synthèse |
| Livrable | Rapport de gaps + plan d'attaque priorisé (P0/P1/P2) |

## Architecture (vagues d'exécution)

```
Vague 0 — Harness runtime (1 sous-agent)
  pnpm build && pnpm start (prod, :3000)
  → capture artefacts dans .audit/ (gitignored) :
     • headers servis : curl -sI sur routes clés
     • HTML rendu : curl -s de pages représentatives (dump .html)
     • routes spéciales : /robots.txt /sitemap.xml /llms.txt /llms-full.txt
       /services.md /manifest.webmanifest /feed.xml /.well-known/* (security.txt…)
     • Lighthouse JSON (LCP/CLS/INP + scores seo/best-practices/a11y/perf)
       sur 3-4 URLs types dérivées de /sitemap.xml
     • linkinator (liens morts) → .audit/links.json
  → écrit .audit/manifest.json (liste des artefacts + URLs testées)

Vague 1 — Audits catégorie (10 sous-agents EN PARALLÈLE)
  un agent par catégorie. Chaque agent est AUTOSUFFISANT :
    1. interroge le MCP : get_checklist(category, status=required|recommended)
       + repère les items 'avoid' de sa catégorie
    2. lit le code de sa zone (cf. map ci-dessous)
    3. lit les artefacts runtime pertinents dans .audit/
    4. renvoie un JSON validé : liste de findings (schéma plus bas)
  (pas de dépendance entre agents ; ne dépendent que de .audit/ produit en vague 0)

Vague 2 — Synthèse (main thread)
  • merge des 10 sous-rapports
  • dédup des items transverses (canonical ∈ seo∩foundations ; lang ∈ foundations∩i18n ;
    headers ∈ security∩performance) → un verdict unique par slug
  • contrôle de couverture : chaque item de la checklist maître apparaît 1× exactement
  • tri sévérité×effort → rapport + plan d'attaque
```

## Map catégorie → zone du site

| Catégorie | Fichiers / routes à confronter |
|---|---|
| foundations | `app/layout.tsx` (generateMetadata, `<html lang>`), `app/**/page.tsx` (title/description/canonical), favicons (`app/icon*.tsx`, `apple-icon.tsx`, `manifest.ts`) |
| seo | metadata + canonical, `app/sitemap.ts`, `app/robots.ts`, `lib/json-ld.tsx`, OG/Twitter (`opengraph-image.tsx`, `twitter-image.tsx`), `app/feed.xml/` |
| agent-readiness | `app/llms.txt/`, `app/llms-full.txt/`, `app/services.md/`, robots (bots IA : GPTBot, ChatGPT-User, PerplexityBot, ClaudeBot…), JSON-LD, structure Hx du contenu MDX |
| well-known | `/.well-known/*` (security.txt, etc.), robots.txt, sitemap.xml servis |
| security | headers `next.config.ts` (CSP, HSTS, X-Content-Type-Options, X-Frame-Options/frame-ancestors, Referrer-Policy, Permissions-Policy) **vs** headers réellement servis (`.audit/`) |
| performance | Lighthouse CWV (`.audit/`), `next.config.ts` (images, cache-control), fonts, `app/globals.css` |
| accessibility | HTML rendu (`.audit/*.html` : landmarks, `alt`, labels, contraste structurel), `components/ui/`, `app/layout.tsx` |
| privacy | `lib/cookieconsent/`, `components/cookie-consent/`, gating OpenPanel/analytics sur consentement (`lib/analytics.ts`, `lib/openpanel.ts`) |
| resilience | `app/error.tsx`, `app/not-found.tsx`, comportement 404/500, dégradation JS-off |
| i18n | `<html lang>`, `content-language`, hreflang (site FR mono-locale → vérifier cohérence et absence de signaux contradictoires), formats de date |

## Schéma de finding (sortie de chaque sous-agent)

```json
{
  "category": "seo",
  "findings": [
    {
      "slug": "canonical-url",
      "title": "Canonical URL",
      "status": "required",                // required | recommended | avoid
      "verdict": "partial",                // pass | partial | fail | na
      "evidence": "app/layout.tsx:42 — alternates.canonical absent sur pages [category]",
      "gap": "Canonical non émis sur les routes dynamiques",
      "fix": "Ajouter alternates.canonical dans generateMetadata de app/[category]/page.tsx",
      "effort": "S"                        // S | M | L
    }
  ]
}
```

Règles de verdict :
- `pass` : item satisfait, **preuve obligatoire** (file:line, header servi, ou métrique LH).
- `partial` : partiellement (ex. présent sur certaines routes seulement).
- `fail` : absent/incorrect.
- `na` : non applicable (justifier — ex. item PWA hors scope d'un site vitrine).
- Pour un item `avoid` : `verdict=fail` signifie « l'anti-pattern EST présent » (à retirer).

## Synthèse & priorisation (plan d'attaque)

- **P0** — `required` en `fail`/`partial` (contrat cassé / indexation menacée).
- **P1** — `recommended` en `fail`/`partial` (manque pour "parfait").
- **P2** — `avoid` présents (nettoyage) + `required`/`recommended` déjà `pass` à durcir.
- Chaque entrée du plan : `slug` · sévérité · effort (S/M/L) · **fichier cible** · action concrète.

## Livrables

- Ce spec : `docs/superpowers/specs/2026-06-01-seo-ai-spec-audit-design.md`
- Rapport de gaps : `docs/seo-ai-audit/2026-06-01-report.md` (matrice par catégorie + preuves)
- Plan d'attaque : section du rapport + base du plan d'implémentation (writing-plans)
- Artefacts runtime : `.audit/` (gitignored, jetable)

## Vérification de l'audit lui-même

1. **Couverture** : `count(items rapport) == count(checklist maître MCP)` ; aucun slug dropped, aucun doublon non résolu.
2. **Preuves** : 100 % des `pass` ont une preuve ; 100 % des `fail/partial` ont fix + fichier.
3. **Spot-check** : re-vérifier manuellement 3 findings (1 required, 1 recommended, 1 avoid) contre code/runtime.

## Hors scope / risques

- `optional` non audités (choix).
- Lighthouse local ≠ field data (CrUX). On mesure le lab ; on le note comme tel.
- Si `pnpm build`/`start` échoue ou Lighthouse indisponible (`npx lighthouse`), la vague 0 dégrade : artefacts runtime partiels, items concernés marqués `na (non vérifiable runtime)` plutôt que faux `pass`.
- Pas de correctifs appliqués dans cet audit : sortie = constat + plan. L'implémentation passe par writing-plans puis le flow git standard (branche `fix/…` depuis `dev`).

## Prochaine étape

Invoquer **writing-plans** pour transformer le plan d'attaque priorisé en plan d'implémentation exécutable.