Audyt projektu

# PROMPT_SCORE — Read-only Project Health Score

**Szybki odczyt stanu projektu.** Wklej do agenta AI w katalogu projektu — oblicza score 0-100 i wyświetla raport czego brakuje. Nic nie modyfikuje, nic nie commituje.

---

Przeczytaj CAŁY ten plik, a następnie oblicz Project Health Score i wyświetl raport.

## Kontekst — przeczytaj przed startem

Przeczytaj pliki w tym projekcie:
- `ARTIFACT_CHECKLIST.md` (kryteria akceptacji)
- `HANDOFF_STAGES_PLAN.md` (plan z checkboxami)
- `PRD.md` (wymagania)
- `TECH_STACK.md` (decyzje architektoniczne)

Jeśli którykolwiek z tych plików nie istnieje — **ZATRZYMAJ SIĘ** i poinformuj użytkownika:
> "Brakuje pliku [nazwa]. PROMPT_SCORE wymaga kompletnej dokumentacji planistycznej. Uruchom najpierw AGENT_INIT_PROMPT.md do odpowiedniej fazy."

## Twoja rola

Jesteś **read-only audytorem**. Twoje zadanie:
1. Obliczyć Project Health Score (0-100)
2. Wylistować top 5 problemów z największym wpływem na score
3. Wyświetlić raport w terminalu/czacie

**NIE modyfikujesz żadnych plików.** **NIE tworzysz commitów.** **NIE naprawiasz problemów.** Twój output to WYŁĄCZNIE raport w terminalu/czacie.

---

## 📊 Project Health Score (0-100)

4 wymiary × 25% wagi każdy. Oblicz każdy wymiar osobno.

### Wymiar 1: Artefakty (25%)

Dla KAŻDEGO wymaganego artefaktu (lista z `ARTIFACT_CHECKLIST.md`, dostosowana do aktualnej fazy projektu):

| Stan artefaktu | Punkty |
|----------------|--------|
| Plik istnieje + wszystkie wymagane sekcje + treść adekwatna | 100% |
| Plik istnieje + większość sekcji (>50%) | 60% |
| Plik istnieje ale pusty/placeholder | 30% |
| Plik nie istnieje | 0% |

Score = średnia punktów ze wszystkich wymaganych artefaktów dla aktualnej fazy.

**Określenie fazy:** Sprawdź które pliki istnieją i stan HANDOFF — na tej podstawie ustal czy projekt jest w Phase 1/2/3/4/5.

### Wymiar 2: Testy (25%)

1. Wykryj framework testowy z `package.json` / `pyproject.toml` / `go.mod` / `TECH_STACK.md`.
2. Jeśli możliwe — uruchom testy. Jeśli nie (brak runtime/dependencies) — użyj analizy statycznej plików testowych i zanotuj w raporcie.

| Stan testów | Punkty |
|------------|--------|
| Brak frameworku / brak plików testowych | 0 |
| Framework jest, ale 0 testów | 10 |
| Testy istnieją ale FAIL | 20 |
| Testy PASS, ale brak testów security (negative cases) | 60 |
| Testy PASS + testy security obecne | 80 |
| Testy PASS + security tests + smoke test (health + happy path + error path) | 100 |

**Detekcja testów security:** szukaj w plikach testowych: `401`, `403`, `400`, `422`, `invalid`, `unauthorized`, `forbidden`, `injection`, `xss`, `sanitiz`. Minimum 2 takie testy = obecne.

**Detekcja smoke testu:** szukaj pliku `smoke*`, `e2e*`, lub testów z opisem `smoke`, `health`, `e2e`.

### Wymiar 3: Security (25%)

Sprawdź każdy item i zsumuj punkty (max 100):

| Sprawdzenie | Punkty | Jak sprawdzić |
|------------|--------|---------------|
| `.env` w `.gitignore` | 15 | Otwórz `.gitignore`, szukaj `.env` |
| Brak hardcoded secrets w kodzie | 15 | Przeszukaj `*.ts,*.js,*.py,*.tsx,*.jsx` (pomiń node_modules, .git, dist): wzorce `API_KEY=["']`, `PASSWORD=["']`, `SECRET=["']`, `TOKEN=["']` z konkretną wartością |
| Walidacja inputu na backendzie | 15 | Szukaj: zod, yup, joi, pydantic, `Field(`, `validator`, `sanitize`. Min. 1 endpoint z walidacją |
| `docs/SECURITY.md` z treścią | 10 | Plik istnieje i ma >10 linii merytorycznych |
| CORS skonfigurowany | 10 | Szukaj: `cors`, `CORSMiddleware`, `Access-Control`, `allowedOrigins` |
| Security headers | 10 | Szukaj: `helmet`, `X-Content-Type-Options`, `X-Frame-Options`, `Content-Security-Policy` w kodzie lub Caddyfile |
| Rate limiting | 10 | Szukaj: `rate-limit`, `rateLimit`, `throttle`, `limiter` |
| Testy security (negative cases) | 15 | Jak w Wymiarze 2 — jeśli obecne → 15 |

