T2: start

.idea/vcs.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="VcsDirectoryMappings">
+    <mapping directory="$PROJECT_DIR$" vcs="Git" />
+  </component>
+</project>

AGENTS.md

@@ -1,6 +1,6 @@
 # Szpitale-graph — agent instructions
 
-**TL;DR:** `cd szpitale-graph && ./mvnw -q compile` (wrapper, not `mvn`). Build lives in `szpitale-graph/`. Neo4j via `docker compose up -d` from same dir. CLAUDE.md has full TDD rules and PLAN2.md has the execution backlog. This file covers what CLAUDE.md doesn't.
+**TL;DR:** `cd szpitale-graph && ./mvnw -q compile` (wrapper, not `mvn`). Build lives in `szpitale-graph/`. Neo4j via `docker compose up -d` from same dir. CLAUDE.md has full TDD rules and PLAN.md has the execution backlog. This file covers what CLAUDE.md doesn't.
 
 ## Project location & structure
 
@@ -55,7 +55,7 @@ Every cell **must** have an `https://...` URL. No URL = `BRAK_DANYCH` or skip.
 
 ## Current state: build is broken (T1 blocker)
 
-`Deduplicator.java:75` — `groups` is `Map<String, List<Person>>` but code puts `List<String>`. Fix needed before any test can run. See PLAN2.md §11, task T1.
+`Deduplicator.java:75` — `groups` is `Map<String, List<Person>>` but code puts `List<String>`. Fix needed before any test can run. See PLAN.md §11, task T1.
 
 ## Dependencies
 
@@ -77,7 +77,7 @@ Every cell **must** have an `https://...` URL. No URL = `BRAK_DANYCH` or skip.
 
 ## Git / checkpoint protocol
 
-PLAN2.md mandates: one checkpoint commit per task (`-m "T<n>: descript [checkpoint]"`). The `local-agent-progress.json` file tracks task states. On conflicts, **git log is the source of truth** (PLAN2.md §13.5).
+PLAN.md mandates: one checkpoint commit per task (`-m "T<n>: descript [checkpoint]"`). The `local-agent-progress.json` file tracks task states. On conflicts, **git log is the source of truth** (PLAN.md §13.5).
 
 ## Getting a new voivodeship
 

CLAUDE.md

@@ -1,6 +1,6 @@
 # Szpitale-graph — instrukcje projektu
 
-Aplikacja Java 21 + Maven + Spring Shell budująca graf szpitali w Neo4j. Architektura warstwowa (`ingest` → canonical JSON → `load`). Szczegóły w [PLAN2.md](PLAN2.md).
+Aplikacja Java 21 + Maven + Spring Shell budująca graf szpitali w Neo4j. Architektura warstwowa (`ingest` → canonical JSON → `load`). Szczegóły w [PLAN.md](PLAN.md).
 
 ## Proces tworzenia oprogramowania: TDD (obowiązkowy)
 

PLAN.md

@@ -11,6 +11,25 @@
 
 ---
 
+## Proces pracy: TDD (obowiązkowy)
+
+Cały kod tego planu powstaje test-first. Agent **nie pisze kodu produkcyjnego zanim nie istnieje test, który go wymaga**. Pełne reguły w [CLAUDE.md](CLAUDE.md); tu skrót obowiązujący dla każdego zadania (§11) i każdej klasy z sekcji 3.
+
+**Cykl red → green → refactor (małe kroki, jeden zachowaniowy przyrost = jeden obieg):**
+1. **RED** — napisz test opisujący pożądane zachowanie w `src/test/java/...` (mirror pakietu z `src/main/java`). Uruchom `./mvnw -q test -Dtest=NazwaTestu` i zobacz, że **failuje** (kompiluje się, asercja nie przechodzi). Test bez uprzedniej porażki nic nie dowodzi.
+2. **GREEN** — napisz **minimalny** kod produkcyjny zazieleniający test. Bez funkcji, których żaden test nie wymaga.
+3. **REFACTOR** — posprzątaj kod i test przy zielonym pasku; testy nadal zielone.
+
+**Zasady wiążące:**
+- **Test najpierw.** Bug fix zaczyna się od testu reprodukującego buga (RED), potem poprawka (np. T1 `Deduplicator`).
+- **Dług techniczny:** istniejący kod produkcyjny powstał bez testów. Dotykając klasy bez pokrycia — najpierw dopisz **charakteryzujący** test aktualnego zachowania (green), potem prowadź zmianę cyklem TDD (patrz T2–T3).
+- **Testy jednostkowe** (bez Neo4j, szybkie, deterministyczne): normalizacja (`NameNormalizer`, `PartyNormalizer`), deduplikacja (`Deduplicator`), parsowanie źródeł (`MarkdownRegistrySource`), serializacja canonical (`CanonicalWriter`/`CanonicalReader`).
+- **Testy integracyjne** dla warstwy `load`: Neo4j przez **Testcontainers** (`org.testcontainers:neo4j`) — idempotencja `MERGE`, constrainty schematu, raporty walidatora (tag **[NEO4J]**, wymaga Dockera).
+- **Nazwy testów** opisują zachowanie: `metoda_warunek_oczekiwanyWynik` (np. `normalize_polishDiacritics_strippedToAsciiSlug`).
+- **Definicja ukończenia:** zielony `./mvnw -q test` jest warunkiem uznania zadania za zrobione. Jeśli testy nie mogą się uruchomić (brak `mvn`/Dockera) — zgłoś jawnie, nie deklaruj sukcesu (tag `[~]` + notatka).
+
+---
+
 ## 1. Architektura warstwowa
 
 Aplikacja to jeden artefakt Spring Boot / Spring Shell z dwiema wyraźnie rozdzielonymi warstwami. Warstwy komunikują się przez **plik(i) w uwspólnionym formacie kanonicznym** (JSON), dzięki czemu można je uruchamiać niezależnie, wznawiać i testować.