Zatwierdzanie i definicja zakończenia

Dwie niezależne osie

Treść i implementacja dojrzewają osobno. Stan approval opisuje przegląd treści, a status — dojrzałość techniczną artefaktu.

Stan	Znaczenie
draft	Strona jest opracowywana albo czeka na review. Może zawierać jawne znaczniki otwartej pracy.
reviewed	Human przeczytał stronę i nie ma uwag. To kandydat do wersji finalnej, nie wynik walidacji całego systemu.
approved	Human sprawdził stronę i zaakceptował ją na ten moment. Treść wolno stosować.

Stan techniczny draft, stable albo deprecated opisuje implementację. Reviewed nie zmienia niedokończonego komponentu w stable, a zielony test nie zatwierdza znaczenia reguły marki.

Review przyrostu

Po każdej nowej paczce reviewed:

1. uruchamiamy wszystkie twarde bramki właściwe dla zmiany;
2. sprawdzamy spójność całego zbioru reviewed i approved, także wcześniejszych stron oraz zależności;
3. poprawiamy ujawnione sprzeczności i zapisujemy jeden raport przyrostu;
4. powtarzalny błąd, który da się wykryć deterministycznie, zamieniamy w test lub walidator z przypadkiem poprawnym i celowym naruszeniem.

Zmiana zaakceptowanego sensu strony reviewed lub approved cofa ją do draft i ponownego przeglądu Human. Korekta techniczna, np. naprawa linku, wymaga kontroli zależności, ale nie ponownej akceptacji niezmienionego sensu. Następna paczka nie zamyka wcześniejszych sprzeczności samym nadaniem statusu.

Zapis reviewed_by: Human, reviewed_on i review_ref dokumentuje przegląd Human. Samoocena modelu nie wystarcza do nadania reviewed. Strona bez uwag redakcyjnych może nadal zależeć od niezakończonej implementacji — opisuje to stan techniczny i raport kontroli, a nie pozorna akceptacja całego systemu.

Reguły i dowody

Każda reguła lub hipoteza ma stabilny identyfikator, źródło, zakres, metodę sprawdzenia, kryterium wyniku i miejsce dowodu. Identyfikator, np. brand.name lub ui.button.token-binding, nie zależy od numeracji stron. Regułę opisujemy przy jej kontrakcie; raport wiąże ją z wynikiem kontroli.

Rodzaj	Kontrola	Granica dowodu
Nazwa i forma zwrotu	Skan kandydatów, potem ocena kontekstu	Nie dowodzi całej jakości tekstu
Twierdzenie produktowe	Właściwe OWU, wersja, miejsce i zgodność sensu	Nie zastępuje procesu dopasowania
Komponent i szablon	Tokeny, render, interakcje, dostępność i regresja	Nie potwierdza wdrożenia bez wydania konsumenta
Zaufanie i zrozumienie	Zadania odbiorców i jawna próba	Nie dowodzi przewagi rynkowej z małej próby
Ambicja biznesowa	Założenia oraz wyniki sprzedaży i kosztu obsługi	Nie gwarantuje realizacji celu

Jeden raport przyrostu obejmuje sprawdzoną wersję materiałów (commit lub hash), cały zbiór stron po przeglądzie Human, reguły, metody, datę, wyniki, ograniczenia i poprawki. „Nie sprawdzono” nie oznacza „zaliczono”. Ponowne użycie dowodu wymaga identycznego wejścia i wersji reguł. Najpierw stosujemy tanie kontrole deterministyczne, potem render, interakcje i ocenę kontekstu.

Raporty żyją poza publiczną narracją stron, w apps/design/docs/reviews/. Nie wymagamy osobnej sekcji dowodów na każdej stronie. Końcowy raport obejmuje cały katalog i jest wskazany przez catalog.json.reviewEvidence jako ścieżka względem repo. Bramka wymaga tego wskazania przy pnpm design:docs:review i pnpm design:docs:release (oraz zawsze, gdy klucz stoi w catalog.json); zwykłe design:docs:check go nie wymaga. Tabela Strona | SHA-256 zawiera link do każdej wymaganej strony i skrót pełnego źródła UTF-8. Bramka sprawdza istnienie raportu, kompletność tabeli, duplikaty i zgodność skrótów z bieżącymi plikami. Human ocenia metody, wyniki, ograniczenia i wnioski. Brak takiego raportu blokuje odbiór całości, nie samo nadanie stronie reviewed po przeglądzie Human.

Hierarchia bramek

Bramki techniczne tworzą jeden rosnący ciąg:

design:docs:check
  ⊂ design:check
      ⊂ design:audit

• pnpm design:docs:check uruchamia autotesty renderowania źródeł, walidatora katalogu i bramki logiki w szablonach, a następnie sprawdza strukturę stron, frontmatter, zależności, odsyłacze oraz to, że strony MDX i szablony .astro nie niosą logiki (template-logic).
• pnpm design:check zawiera te same kontrole dokumentacji, a ponadto sprawdza pin Playwrighta, granice biblioteki UI, testy i pokrycie validator-kit oraz UI, budowanie i kontrast tokenów, build i typy styleguide’u oraz walidatory statyczne, w tym kotwice wewnętrzne w wynikowym HTML.
• pnpm design:audit wykonuje pełne design:check i dodaje testy przeglądarkowe: dostępność axe, interakcje, wartości policzone tokenów i porównanie zrzutów.

Gotowość treści jest drugą osią:

• pnpm design:docs:review zawiera design:docs:check, po czym wymaga od wszystkich stron co najmniej statusu reviewed, zamkniętej pracy, wspólnego raportu z aktualnymi skrótami źródeł oraz stanu stable dla elementów technicznych i szablonów.
• pnpm design:docs:release zawiera design:docs:check, po czym wymaga approved nadanego przez Human, zamkniętej pracy, wspólnego raportu z aktualnymi skrótami źródeł oraz wymaganych stanów stable.

Nie uruchamiamy wszystkich komend po kolei. Dobieramy najwyższą potrzebną bramkę techniczną i właściwą bramkę gotowości:

Moment	Uruchom
Zmiana wyłącznie dokumentacji, bez wpływu na render	pnpm design:docs:check
Zmiana kodu, tokenów, komponentów, walidatorów lub styleguide’u	pnpm design:check
Zmiana wyglądu, zachowania albo dostępności	pnpm design:audit
Kandydat do review całego systemu	pnpm design:audit oraz pnpm design:docs:review
Wydanie po akceptacji Human	pnpm design:audit oraz pnpm design:docs:release

Dwie komendy w ostatnich dwóch wierszach sprawdzają różne osie: działanie systemu i gotowość treści. CI uruchamia pnpm design:audit dla każdej zmiany obszaru. Kontrola, którą można wykonać skryptem, nie może pozostać wyłącznie checklistą dla wykonawcy.

Zakończenie systemu

System jest gotowy do końcowego review, gdy wszystkie wymagane strony są co najmniej reviewed, nie ma otwartej pracy ani placeholderów, implementacje są gotowe, a dowody odpowiadają aktualnej wersji materiału. Review całości domyka brakujące approved i wskazuje poprawki obejmujące także wcześniejsze strony; status pojedynczej strony nie czeka na ten moment.

Wydanie systemu i migracja produktów są oddzielne. Brak migracji konsumenta pozostaje widoczny w rejestrze zastosowań, ale nie zmienia kontraktu wydanego DS.