### Wymiar 4: Docs & Process (25%)

| Sprawdzenie | Max punkty | Jak liczyć |
|------------|-----------|------------|
| HANDOFF checkboxy `[x]` odpowiadają stanowi kodu | 25 | (checkboxy [x] / wszystkie checkboxy) × 25 |
| `docs/CHANGELOG.md` — wpisy per stage | 20 | (stages z wpisem / total stages) × 20 |
| `docs/API.md` — endpointy udokumentowane | 20 | >10 linii treści = 20, placeholder = 5, brak = 0 |
| `docs/README.md` — Quick Start obecny | 15 | Sekcja istnieje i nie jest placeholder = 15 |
| Git commity per stage | 10 | Widać commity stage'owe w `git log` = 10 |
| Git repo zainicjalizowane | 10 | `git status` działa = 10 |

### Końcowy score

```
HEALTH_SCORE = (Artefakty × 0.25) + (Testy × 0.25) + (Security × 0.25) + (Docs_Process × 0.25)
```

---

## 📋 Algorytm (liniowy, bez pętli)

1. **Określ fazę projektu** — na podstawie istniejących plików i HANDOFF.
2. **Oblicz każdy wymiar** — zgodnie z tabelami powyżej.
3. **Oblicz końcowy HEALTH_SCORE** — średnia ważona.
4. **Wylistuj TOP 5 problemów** — posortowane malejąco po wpływie na score (ile punktów zyskałby projekt gdyby problem został naprawiony).
5. **Wyświetl raport** — w formacie poniżej.

---

## 📊 Format raportu

```
═══════════════════════════════════════════════════
  PROJECT HEALTH SCORE
  Data: [YYYY-MM-DD]
  Projekt: [nazwa z PRD.md lub katalogu]
  Faza: [Phase X / Phase 3 Stage Y]
═══════════════════════════════════════════════════

  SCORE: [XX] / 100

  Artefakty:      [XX] / 100  ████████░░
  Testy:          [XX] / 100  ██████░░░░
  Security:       [XX] / 100  ████░░░░░░
  Docs & Process: [XX] / 100  █████████░

  ─── Szczegóły per wymiar ───

  Artefakty ([XX]/100):
  ✓ PRD.md — kompletny
  ✓ TECH_STACK.md — kompletny
  ✗ docs/API.md — brak pliku
  ...

  Testy ([XX]/100):
  [opis stanu testów]

  Security ([XX]/100):
  ✓ .env w .gitignore
  ✗ Brak rate limiting
  ...

  Docs & Process ([XX]/100):
  ✓ Git repo zainicjalizowane
  ✗ HANDOFF checkboxy: 5/20 (25%)
  ...

  ─── Top 5 do poprawy ───

  #  Problem                         Wpływ    Wymiar
  1. [opis]                          +[N] pkt  [wymiar]
  2. [opis]                          +[N] pkt  [wymiar]
  3. [opis]                          +[N] pkt  [wymiar]
  4. [opis]                          +[N] pkt  [wymiar]
  5. [opis]                          +[N] pkt  [wymiar]

  Napraw te 5 problemów → score wzrośnie do ~[estimated].

═══════════════════════════════════════════════════
```

**Progress bar:** 10 znaków. Każdy `█` = 10 punktów. Reszta = `░`.

---

## ⚠️ Edge cases

- **Brak git:** Zanotuj w raporcie (Docs & Process: -10 pkt). Kontynuuj bez git.
- **Brak testów (score = 0):** Wymiar Testy = 0. Zanotuj w Top 5.
- **Projekt w Phase 1-2 (brak kodu):** Licz score tylko z Artefaktów i Docs & Process (waga 50/50). Testy i Security = N/A.
- **Build się nie kompiluje:** Zanotuj, kontynuuj z analizą statyczną (nie uruchamiaj testów). Wymiar Testy: użyj analizy statycznej plików testowych.
- **HANDOFF nie ma struktury kursu:** Zanotuj brakujące sekcje w raporcie.
- **Checkbox `[x]` ale task nie ukończony w kodzie:** Zanotuj rozbieżność w raporcie.

---

## 🚀 Uruchomienie

Wklej do agenta AI w katalogu projektu:

```
Przeczytaj PROMPT_SCORE.md i oblicz score.
```

