Verifiering och bevis

Maskinöversatt från engelska — källa: verification-and-evidence.md.

Implementeringsstatus: Designanteckning — anpassar Playwright Test Agents 1.56 (okt 2025) failure-dossier-mönster som teamets standard-bevisartefakt.

Byggt idag: docs/dossiers/<feature>/-mappar finns som en konvention; människor skapar dem för hand per funktion (t.ex. docs/dossiers/visit-chain-scope/README.md + numrerade PNG-skärmbilder). Playwright producerar redan trace.zip nativt när traces är aktiverade i apps/dashboard/playwright.config.ts.

Mål-tillägg: automatiserad buntare på be-agent-service/apps/server/src/pipeline/dossier.ts som fångar slut-tillståndets skärmbild, filtrerar konsoloutput, producerar summary.json mot schemat nedan, och zipar Playwright-tracen i samma mapp. En "ingen dossier, ingen merge"-grind upprätthållen av pipeline-runnern. Idag är grinden mänsklig disciplin.

Pipelinens kontrakt: ingen dossier, ingen merge. En grön CI-körning är nödvändig men inte tillräcklig. Tester kan passera medan det faktiska användarsynliga beteendet är trasigt (fel selektorer, mockad integration, konsolfel som sväljs). Dossiern är vad som bevisar att funktionen faktiskt renderades, i en riktig webbläsare, i ett tillstånd som matchar specen.

Denna sida definierar dossier-formatet och vad varje element bevisar.

Mappen docs/dossiers/<feature>/

Varje feature-branch levereras med docs/dossiers/<feature>/ ifylld av Verifier-agenten innan PR:n kan mergas (mål-tillstånd). Idag är dessa mappar handgjorda; buntaren som automatiserar layouten nedan är ett gap-listobjekt:

docs/dossiers/<feature>/
├── trace.zip          ← Playwright-trace (nätverk, DOM-snapshots, video, console)
├── screenshot.png     ← Slutligt renderat tillstånd för det primära acceptansscenariot
├── console.log        ← Webbläsarens konsoloutput (filtrerad till warnings + errors)
├── summary.json       ← Maskinläsbar: vilka scenarier passerade, tider, kostnader
└── README.md          ← En paragraf människosammanfattning som länkar till spec-scenarierna

Vad varje artefakt bevisar

trace.zip

Playwrights nativa trace-bunt. Fångar:

• Varje nätverksbegäran (URL, metod, status, response-body).
• DOM-snapshot vid varje interaktion.
• Konsolmeddelanden i realtid.
• Valfritt video av körningen.

Detta är artefakten en människa inspekterar när de inte litar på skärmbilden. Den kan spelas upp i Playwright Trace Viewer för att stega genom testet som det hände. Mestadels ett auditverktyg — agenter läser den inte; människor gör det, när något ser fel ut.

screenshot.png

Den enda bilden som bifogas notifieringen i den mänskliga kanalen när PR:n är klar. Fångad i slutet av det primära acceptansscenariot namngivet i specen. Upplösning: 1440×900 som standard, mörkt tema, inloggad testanvändare.

Detta är beviset människan godkänner. Den stående regeln: en Playwright-körning som inte producerar en skärmbild som visar att den implementerade funktionen faktiskt renderas är inte verifiering — det är ett no-error-smoketest (minnesregeln feedback_playwright_screenshot_proof.md).

console.log

Filtrerad till nivåerna warning och error. Fångar den klass av regression där en komponent "renderas" men kastar en stack trace i konsolen — vanligt när en genererad GraphQL-hook tyst misslyckas eller en hook-ordningsbugg inte kraschar men korruperar tillstånd.

Tom console.log är en positiv signal. Icke-tom är ett P1-fynd för granskaren.

summary.json

Strukturerat utfall:

{
  "feature": "lab-promotion-banner",
  "spec": "wiki/specs/lab-promotion-banner.md",
  "scenarios": [
    {
      "name": "Pinned trial is shown above the leaderboard",
      "status": "passed",
      "durationMs": 2143
    },
    {
      "name": "Promote button is disabled for in-progress trials",
      "status": "passed",
      "durationMs": 1876
    }
  ],
  "ci": {
    "type-check": "passed",
    "lint": "passed",
    "vitest": { "passed": 12, "failed": 0, "skipped": 0 },
    "playwright": { "passed": 2, "failed": 0, "skipped": 0 }
  },
  "tokenCost": {
    "architect": { "tokens": 12450, "usd": 0.45 },
    "test-writer": { "tokens": 8200, "usd": 0.07 },
    "editor": { "tokens": 38900, "usd": 0.32 },
    "verifier": { "tokens": 5100, "usd": 0.04 }
  },
  "elapsedSeconds": 1247,
  "throughput": { "featuresPerSecondPerToken": 1.2e-9 }
}

Konsumeras av:

• Merge-grinden (ci.* måste alla vara passed).
• Genomströmnings-loggern (skriver en rad till .compound-state/agent-service.db).
• Optimerings-matematikern (använder kostnad / genomströmning / felmått för att rotera modellroutning).

README.md

En paragraf för människor. Länkar till specen, listar scenarierna, bäddar in skärmbilden. Detta är vad som postas till Telegram via interface-agent när PR:n är klar.

Vad dossiern inte är

• Inte en ersättning för specen. Specen definierar vad dossiern måste bevisa.
• Inte en ersättning för kodgranskning. Granskar-underagenter läser diffen; dossiern verifierar beteende.
• Inte ett snapshot-test. Snapshot-tester fryser tillfällig rendering; dossiern fångar avsiktligt beteende mot ett typat kontrakt.
• Inte valfri. En PR utan dossier är en PR utan bevis — orkestreraren vägrar köa den för auto-merge.

Mockade kontra verkliga miljöbevis

Vissa funktioner, särskilt optimerings- och Timefold-arbetsflöden, kan inte köra fulla riktiga lösningar i varje CI-körning. Dossiern måste separera bevistyper explicit:

• Deterministiska bevis: enhets-, integrations- och webbläsartester med mockade externa system. Dessa krävs i CI.
• Verkliga miljö-smoke-bevis: korta begränsade körningar mot riktiga tjänster när credentials och latensbudget är tillgängliga. Dessa registreras i summary.json som valfria smoke-kontroller, inte som en ersättning för deterministiska tester.

För solver-baserade funktioner måste specen ange vilka acceptansscenarier som bevisas av deterministiska mocks och vilka som bevisas av korta real-solve-smoke-kommandon.

Felfall dossiern fångar

Korsreferenser

• PRD-till-PR-pipeline — steg 5–6 producerar dossiern.
• Specen som kontrakt — vad dossiern verifierar mot.
• Granskningsåterkoppling — hur en icke-tom console.log blir ett P1-fynd.
• Genomströmning och affärssignaler — summary.json.tokenCost matar genomströmnings-loggern.
• Playwright e2e-katalog — befintliga tester detta mönster komponerar ovanpå.