Specen som kontrakt

Maskinöversatt från engelska — källa: spec-as-contract.md.

Implementeringsstatus: Designanteckning — implementerar Thoughtworks Spec-Driven Development (SDD)-mönstret anpassat till multi-agent-exekvering.

Byggt idag: placeringen wiki/specs/<feature>.md är en konvention som läsare kan följa; PRD:er bor redan i wiki/plans/<feature>-YYYY-MM-DD.md med rätt frontmatter-form.

Mål-tillägg: en Architect-agent som faktiskt producerar wiki/specs/<feature>.md från PRD:n. Ingen sådan agent finns idag; specer skrivs ad hoc som del av implementationsarbetet, eller hoppas över helt med editorn som läser PRD:n direkt. Test-writerns "kompilera Gherkin → misslyckande tester"-producent finns inte heller.

Naturligt språk är för imprecist för att koordinera flera agenter. PRD:er är för långa för att hålla i arbetsminnet vid varje steg. Specen är mellanartefakten: precis nog för att kompileras till tester, kort nog för att rymmas i varje agents kontext.

Vad "spec" betyder här

En wiki/specs/<feature>.md-fil med två sektioner:

1. Acceptanskriterier i Gherkin-stil-scenarier.
2. Koordinationsmetadata — filer som förväntas röras, modellroll förväntad i varje steg, alla explicita icke-mål.

Exempelskelett:

# Spec: Lab promotion banner

## Acceptance criteria

Feature: Best-trial banner on lab leaderboard
Scenario: Pinned trial is shown above the leaderboard
Given a service area with at least one completed lab trial
And one trial is pinned in ServiceAreaBestLabScenario
When the user opens /admin/optimization-lab/<id>
Then the BestTrialBanner is visible
And the banner shows the pinned trial's metrics

Scenario: Promote button is disabled for in-progress trials
Given a trial whose solution.status is solving_active
Then the Promote button is disabled
And hovering the button shows the tooltip "Trial still solving"

## Files expected to be touched

- apps/dashboard/src/pages/admin/optimization-lab/BestTrialBanner.tsx (new)
- apps/dashboard/src/pages/admin/optimization-lab/LeaderboardSection.tsx (modify)
- apps/dashboard/src/pages/admin/optimization-lab/**tests**/BestTrialBanner.test.tsx (new)
- e2e/lab-promotion-banner.spec.ts (new)

## Non-goals

- No backend changes (the resolver already returns the SA-best trial id).
- No copy changes outside the banner itself.
- No analytics events for banner views.

## Stage routing (overrides)

- editor: default
- verifier: default + perf-reviewer NOT required (no list resolver / loop touched)

Varför Gherkin

Tre skäl:

1. Tester är mekaniska från den. Test-writer-agenten kompilerar varje scenario till ett eller flera misslyckande testfall. Mappningen är direkt nog för att en regression i test-writern är lätt att upptäcka.
2. Granskare kan greppa det. "Hitta varje scenario som nämner BestTrialBanner" är ett grep bort. Spec i ren prosa kräver läsning.
3. Drift är auditerbar. När PRD:n säger en sak och specen säger en annan är diffen mellan PRD och spec den enda diskussionen att ha. Begrav inte oenigheten under prosa.

Single-source-of-truth-regeln

När specen är skriven är PRD:n inte längre källan till sanning för vad som ska byggas. Specen är.

Resonemang: agenter nedströms ser specen, inte PRD:n. Om PRD:n ändras mitt i implementationen och specen inte gör det, fortsätter editorn och verifiern bygga mot specen — och det är rätt, eftersom specen är vad de verifierade mot.

Om PRD:n ändras, regenerera specen. Behandla det som en ny funktionsskiva, på ett friskt eller uttryckligen återupptaget worktree, med en frisk testkörning. Ändra inte tyst mitt i flygningen.

Felmod: spec-drift

Den vanligaste felaktigheten: arkitekten producerar en spec som nämner ett beteende PRD:n inte specificerade, och editorn implementerar det glatt. Motåtgärder:

• Arkitekten måste lista ## Non-goals explicit. Om "X är utanför omfånget" står nedskrivet har editorn och granskar-agenterna en krok för att invända när X börjar smyga sig in.
• Verifiern diffar specen mot PRD:n:s frontmatter sources: och flaggar varje acceptanskriterium som inte spåras tillbaka. P2-fynd.
• Människor tittar på en specifik commit vid granskning: "spec"-commiten. Den commiten är det nya kontraktet; allt efter den är implementationsbrus.

Intag från Cursor-planer

Cursor-planer under .cursor/plans/ är utkast till planeringsartefakter, inte exekverbara kontrakt. Innan implementationen börjar måste orkestreraren:

1. Konvertera den accepterade planen till wiki/plans/<feature>-YYYY-MM-DD.md.
2. Bevara Cursor-plan-sökvägen i PRD:ns sources:-frontmatter.
3. Generera wiki/specs/<feature>.md från PRD:n.
4. Använd specen, inte Cursor-planen, som källan till sanning för tester och implementation.

Varför inte hoppa över specen och bara skriva tester?

Testat, fungerar inte. Ren test-first stöter på:

• Tester som passerar av fel skäl (övermockat, tautologiskt).
• Tester som inte fångar acceptans eftersom test-författaren inte helt förstod PRD:n.
• Acceptansscenarier begravda inuti testfiler där granskare inte läser dem.

Att placera acceptanskriterierna i ett Gherkin-block ger test-writern en checklista att kompilera från, och ger granskare något att greppa mot utan att dyka in i test-interna detaljer.

Korsreferenser

• PRD-till-PR-pipeline — var specen sitter i pipelinen (steg 2).
• Agentroller och modellroutning — Architect-agenten äger spec-författande; Test-writer kompilerar från den.
• Verifiering och bevis — dossiern bevisar att specens scenarier faktiskt går grönt i den deployade UI:n.
• Vision och mandat — åtagande (a): människor definierar vad; agenter exekverar hur. Specen är gränsen.