**Czas:** 1-3 minuty. **Wynik:** raport w terminalu — zero zmian w projekcie.

# PROMPT_SECURITY_AUDIT — Iteracyjny, stack-agnostic

**Niezależny audyt bezpieczeństwa projektu.** Wklej do agenta AI w katalogu projektu. Read-only — nic nie modyfikuje.

---

Przeczytaj CAŁY ten plik, a następnie wykonaj audyt bezpieczeństwa projektu.

## Rola

Jesteś niezależnym audytorem bezpieczeństwa. Twoje zadanie: znaleźć prawdziwe podatności, zweryfikować deklarowane zabezpieczenia i ocenić jakość testów.

**Zasady nadrzędne:**
- Nigdy nie ufaj dokumentacji. Czytaj kod źródłowy.
- Nigdy nie ufaj nazwie testu. Czytaj ciało testu.
- Dowody ponad opinie — każdy finding wymaga ścieżki pliku i numeru linii.
- Jeśli znajdziesz problem w obszarze X, zadaj sobie pytanie: "Co jeszcze może być źle w pobliżu?"

---

## Faza 1: Rekonesans (odkryj powierzchnię ataku)

Zmapuj projekt ZANIM zaczniesz audyt. NIE pomijaj tej fazy.

**1.1 Zidentyfikuj stack**
- Przeczytaj pliki w katalogu głównym: package.json, requirements.txt, go.mod, Cargo.toml, Gemfile, Dockerfile, docker-compose.yml, itp.
- Ustal: język(i), framework(i), baza(y) danych, usługi zewnętrzne, metoda deploymentu.

**1.2 Zmapuj powierzchnię ataku**
Znajdź i wylistuj:
- **Entry pointy**: trasy API / kontrolery, resolvery GraphQL, komendy CLI, handlery WebSocket, cron joby
- **System auth**: Jak użytkownicy są uwierzytelniani? Sesje, JWT, OAuth, klucze API?
- **Przepływ danych**: Gdzie wchodzi input od użytkownika? Gdzie jest zapisywany? Gdzie renderowany?
- **Obsługa plików**: Endpointy uploadu, serwowanie plików, pliki tymczasowe
- **Wywołania zewnętrzne**: API firm trzecich, wychodzące HTTP, konsumenci kolejek
- **Zarządzanie sekretami**: Jak ładowane są sekrety? Zmienne środowiskowe, pliki konfiguracyjne, vaults?
- **Middleware / interceptory**: Co wykonuje się przed handlerami? (auth, rate limiting, CORS, logowanie)

**1.3 Inwentaryzacja dokumentacji security**
Znajdź wszystkie pliki dokumentacji dot. bezpieczeństwa (SECURITY.md, threat modele, logi audytowe, sekcje security w README). Wylistuj KAŻDE deklarowane zabezpieczenie — to stanie się checklistą weryfikacyjną dla Fazy 2.

**1.4 Inwentaryzacja testów**
Wylistuj wszystkie pliki testowe. Skategoryzuj: unit, integracyjne, security, E2E. Odnotuj runner testowy i konfigurację (fixtures, mocki, testowa baza danych).

**Output Fazy 1:** Ustrukturyzowane podsumowanie: stack, mapa powierzchni ataku, deklaracje security do weryfikacji, inwentarz testów. To definiuje zakres Fazy 2.

---

## Faza 2: Celowany audyt (weryfikuj i sonduj)

Użyj outputu Rekonesansu do systematycznego sprawdzenia. Dla każdej kategorii poniżej zweryfikuj to, co dotyczy tego projektu.

### 2.1 Uwierzytelnianie i autoryzacja
- [ ] Hasła hashowane silnym algorytmem (bcrypt/scrypt/argon2), nigdy nie logowane ani zwracane w odpowiedziach
- [ ] Wygasanie tokenów/sesji wymuszone, tokeny walidowane na każdym chronionym endpoincie
- [ ] Sprawdzenie autoryzacji na każdym mutującym endpoincie (nie tylko auth, ale ownership/rola)
- [ ] Żaden endpoint nie jest dostępny bez zamierzonego auth (szukaj niezabezpieczonych tras)
- [ ] Sekrety (klucz JWT, klucze API, hasła do bazy): ładowane z env, brak hardcoded wartości domyślnych użytecznych na produkcji, fail-fast jeśli brakuje

### 2.2 Walidacja inputu i injection
- [ ] SQL: Wszystkie zapytania parametryzowane (brak konkatenacji/interpolacji stringów w zapytaniach). Szukaj raw SQL, `execute()`, f-stringów/template literals przy zapytaniach
- [ ] XSS: Treść użytkownika escapowana przy renderowaniu. Szukaj `dangerouslySetInnerHTML`, `innerHTML`, `v-html`, `|safe`, `raw()`, niesanityzowanych zmiennych szablonowych
- [ ] Command injection: Brak inputu użytkownika w komendach shell. Szukaj `exec`, `spawn`, `system`, `subprocess`, `os.popen`
- [ ] Path traversal: Endpointy serwujące pliki walidują nazwy plików (brak `../`). Szukaj path join z inputem użytkownika
- [ ] Deserializacja: Brak niebezpiecznej deserializacji inputu użytkownika (pickle, yaml.load, JSON.parse na niezwalidowanych blobinach)

### 2.3 Rate limiting i ochrona przed nadużyciami
- [ ] Endpointy auth (login, rejestracja, reset hasła) z rate limitem
- [ ] Endpointy tworzenia zasobów z rate limitem (zapobieganie spamowi)
- [ ] Limity rozmiaru plików wymuszone przy uploadzie
- [ ] Jeśli rate limiting jest deklarowany: zweryfikuj czy jest faktycznie aktywny (nie wyłączony w konfiguracji, nie obchodzony w testach)

### 2.4 Ekspozycja danych
- [ ] Odpowiedzi błędów nie ujawniają stack trace'ów, wewnętrznych ścieżek ani struktury bazy w trybie produkcyjnym
- [ ] Odpowiedzi API nie nadeksponują pól (brak hashów haseł, wewnętrznych ID, flag admina zwracanych nie-adminom)
- [ ] Logi nie zawierają sekretów, tokenów ani haseł
- [ ] Pliki .env / credentials w .gitignore

### 2.5 Nagłówki bezpieczeństwa i transport
- [ ] CORS: Allowlista originów (nie wildcard `*` na produkcji), odpowiednie metody/nagłówki
- [ ] Nagłówki bezpieczeństwa obecne: X-Content-Type-Options, X-Frame-Options, Content-Security-Policy
- [ ] HTTPS wymuszone (HSTS, redirect HTTP→HTTPS) jeśli dotyczy

### 2.6 Upload plików (jeśli dotyczy)
- [ ] MIME type walidowany (nie tylko rozszerzenie)
- [ ] Limit rozmiaru pliku wymuszony PRZED wczytaniem do pamięci
- [ ] Pliki graficzne zweryfikowane (magic bytes lub walidacja biblioteką)
- [ ] Uploadowane pliki serwowane z oddzielnej domeny/ścieżki, nie wykonywane
- [ ] WSZYSTKIE endpointy przyjmujące pliki współdzielą tę samą walidację (brak obejścia przez alternatywny endpoint)

### 2.7 Dokumentacja vs rzeczywistość
Dla każdej deklaracji security znalezionej w Fazie 1.3:
- Zweryfikuj w kodzie. Zapisz: ZAIMPLEMENTOWANE / CZĘŚCIOWO / BRAK / NIEPRAWIDŁOWE
- Oznacz każdą deklarację, która jest technicznie prawdziwa ale myląca (np. "zabezpieczone przez auth" gdy obiecano rate limiting)

---

## Faza 3: Deep dive (iteracyjne pogłębianie)

To jest pętla auto-badawcza. Dla każdego findingu z Fazy 2 zadawaj pytania rozszerzające i badaj dalej. Powtarzaj aż przestaniesz znajdować nowe problemy.

**Pętla:**
```
DLA KAŻDEGO findingu F z Fazy 2:
  1. ROZSZERZ: "Jeśli F istnieje tutaj, gdzie jeszcze może wystąpić ten sam wzorzec?"
     - Ta sama podatność w innych endpointach/komponentach
     - Ten sam błąd developera w podobnym kodzie
  2. PRZEŚLEDŹ: Podążaj za przepływem danych przez F od początku do końca
     - Skąd pochodzi input? Czy można go spreparować?
     - Gdzie trafia? Baza, log, odpowiedź, plik, zewnętrzne API?
  3. POŁĄCZ: "Czy F można łączyć z innym findingiem dla większego impaktu?"
     - np. brak rate limitu + brak CAPTCHA = credential stuffing
     - np. obejście uploadu + path traversal = zapis dowolnego pliku
  4. ZWERYFIKUJ: Opisz dokładnie jak atakujący wykorzystałby F
     - Jeśli nie potrafisz opisać konkretnych kroków, obniż severity
  5. ZAPISZ: Dodaj nowe findingi, zaktualizuj severity istniejących
  6. POWTÓRZ: Jeśli kroki 1-3 dały nowe tropy, zbadaj je
```

**Warunek stopu:** Pełna iteracja pętli nie produkuje nowych findingów.

---

## Faza 4: Audyt jakości testów

### 4.1 Czy testy uderzają w prawdziwy kod?
- Przeczytaj konfigurację testów (conftest, pliki setup, jest config). Czy klient testowy jest podłączony do prawdziwej aplikacji?
- Czy krytyczne funkcje bezpieczeństwa są wyłączone podczas testowania? (rate limiting off, auth obchodzony, walidacja pominięta)
- Jeśli zmockowane: czy mocki odpowiadają prawdziwemu kontraktowi API (kody statusu, kształty odpowiedzi, formaty błędów)?

### 4.2 Czy testy security testują prawdziwe ataki?
Dla każdego testu security przeczytaj ciało i zweryfikuj:
- Czy wysyła prawdziwy złośliwy payload, czy tylko sprawdza istnienie funkcji?
- Czy asertuje na WŁAŚCIWEJ rzeczy? (kod statusu ORAZ ciało odpowiedzi, nie tylko jedno)
- Czy test mógłby przejść nawet gdyby zabezpieczenie zostało usunięte? Jeśli tak → false positive.

### 4.3 Luki w pokryciu
- Dla każdego findingu z Faz 2-3: czy istnieje test, który by go wyłapał?
- Dla każdego chronionego endpointu: czy jest test na nieautoryzowany dostęp?
- Dla każdej reguły walidacji: czy jest test z nieprawidłowym inputem?
- Wylistuj brakujące testy wg priorytetu.

### 4.4 Test smells
Oznacz: puste ciała testów, `assert True`, testy które mockują to co testują, testy sprawdzające tylko happy path, testy bez asercji, hardcoded wartości "oczekiwane" nie pochodzące z systemu.

---

## Format raportu

```markdown
# Raport audytu bezpieczeństwa

## Podsumowanie projektu
- Stack: [auto-wykryty]
- Powierzchnia ataku: [liczba entry pointów, metoda auth, obsługa plików, usługi zewnętrzne]
- Szacowana ilość kodu: [szacunek]
- Suite testów: [X backend + Y frontend testów, runner, uwagi do konfiguracji]

## Podsumowanie wykonawcze
- Findingi krytyczne: [liczba]
- Wysokie: [liczba] | Średnie: [liczba] | Niskie: [liczba]
- Jakość testów: [SILNA / WYSTARCZAJĄCA / SŁABA / NIEWIARYGODNA]
- Top 3 ryzyka: [jedna linia każde]

## Findingi

### [F1] Tytuł
- **Severity**: KRYTYCZNY / WYSOKI / ŚREDNI / NISKI
- **Kategoria**: auth | injection | ekspozycja | konfiguracja | upload | rate-limit | luka-w-testach
- **Dowód**: `plik:linia` — co robi kod
- **Scenariusz exploitu**: konkretne kroki ataku
- **Rekomendacja**: konkretna poprawka
- **Pokrycie testami**: testowane / nietestowane / test istnieje ale niewystarczający

[powtórz dla każdego findingu, posortowane wg severity]

## Dokumentacja vs rzeczywistość
| # | Deklaracja | Status | Dowód |
|---|-----------|--------|-------|

## Szczegóły jakości testów
| Plik testowy | Werdykt | Problemy |
|-------------|---------|----------|

## Rekomendowane akcje (wg priorytetu)
1. [Poprawki KRYTYCZNE]
2. [Poprawki WYSOKIE]
3. [Brakujące testy do dodania]
4. [Korekty dokumentacji]
```

---

## Zasady anty-halucynacyjne

1. **Brak zakładanych podatności.** Jeśli nie znalazłeś tego w kodzie, to nie jest finding.
2. **Brak zawyżania severity.** Teoretyczne ryzyko bez ścieżki exploitu to NISKI, nie WYSOKI.
3. **Każdy finding wymaga:** ścieżki pliku, numeru linii, snippetu kodu i scenariusza exploitu.
4. **Jeśli dokumentacja nie istnieje**, nie karz za to — audytuj kod taki jaki jest.
5. **Uruchom testy** jeśli możesz. Zielone testy które nic nie testują są gorsze niż brak testów.

# PROMPT_AUTOFIX — Autonomiczny fixer projektu

**Prompt autonomiczny w stylu [autoresearch](https://github.com/karpathy/autoresearch).** Wklej go do agenta AI (Claude Code, Cursor, Windsurf itp.) w katalogu swojego projektu. Agent sam obliczy stan projektu, znajdzie problemy i naprawi je — commit po commicie — bez Twojej interwencji.

> Wzorzec: pętla modify → evaluate → keep/revert → repeat. Każdy fix to osobny commit — łatwy do przeglądu i cofnięcia.

---

Przeczytaj CAŁY ten plik, a następnie wykonaj pełną sesję autofix zgodnie z poniższymi instrukcjami.

## Kontekst — przeczytaj przed startem

Przeczytaj pliki w tym projekcie:
- `ARTIFACT_CHECKLIST.md` (kryteria akceptacji)
- `HANDOFF_STAGES_PLAN.md` (plan z checkboxami)
- `PRD.md` (wymagania)
- `TECH_STACK.md` (decyzje architektoniczne)

Jeśli którykolwiek z tych plików nie istnieje — **ZATRZYMAJ SIĘ** i poinformuj użytkownika:
> "Brakuje pliku [nazwa]. PROMPT_AUTOFIX wymaga kompletnej dokumentacji planistycznej. Uruchom najpierw AGENT_INIT_PROMPT.md do odpowiedniej fazy."

## Twoja rola

Jesteś autonomicznym **Project Health Fixerem**. Twoje zadanie:
1. Obliczyć Project Health Score (0-100)
2. Znaleźć najsłabszy punkt
3. Naprawić go (commit)
4. Zweryfikować, czy wynik się poprawił (keep/revert)
5. Powtarzać aż score >= 95 lub wyczerpiesz limit iteracji

**NIE pytasz użytkownika o zgodę na każdy fix.** Działasz autonomicznie. Użytkownik przegląda wynik (commity) po zakończeniu.

---

## 🔒 Pliki chronione (NEVER MODIFY)

Następujących plików **NIGDY nie modyfikujesz**:

- `PRD.md` — zatwierdzone wymagania użytkownika
- `TECH_STACK.md` — zatwierdzone decyzje architektoniczne
- `STACK_GUIDELINES.md` — zatwierdzone wytyczne
- `AGENT_INIT_PROMPT.md`, `ARTIFACT_CHECKLIST.md`, `VERIFICATION_PROMPT.md`, `PROMPT_HANDOFF_CHECK.md`, `PROMPT_AUTOFIX.md` — prompty kursu
- `.env` — sekrety użytkownika

Jeśli problem wymaga zmiany chronionego pliku — zapisz go w raporcie końcowym jako **"wymaga interwencji użytkownika"**.

## 🛡️ Safety Guards

1. **NIGDY nie usuwaj istniejących plików testowych** — możesz dodawać nowe lub naprawiać istniejące.
2. **NIGDY nie usuwaj funkcjonalności** — nie zmieniaj logiki biznesowej, nie usuwaj endpointów.
3. **Każdy fix = osobny commit** z komunikatem: `autofix: [wymiar] — [co naprawiono]`
4. **Przed sesją:** jeśli są niezacommitowane zmiany → `git add -A && git commit -m "autofix: save user work before autofix session"`
5. **Dozwolone operacje:**
   - DODAWANIE brakujących plików dokumentacji
   - UZUPEŁNIANIE brakujących sekcji w docs
   - NAPRAWIANIE broken testów (bez usuwania)
   - DODAWANIE brakujących testów (smoke, security negative cases)
   - DODAWANIE brakujących zabezpieczeń (walidacja, sanityzacja, headers)
   - AKTUALIZACJA checkboxów `[ ]` → `[x]` w HANDOFF (jeśli task jest faktycznie ukończony w kodzie)
   - DODAWANIE brakujących sekcji strukturalnych do HANDOFF (User Stories, Docs, Stage Completion — bez zmiany scope)
   - NAPRAWIANIE `.gitignore` (dodawanie brakujących wpisów)
   - TWORZENIE brakujących plików (`docs/API.md`, `docs/SECURITY.md` itp.)

---

## 📊 Project Health Score (0-100)

4 wymiary × 25% wagi każdy. Oblicz każdy wymiar osobno.

### Wymiar 1: Artefakty (25%)

Dla KAŻDEGO wymaganego artefaktu (lista z `ARTIFACT_CHECKLIST.md`, dostosowana do aktualnej fazy projektu):

| Stan artefaktu | Punkty |
|----------------|--------|
| Plik istnieje + wszystkie wymagane sekcje + treść adekwatna | 100% |
| Plik istnieje + większość sekcji (>50%) | 60% |
| Plik istnieje ale pusty/placeholder | 30% |
| Plik nie istnieje | 0% |

Score = średnia punktów ze wszystkich wymaganych artefaktów dla aktualnej fazy.

**Określenie fazy:** Sprawdź które pliki istnieją i stan HANDOFF — na tej podstawie ustal czy projekt jest w Phase 1/2/3/4/5.

### Wymiar 2: Testy (25%)

1. Wykryj framework testowy z `package.json` / `pyproject.toml` / `go.mod` / `TECH_STACK.md`.
2. Jeśli możliwe — uruchom testy. Jeśli nie (brak runtime/dependencies) — użyj analizy statycznej plików testowych i zanotuj w raporcie.

| Stan testów | Punkty |
|------------|--------|
| Brak frameworku / brak plików testowych | 0 |
| Framework jest, ale 0 testów | 10 |
| Testy istnieją ale FAIL | 20 |
| Testy PASS, ale brak testów security (negative cases) | 60 |
| Testy PASS + testy security obecne | 80 |
| Testy PASS + security tests + smoke test (health + happy path + error path) | 100 |

**Detekcja testów security:** szukaj w plikach testowych: `401`, `403`, `400`, `422`, `invalid`, `unauthorized`, `forbidden`, `injection`, `xss`, `sanitiz`. Minimum 2 takie testy = obecne.

**Detekcja smoke testu:** szukaj pliku `smoke*`, `e2e*`, lub testów z opisem `smoke`, `health`, `e2e`.

### Wymiar 3: Security (25%)

Sprawdź każdy item i zsumuj punkty (max 100):

| Sprawdzenie | Punkty | Jak sprawdzić |
|------------|--------|---------------|
| `.env` w `.gitignore` | 15 | Otwórz `.gitignore`, szukaj `.env` |
| Brak hardcoded secrets w kodzie | 15 | Przeszukaj `*.ts,*.js,*.py,*.tsx,*.jsx` (pomiń node_modules, .git, dist): wzorce `API_KEY=["']`, `PASSWORD=["']`, `SECRET=["']`, `TOKEN=["']` z konkretną wartością |
| Walidacja inputu na backendzie | 15 | Szukaj: zod, yup, joi, pydantic, `Field(`, `validator`, `sanitize`. Min. 1 endpoint z walidacją |
| `docs/SECURITY.md` z treścią | 10 | Plik istnieje i ma >10 linii merytorycznych |
| CORS skonfigurowany | 10 | Szukaj: `cors`, `CORSMiddleware`, `Access-Control`, `allowedOrigins` |
| Security headers | 10 | Szukaj: `helmet`, `X-Content-Type-Options`, `X-Frame-Options`, `Content-Security-Policy` w kodzie lub Caddyfile |
| Rate limiting | 10 | Szukaj: `rate-limit`, `rateLimit`, `throttle`, `limiter` |
| Testy security (negative cases) | 15 | Jak w Wymiarze 2 — jeśli obecne → 15 |

### Wymiar 4: Docs & Process (25%)

| Sprawdzenie | Max punkty | Jak liczyć |
|------------|-----------|------------|
| HANDOFF checkboxy `[x]` odpowiadają stanowi kodu | 25 | (checkboxy [x] / wszystkie checkboxy) × 25 |
| `docs/CHANGELOG.md` — wpisy per stage | 20 | (stages z wpisem / total stages) × 20 |
| `docs/API.md` — endpointy udokumentowane | 20 | >10 linii treści = 20, placeholder = 5, brak = 0 |
| `docs/README.md` — Quick Start obecny | 15 | Sekcja istnieje i nie jest placeholder = 15 |
| Git commity per stage | 10 | Widać commity stage'owe w `git log` = 10 |
| Git repo zainicjalizowane | 10 | `git status` działa = 10 |

### Końcowy score

```
HEALTH_SCORE = (Artefakty × 0.25) + (Testy × 0.25) + (Security × 0.25) + (Docs_Process × 0.25)
```

---

## 🔄 Pętla naprawcza

### Preconditions

1. Sprawdź git — jeśli brak → `git init && git add -A && git commit -m "autofix: initial state"`
2. Jeśli niezacommitowane zmiany → `git add -A && git commit -m "autofix: save user work before autofix session"`
3. Oblicz **INITIAL_SCORE** — pełny raport per wymiar
4. Wyświetl raport początkowy

### Algorytm

```
iteration = 0
MAX_ITERATIONS = 20
MAX_NO_IMPROVEMENT = 3
no_improvement_count = 0

WHILE score < 95 AND iteration < MAX_ITERATIONS AND no_improvement_count < MAX_NO_IMPROVEMENT:

    iteration += 1

    1. NAJSŁABSZY WYMIAR (najniższy score; przy remisie priorytet: Security > Artefakty > Testy > Docs)

    2. ZNAJDŹ KONKRETNY FIXABLE ISSUE w tym wymiarze. Priorytet:
       a) Brakujący plik (duży wpływ, łatwy fix)
       b) Brakująca sekcja w istniejącym pliku
       c) Broken test do naprawienia
       d) Brakujący test do dodania
       e) Brakujące zabezpieczenie
       f) Checkbox do zaktualizowania (jeśli task ukończony w kodzie)

    3. WYKONAJ FIX — minimalna, skupiona zmiana (1 problem = 1 fix)

    4. COMMIT: git add -A && git commit -m "autofix: [wymiar] — [opis]"

    5. OBLICZ NOWY SCORE

    6. DECYZJA:
       - new_score > old_score → KEEP, no_improvement_count = 0
       - new_score <= old_score → git revert HEAD --no-edit, no_improvement_count += 1

    7. LOG: "Iteracja N: [fix] | Score: old → new | ✓ KEEP / ✗ REVERT"
```

### Kiedy NIE naprawiać

Jeśli problem wymaga:
- Zmiany chronionego pliku → zanotuj w REMAINING_ISSUES
- Uruchomienia serwera/bazy (brak runtime) → zanotuj
- Naprawy logiki biznesowej → zanotuj
- Tworzenia `.env` z sekretami → zanotuj
- Danych testowych z zewnętrznego API → zanotuj

Kontynuuj z kolejnym problemem.

---

## 📋 Raporty

### Raport początkowy

```
═══════════════════════════════════════════════════
  AUTOFIX — Raport początkowy
  Data: [YYYY-MM-DD]
  Projekt: [nazwa z PRD.md lub katalogu]
  Faza: [Phase X / Phase 3 Stage Y]
═══════════════════════════════════════════════════

  PROJECT HEALTH SCORE: [XX] / 100

  Artefakty:      [XX] / 100  ████████░░
  Testy:          [XX] / 100  ██████░░░░
  Security:       [XX] / 100  ████░░░░░░
  Docs & Process: [XX] / 100  █████████░

  [szczegóły per wymiar — co zdane, co nie]

  Plan: max [MAX_ITERATIONS] iteracji naprawczych
═══════════════════════════════════════════════════
```

### Log iteracji (na bieżąco)

```
--- Iteracja N / MAX ---
Wymiar: [nazwa] ([score])
Problem: [opis]
Fix: [co zrobiono]
Commit: [hash 7 znaków]
Score: [old] → [new] (+/-delta)
Status: ✓ KEEP / ✗ REVERT
```

### Raport końcowy

```
═══════════════════════════════════════════════════
  AUTOFIX — Raport końcowy
  Iteracji: [N] / [MAX]
  Powód: [score >= 95 / max iteracji / brak poprawy]
═══════════════════════════════════════════════════

  SCORE: [XX] → [YY] / 100  (+ZZ)

  Artefakty:      [XX] → [YY]  (Δ +/-ZZ)
  Testy:          [XX] → [YY]  (Δ +/-ZZ)
  Security:       [XX] → [YY]  (Δ +/-ZZ)
  Docs & Process: [XX] → [YY]  (Δ +/-ZZ)

  Wykonane fixy:
  1. ✓ [wymiar] — [opis] | score +N | commit: [hash]
  2. ✗ [wymiar] — [opis] | brak poprawy, cofnięto
  ...

  Pozostałe problemy (wymaga interwencji użytkownika):
  1. [opis + powód]

  Przegląd: git log --oneline
  Cofnij wszystko: git revert --no-edit HEAD~N..HEAD
═══════════════════════════════════════════════════
```

---

## ⚠️ Edge cases

- **Brak git:** Zainicjalizuj `git init && git add -A && git commit -m "autofix: initial commit"`. Kontynuuj.
- **Brak testów (score = 0):** Dodaj TYLKO smoke test (health endpoint) + 1 test security (niepoprawny input). To podniesie score do ~40-60.
- **Projekt w Phase 1-2 (brak kodu):** Licz score tylko z Artefaktów i Docs & Process (waga 50/50). Testy i Security = N/A.
- **Build się nie kompiluje:** Zanotuj, kontynuuj z analizą statyczną (nie uruchamiaj testów).
- **HANDOFF nie ma struktury kursu:** DODAJ brakujące sekcje (User Stories, Docs, Stage Completion) z pustymi checkboxami. To uzupełnienie struktury, nie zmiana scope.
- **Checkbox `[x]` ale task nie ukończony w kodzie:** NIE cofaj. Zanotuj rozbieżność w raporcie.

---

## 🚀 Uruchomienie

Wklej do agenta AI w katalogu projektu:

```
Przeczytaj PROMPT_AUTOFIX.md i wykonaj pełną sesję autofix.
```

**Czas:** 5-20 minut. **Po zakończeniu:** przejrzyj commity i zdecyduj czy zachować.