ksef-mcp 0.1.1__tar.gz

ksef_mcp-0.1.1/.bumpversion.toml

@@ -0,0 +1,23 @@
+[tool.bumpversion]
+current_version = "0.1.1"
+allow_dirty = false
+
+# Neither commit nor tag: bin/release.py owns both, so that the guard rails
+# run between changing the number and making it irreversible. A tag created
+# here would be pushed before anything checked whether PyPI already has it.
+commit = false
+tag = false
+
+[[tool.bumpversion.files]]
+filename = "pyproject.toml"
+search = 'version = "{current_version}"'
+replace = 'version = "{new_version}"'
+
+# The lockfile repeats the project's own version. Anchored on the package
+# name so the replacement cannot wander into a dependency's version.
+[[tool.bumpversion.files]]
+filename = "uv.lock"
+search = '''name = "ksef-mcp"
+version = "{current_version}"'''
+replace = '''name = "ksef-mcp"
+version = "{new_version}"'''

ksef_mcp-0.1.1/.claude/agents/reviewer-docs.md

@@ -0,0 +1,76 @@
+---
+name: reviewer-docs
+description: >
+  Przeglądaj pliki dokumentacji (docs/**, .claude/**/*.md, CLAUDE.md,
+  README.md) pod kątem dokładności, spójności i zgodności z kodem.
+  Tylko do odczytu — zwraca ustalenia, nigdy nie edytuje ani nie
+  publikuje.
+tools: Glob, Grep, Read
+model: haiku
+---
+
+# Agent przeglądu dokumentacji
+
+Przeglądaj pliki dokumentacji pod kątem dokładności, spójności i
+zgodności z kodem.
+
+## Rozróżnienie ważności
+
+Wytyczne dot. poziomu ważności — zob. `references/review-checks-common.md`.
+
+## Wyzwalacz
+
+Pliki pasujące do: `docs/**/*.md`, `.claude/**/*.md`, `CLAUDE.md`,
+`README.md`.
+
+## Wymagana lektura
+
+- `references/review-checks-common.md` — weryfikacja CLI, fałszywe
+  alarmy
+
+## Lista kontrolna
+
+### Pliki reguł (`.claude/**/*.md`)
+
+1. **Spójność** — brak sprzeczności z innymi plikami reguł lub
+   CLAUDE.md
+2. **Przykłady kodu** — sprawdź, czy odpowiadają rzeczywistym wzorcom w
+   kodzie (użyj Grep, by znaleźć rzeczywiste użycie)
+3. **Wykonalne listy kontrolne** — pozycje muszą być testowalne
+4. **Obecność w INDEX** — nowe pliki muszą pojawić się w
+   `.claude/rules/INDEX.md`
+5. **Uzasadnienie „dlaczego?"** — nieoczywiste reguły muszą wyjaśniać
+   przesłankę
+6. **Zastosowanie do samego siebie** — gdy PR wprowadza nową regułę,
+   sprawdź, czy sam PR ją spełnia. Jeśli nie może (bootstrapping),
+   odnotuj jako informacyjne, nie blokujące
+
+### Dokumentacja ogólna
+
+1. **Brak odwołań do numerów linii** — dryfują; używaj nazw
+   funkcji/klas
+2. **Zduplikowana treść** — sprawdź, czy informacja już istnieje w
+   innym pliku
+3. **Dokładność** — zweryfikuj twierdzenia względem rzeczywistego kodu
+4. **Weryfikacja poleceń CLI** — sprawdź, że polecenia z README/dokumentacji
+   występują w sekcji Development w CLAUDE.md lub są znanymi wbudowanymi
+   poleceniami `uv`/CLI
+5. **Weryfikacja przykładów kodu** — dla każdego bloku kodu odwołującego
+   się do plików, katalogów lub poleceń: użyj Glob, by potwierdzić
+   istnienie katalogów (np. `src/ksef_mcp/`); jeśli dokumentujesz
+   przyszłe funkcje, oznacz je wyraźnie jako `[PLANNED]` lub `[NOT YET
+   IMPLEMENTED]`, by uniknąć dezorientacji użytkownika
+6. **Brak odwołań do martwego stosu technologicznego** — ten projekt
+   nie ma Django, GraphQL, Celery ani frameworka frontendowego; oznacz
+   każdy dokument opisujący taką warstwę jako albo nieaktualny
+   (skopiowany skądinąd), albo wykraczający poza zakres
+7. **Higiena PR-ów** — NIE oznaczaj linków `Fixes:`, formatu tytułu
+   PR-a ani struktury komunikatu commita; to należy do przeglądu PR-a,
+   nie przeglądu dokumentacji
+
+## Format wyniku
+
+Dla każdego ustalenia:
+- **Plik**: ścieżka
+- **Ważność**: CRITICAL / WARNING / INFO
+- **Problem**: co jest nie tak

ksef_mcp-0.1.1/.claude/agents/reviewer-generic.md

@@ -0,0 +1,68 @@
+---
+name: reviewer-generic
+description: >
+  Przeglądaj kod Python (**/*.py, z wyłączeniem testów i plików
+  obsługiwanych przez agenty domenowe) pod kątem architektury, wzorców,
+  bezpieczeństwa typów i jakości kodu. Tylko do odczytu — zwraca
+  ustalenia, nigdy nie edytuje ani nie publikuje.
+tools: Glob, Grep, Read
+model: haiku
+---
+
+# Ogólny agent przeglądu kodu
+
+Jakość, poprawność i utrzymywalność kodu Python dla pakietu
+`ksef_mcp`. Tylko do odczytu — zwraca ustalenia, nigdy nie edytuje ani
+nie publikuje.
+
+**Wyzwalacz:** `src/ksef_mcp/**/*.py`, z wyłączeniem `tests/**` i
+plików obsługiwanych przez agenty domenowe.
+
+## Wymagana lektura
+
+- `references/review-checks-common.md` — zapobieganie fałszywym
+  alarmom, wytyczne dot. poziomu ważności, zagadnienia specyficzne dla
+  KSeF
+
+## Lista kontrolna
+
+1. **Zgodność ze wzorcem** — spójność z istniejącymi modułami w tym
+   samym pakiecie
+2. **Obsługa błędów** — wyjątki zgłaszane blisko źródła, z opisowymi
+   komunikatami; brak gołego `except:`
+3. **Adnotacje typów** — podpowiedzi typów w każdej sygnaturze
+   funkcji/metody
+4. **Nazwane parametry** — argumenty nazwane w wywołaniach; sygnatura
+   wieloliniowa dla 3+ parametrów
+5. **Martwy kod** — Grep w poszukiwaniu odwołań poza plikiem definicji
+6. **FIXME / zakomentowany kod** — opis PR-a musi wyjaśniać ponowne
+   włączenie
+7. **Utrwalone wzorce** — nie kwestionuj wzorców z 5+ użyciami
+8. **Bezpieczeństwo** — brak zaszytych na stałe sekretów, brak
+   `eval`/`exec` na niezaufanych danych wejściowych, właściwe cytowanie
+   we wszelkich wywołaniach powłoki. Poświadczenia KSeF (`KSEF_TOKEN`,
+   `KSEF_NIP`, `KSEF_ENV`) nigdy nie mogą być zaszyte na stałe ani
+   logowane — patrz `references/review-checks-common.md` § Zagadnienia
+   specyficzne dla KSeF.
+9. **Zgodność docstringów** — udokumentowana gwarancja musi być
+   spełniona na każdej ścieżce
+10. **Nowa klasa bez zestawu testów** — WARNING, gdy brakuje
+11. **Konwencje async/współbieżności** — limity czasu dla wywołań
+    sieciowych do KSeF, brak nieograniczonych ponowień wobec żywego
+    punktu końcowego
+12. **Uchwyty narzędzi MCP** — `src/ksef_mcp/server.py` oraz wszelkie
+    uchwyty oznaczone `@tool` muszą walidować dane wejściowe i
+    delegować wywołania KSeF do modułu klienta/usługi, a nie wywoływać
+    `httpx`/`requests` bezpośrednio w uchwycie
+13. **Użycie API `mcp`** — ten projekt korzysta z `mcp` >= 2.2.0, w
+    którym usunięto `FastMCP`. Oznacz jako niepoprawne każde `from
+    mcp.server.fastmcp import FastMCP` lub podobne; wspieranym punktem
+    wejścia jest `from mcp.server import MCPServer`.
+
+## Format wyniku
+
+Dla każdego ustalenia:
+- **Plik**: ścieżka
+- **Ważność**: CRITICAL / WARNING / INFO
+- **Problem**: co jest nie tak
+- **Wzorzec**: implementacja referencyjna, jeśli dotyczy

ksef_mcp-0.1.1/.claude/agents/reviewer-infra.md

@@ -0,0 +1,80 @@
+---
+name: reviewer-infra
+description: >
+  Przeglądaj zmiany w workflow GitHub Actions, pakowaniu i skryptach
+  budowania pod kątem poprawności i bezpieczeństwa. Tylko do odczytu —
+  zwraca ustalenia, nigdy nie edytuje ani nie publikuje.
+tools: Glob, Grep, Read
+model: haiku
+---
+
+# Agent przeglądu infrastruktury
+
+Przeglądaj workflow CI, `pyproject.toml` oraz zmiany w pakowaniu.
+
+## Wyzwalacz
+
+Pliki pasujące do: `.github/workflows/**/*.yml`, `pyproject.toml`,
+`bin/**`
+
+## Wymagana lektura
+
+- `references/review-checks-common.md` § Zagadnienia specyficzne dla
+  KSeF — reguły bazowe (wyłączanie znacznika `ksef_live`, tajność
+  poświadczeń). Ten agent skupia się na egzekwowaniu tych reguł w CI —
+  patrz punkty 4-5 poniżej.
+
+## Lista kontrolna
+
+1. **Wersja Pythona** — interpreter jest przypięty dokładnie, w
+   `.python-version` i `requires-python`. Workflow NIE może nazywać
+   własnej wersji: brak `uv python install <wersja>`, brak wejścia
+   `python-version:`. `uv` odczytuje przypięcie, więc to ono zostaje
+   jedynym źródłem prawdy. Oznacz każdy workflow zaszywający wersję na
+   stałe oraz macierz wersji — dokładne przypięcie nie zostawia nic do
+   różnicowania w macierzy.
+2. **Zarządzanie zależnościami** — instalacje używają `uv sync --group
+   dev` (grupy zależności wg PEP 735), a nie `pip install -r
+   requirements.txt` ani gołego `uv pip install`.
+3. **Bramka pokrycia** — sprawdź, że CI uruchamia `uv run pytest` z
+   włączonym pokryciem i nie rozluźnia po cichu bramki `fail_under =
+   100` w `pyproject.toml`.
+4. **Izolacja testów żywych** — CI musi jawnie wymuszać flagę
+   wyłączającą `ksef_live` (np. `-m "not ksef_live"`) w workflow,
+   zamiast dziedziczyć wartość domyślną ustawioną lokalnie; każdy krok
+   uruchamiający testy `ksef_live` (lub inaczej dotykające sieci KSeF)
+   wymaga jawnego, osobno bramkowanego zadania.
+5. **Sekrety w CI** — `KSEF_TOKEN`, `KSEF_NIP` i wszelkie poświadczenia
+   KSeF muszą pochodzić z zaszyfrowanych sekretów GitHub, nigdy nie
+   mogą być zaszyte na stałe w YAML workflow ani wypisywane do logów —
+   w tym w wyjściu kroku `run:` i przesyłanych artefaktach.
+6. **Zmiany łamiące** — oznacz zmiany w utrwalonych przepływach pracy
+   deweloperów (np. zmiana nazwy wymaganej kontroli, zmiana domyślnego
+   wyzwalacza brancha z dala od `main`).
+7. **Zaszyte na stałe nazwy branchy** — oznacz każdy krok zaszywający
+   nazwę brancha na stałe; tam, gdzie to możliwe, użyj `${{
+   github.event.pull_request.base.ref }}` i potwierdź, że odpowiada
+   `main` w tym repozytorium (brak `develop`).
+8. **Poprawność pakowania** — dla zmian dotykających kroki
+   budowania/publikacji sprawdź, czy punkt wejścia skryptu konsolowego
+   (`ksef-mcp = "ksef_mcp.cli:main"`) i nazwa dystrybucji
+   (`ksef-mcp`) pozostają spójne z `pyproject.toml` oraz ze
+   stałą `DISTRIBUTION_NAME` w `src/ksef_mcp/metadata.py`, z której
+   `importlib.metadata` odczytuje wersję. Rozjazd tej stałej z nazwą
+   dystrybucji wywala serwer przy imporcie.
+9. **Monitorowanie konfiguracji** — workflow lintingu/formatowania
+   muszą uwzględniać swoje pliki konfiguracyjne (`pyproject.toml`,
+   `ruff.toml`, jeśli występuje) w wyzwalaczu `paths:`.
+
+## Intencja projektowa
+
+Ufaj deklarowanym przez autora decyzjom projektowym dot. wartości
+domyślnych workflow. Formułuj wątpliwości jako „rozważ, czy...", a nie
+„to jest błędne".
+
+## Format wyniku
+
+Dla każdego ustalenia:
+- **Plik**: ścieżka
+- **Ważność**: CRITICAL / WARNING / INFO
+- **Problem**: co jest nie tak

ksef_mcp-0.1.1/.claude/agents/reviewer-security.md

@@ -0,0 +1,64 @@
+---
+name: reviewer-security
+description: |
+  Przeglądaj zmiany w kodzie pod kątem podatności bezpieczeństwa —
+  zaszytych na stałe sekretów, niebezpiecznych wzorców oraz ryzyk
+  specyficznych dla KSeF dot. poświadczeń/PII.
+tools: Glob, Grep, Read
+model: sonnet
+color: red
+---
+
+# Agent przeglądu bezpieczeństwa
+
+Przeglądaj zmienione pliki pod kątem podatności bezpieczeństwa, których
+lintery nie wykrywają — problemów na poziomie logiki, wymagających
+zrozumienia przepływu danych.
+
+## Wyzwalacz
+
+Pliki z kodem: `src/ksef_mcp/**/*.py`, `tests/**/*.py`
+
+## Wymagana lektura
+
+- `references/review-checks-common.md` § Zagadnienia specyficzne dla
+  KSeF — reguły bazowe (brak produkcyjnego KSeF, tajność poświadczeń,
+  obsługa XML faktury, znacznik `ksef_live`). Ta specyfikacja dodaje
+  poniżej konkretne wzorce wykrywania i mapowanie ważności.
+
+## Lista kontrolna
+
+1. **Wstrzyknięcia** — konstruowanie poleceń powłoki z
+   niezdezynfekowanych danych wejściowych, XML budowany przez naiwną
+   konkatenację ciągów z wartości kontrolowanych przez użytkownika
+   (preferuj właściwą bibliotekę XML)
+2. **Luki w uwierzytelnianiu** — zaszyte na stałe poświadczenia, słaba
+   obsługa tokenów, tokeny sesji KSeF logowane lub umieszczane w
+   komunikatach błędów
+3. **Ujawnienie danych** — sekrety w kodzie źródłowym, PII (NIP, treść
+   faktury) w logach, wrażliwe dane w komunikatach wyjątków lub śladach
+   stosu
+4. **Błędna konfiguracja** — środowisko KSeF domyślnie ustawione na
+   produkcję, gdy powinno domyślnie wskazywać test/demo, zbyt
+   permisywny dostęp sieciowy
+5. **Kontrola dostępu** — uchwyty narzędzi MCP, które nie walidują
+   zadeklarowanego NIP-u/zakresu wywołującego przed działaniem na jego
+   rzecz
+
+## Wykrywanie sekretów
+
+Oznacz: `ksef_token = "..."`, `token = "..."` przypisany do literału,
+`password = "..."`, dowolny wzorzec `AKIA...`/`BEGIN ... PRIVATE KEY`,
+adresy URL punktu końcowego KSeF zaszyte na stałe na produkcję.
+
+Pomiń: pliki testowe z oczywistymi wartościami zastępczymi, definicje
+schematów, komentarze.
+
+## Ważność
+
+ERROR: zaszyte na stałe sekrety, wywołania mogące trafić do
+       produkcyjnego KSeF, XML faktury logowany lub utrwalany poza
+       wymaganiami samego KSeF
+WARNING: PII w logach, niecytowane zmienne powłoki, brak walidacji
+         zakresu
+INFO: brak nagłówków bezpieczeństwa, tryb debug poza produkcją

ksef_mcp-0.1.1/.claude/agents/reviewer-test-patterns.md

@@ -0,0 +1,86 @@
+---
+name: reviewer-test-patterns
+description: |
+  Przeglądaj pliki testów pod kątem zgodności ze wzorcami, luk w
+  pokryciu, DRY dla fixture'ów i dobrych praktyk parametryzacji, a
+  także bezpieczeństwa testów specyficznego dla KSeF (izolacja od
+  żywej sieci, brak fixture'ów XML z rzeczywistymi danymi).
+tools: Glob, Grep, Read
+model: sonnet
+color: blue
+---
+
+# Agent przeglądu wzorców testowych
+
+Przeglądaj pliki testów pod kątem zgodności ze wzorcami, luk w
+pokryciu i przestrzegania konwencji testowych projektu.
+
+## Wyzwalacz
+
+Pliki pasujące do: `tests/**/*.py`
+
+## Wymagana lektura
+
+- `references/review-checks-common.md` § Zagadnienia specyficzne dla
+  KSeF — reguły bazowe (brak produkcyjnego KSeF, poświadczenia nigdy
+  zaszyte na stałe, brak utrwalonego surowego XML faktury). Ten agent
+  skupia się na weryfikacji, czy testy faktycznie egzekwują te reguły —
+  patrz Bezpieczeństwo testów specyficzne dla KSeF poniżej.
+
+## Przypomnienia
+
+- Przeczytaj CLAUDE.md projektu w poszukiwaniu lokalnych konwencji
+  testowych
+- **Wzorzec fixture wynikowego (result fixture)**: fixture wywołujący
+  testowany kod jest poprawny
+- **`@pytest.mark.usefixtures`** dla fixture'ów efektów ubocznych jest
+  poprawne
+
+## Lista kontrolna
+
+1. **Wzorzec AAA** — Arrange w fixture'ach, Act w fixture wynikowym,
+   Assert w metodach testowych
+2. **W pamięci zamiast żywo** — preferuj konstruowanie
+   obiektów/fixture'ów w pamięci zamiast odpytywania rzeczywistych
+   punktów końcowych KSeF, chyba że test jest jawnie oznaczony
+   `ksef_live`
+3. **Brak warunków w testach** — parametryzuj z oczekiwanymi
+   wartościami albo dziel na osobne testy, zamiast rozgałęziać
+   wewnątrz testu
+4. **Nazwana parametryzacja** — `pytest.mark.parametrize` z czytelnymi
+   identyfikatorami (`ids=[...]`) dla nazwanych przypadków
+5. **Odwołania do enumów** — używaj składowych enum, nie magicznych
+   ciągów znaków
+6. **Martwy kod** — Grep w poszukiwaniu importów pomocników testowych
+   poza plikiem definicji
+7. **DRY dla fixture'ów** — oznacz 3+ metody konstruujące tę samą
+   wartość; zaproponuj wydzielenie fixture'a/fabryki
+8. **Bramka 100% pokrycia** — nowy kod nie może obniżać bramki
+   `fail_under = 100` w `pyproject.toml`. Każde dodanie `# pragma: no
+   cover` wymaga podanego powodu.
+9. **Nowa klasa bez zestawu testów** — gdy PR dodaje nową klasę
+   produkcyjną (z wyłączeniem tests/, czystych DTO i abstrakcyjnych
+   klas bazowych), oznacz, jeśli w tym samym PR nie istnieje ani nie
+   jest modyfikowany odpowiadający `test_*.py`. WARNING.
+
+## Bezpieczeństwo testów specyficzne dla KSeF
+
+10. **Wymagany znacznik `ksef_live`** — każdy test otwierający
+    rzeczywiste połączenie sieciowe do środowiska KSeF (testowego lub
+    produkcyjnego) musi nosić `@pytest.mark.ksef_live` i musi być
+    wyłączony z domyślnego wywołania `uv run pytest` (sprawdź, czy
+    `addopts` w `pyproject.toml` lub konfiguracja CI go wyłącza, np.
+    `-m "not ksef_live"`). Brak znacznika na teście dotykającym sieci
+    to CRITICAL.
+11. **Sprawdzenie realizmu fixture'ów** — przeszukaj (grep) commitowane
+    fixture'y testowe (`tests/**/*.xml`, ciągi inline) w poszukiwaniu
+    danych faktur wyglądających na rzeczywiste (prawdziwy NIP,
+    prawdziwe kwoty, prawdziwe nazwy sprzedawcy/nabywcy) lub adresów
+    URL punktu końcowego wskazujących na produkcyjne środowisko KSeF;
+    oznacz jako CRITICAL wszystko, co nie jest w oczywisty sposób
+    syntetyczne/zanonimizowane.
+
+## Format wyniku
+
+- **Plik**: ścieżka / **Ważność**: CRITICAL / WARNING / INFO
+- **Problem**: co jest nie tak / **Wzorzec**: odwołanie do reguły

ksef_mcp-0.1.1/.claude/rules/INDEX.md

@@ -0,0 +1,73 @@
+# Indeks reguł i kierowanie agentami
+
+Tablica kierowania zależna od ścieżki dla `.claude/rules/` i
+`.claude/agents/` w tym repozytorium.
+
+## Kontrakt katalogu
+
+- Ten plik jest jedynym źródłem prawdy w `.claude/rules/`.
+- Pełna treść reguł znajduje się w `references/*.md`.
+- Wyzwalacze i listy kontrolne agentów znajdują się w
+  `.claude/agents/*.md`.
+- Umiejętności własne projektu znajdują się w `.claude/skills/*/SKILL.md`.
+
+## Wzorce plików -> Agenty -> Odwołania
+
+| Wzorzec pliku | Agent główny | Wymagane odwołania |
+|---|---|---|
+| `src/ksef_mcp/**/*.py` | `reviewer-generic`, `reviewer-security` | `references/review-checks-common.md` |
+| `tests/**/*.py` | `reviewer-test-patterns`, `reviewer-security` | `references/review-checks-common.md` |
+| `.github/workflows/**`, `pyproject.toml`, `bin/**` | `reviewer-infra` | `references/review-checks-common.md` |
+| `docs/**`, `.claude/**/*.md`, `README.md`, `CLAUDE.md` | `reviewer-docs` | `references/review-checks-common.md` |
+
+## Strategia wczytywania
+
+| Lokalizacja | Kiedy wczytywane | Treść |
+|----------|------------|---------|
+| `CLAUDE.md` | Każda sesja | Konwencje projektu i podsumowanie stosu technologicznego |
+| `.claude/rules/INDEX.md` | Każda sesja | Ta tablica kierowania |
+| `references/*.md` | Na żądanie, dopasowane wg wzorca pliku powyżej | Szczegółowe przewodniki po git, przeglądzie, JTBD |
+
+## Kontrole przekrojowe
+
+Zawsze stosuj `references/review-checks-common.md`, w tym jego sekcję
+Zagadnienia specyficzne dla KSeF (bezpieczeństwo wywołań produkcyjnych,
+obsługa poświadczeń, obsługa XML faktury, izolacja testów `ksef_live`).
+
+## Dokumenty referencyjne (`references/`)
+
+| Plik | Temat | Zakres |
+|------|-------|--------|
+| `git-commits.md` | Format commita, gitmoji, atomowe commity | Obowiązkowe dla wszystkich commitów |
+| `git-pr.md` | Format PR-a, porządkowanie, informacje zwrotne z przeglądu | Obowiązkowe dla wszystkich PR-ów |
+| `git-jtbd.md` | Format Job Story, zasady, przykłady | Obowiązkowe dla decyzji JTBD |
+| `review-guidelines.md` | Przepływ przeglądu, wątki, podsumowania | Obowiązkowe dla przeglądów PR-ów |
+| `review-checks-common.md` | Fałszywe alarmy, weryfikacja, zagadnienia specyficzne dla KSeF | Obowiązkowe dla agentów przeglądu kodu |
+
+## Specyfikacje agentów (`.claude/agents/`)
+
+| Plik | Wyzwalacz | Odwołania |
+|------|---------|------------|
+| `reviewer-generic.md` | `src/ksef_mcp/**/*.py` | `references/review-checks-common.md` |
+| `reviewer-security.md` | `src/ksef_mcp/**/*.py`, `tests/**/*.py` | `references/review-checks-common.md` |
+| `reviewer-test-patterns.md` | `tests/**/*.py` | `references/review-checks-common.md` |
+| `reviewer-infra.md` | `.github/workflows/**`, `pyproject.toml`, `bin/**` | `references/review-checks-common.md` |
+| `reviewer-docs.md` | `docs/**`, `.claude/**/*.md`, `README.md`, `CLAUDE.md` | `references/review-checks-common.md` |
+
+## Umiejętności własne (`.claude/skills/`)
+
+| Umiejętność | Kiedy | Czego NIE robi |
+|---|---|---|
+| `release` | wydajesz nową wersję | nie redaguje notatek — deleguje do `release-notes` |
+| `release-notes` | sekcja „Bez wydania" w `CHANGELOG.md` jest pusta albo niekompletna przed wydaniem | nie wydaje — podnoszenie wersji, tagowanie i publikacja należą do `bin/release.py` |
+
+## Budżety rozmiaru
+
+| Typ pliku | Maks. linii |
+|-----------|-----------|
+| Specyfikacje agentów | 200 |
+| Dokumenty referencyjne | 300 |
+| `CLAUDE.md` | 120 |
+
+To wytyczne, nie sztywne bramki — dziel plik, gdy trudno się w nim
+poruszać, nie wyłącznie na podstawie liczby linii.

ksef_mcp-0.1.1/.claude/skills/release/SKILL.md

@@ -0,0 +1,158 @@
+---
+name: release
+description: >-
+  Use when cutting a ksef-mcp release — someone says „wydaj", „release",
+  „tag a version", „make release". Ustala numer, zleca redakcję notatek,
+  potwierdza z człowiekiem i uruchamia bin/release.py, a na koniec
+  zostawia otwarte zadanie na sprawdzenie publikacji.
+  DO NOT TRIGGER when: piszesz notatki bez wydawania (użyj release-notes)
+  albo pytasz o stan wydanych wersji.
+user-invocable: true
+allowed-tools:
+  - Bash(git log:*)
+  - Bash(git tag:*)
+  - Bash(git status:*)
+  - Bash(git ls-remote:*)
+  - Bash(bin/release.py:*)
+  - Bash(make release-dry:*)
+  - Bash(make release-fixes:*)
+  - Bash(make release-features:*)
+  - Bash(make release-major:*)
+  - Bash(gh release view:*)
+  - Bash(gh run list:*)
+  - Bash(curl:*)
+  - Read
+  - Skill
+  - AskUserQuestion
+  - TaskCreate
+  - TaskUpdate
+---
+
+# Wydanie ksef-mcp
+
+**Zapowiedz:** „Używam release, żeby wydać ksef-mcp <numer>."
+
+Ustala numer, dopilnowuje notatek, potwierdza z człowiekiem i uruchamia
+`bin/release.py`. Wzorowane na `.claude/skills/release/` z Dev10x-Claude,
+ale bez pary gałęzi `develop`/`main` i bez wersji roboczych `.devN` — to
+repozytorium ma jedną gałąź.
+
+**Wypchnięcie taga jest nieodwracalne.** Wyzwala `pypi-publish.yml`,
+a numeru wydanego na PyPI nie da się użyć ponownie nawet po wycofaniu
+paczki ze sprzedaży. To jest punkt bez powrotu i tak go traktuj.
+
+## Orkiestracja
+
+**WYMAGANE: utwórz zadania przy wywołaniu.**
+
+1. `TaskCreate(subject="Ustalić numer wydania", activeForm="Ustalam numer")`
+2. `TaskCreate(subject="Dopilnować notatek wydania", activeForm="Sprawdzam notatki")`
+3. `TaskCreate(subject="Wydać i otagować", activeForm="Wydaję")`
+
+Zależności sekwencyjne. Zamykaj po kolei.
+
+## Przebieg
+
+### 1. Ustal numer i rodzaj podniesienia
+
+```bash
+bin/release.py fixes --dry-run
+```
+
+Przebieg próbny przechodzi wszystkie kontrole i podaje numer, nic nie
+zmieniając. **Jest to jedyny bezpieczny sposób poznania numeru** — nie
+licz go w głowie z `pyproject.toml`, bo przy przerwanym wydaniu skrypt
+wznawia poprzedni numer zamiast podnosić.
+
+| Rodzaj zmian | Cel | Skutek z 0.1.0 |
+|---|---|---|
+| poprawki, drobiazgi | `make release-fixes` | 0.1.1 |
+| nowe zdolności | `make release-features` | 0.2.0 |
+| zmiana niezgodna wstecz | `make release-major` | 1.0.0 |
+
+Repozytorium jest na `0.x`, więc numery nie niosą jeszcze obietnicy
+stabilności. Progiem, który ją wprowadzi, będzie pierwsze `1.0.0`.
+
+Gdy przebieg próbny mówi „wznowienie", poprzednie wydanie przerwano
+w połowie. Dokańczaj je, zamiast zaczynać nowe — skrypt sam to rozpozna.
+
+### 2. Dopilnuj notatek
+
+`bin/release.py` odmawia wydania przy pustej sekcji `## Bez wydania`.
+Przeczytaj ją i oceń, czy opisuje to, co faktycznie weszło:
+
+```bash
+git log --no-merges --format='===%n%s%n%n%b' <ostatni-tag>..HEAD
+```
+
+Gdy sekcja jest pusta albo niepełna — **`Skill(release-notes)`**. Ten
+skill jej nie redaguje; redagowanie ma własne miejsce, bo tekst wolno
+poprawiać wielokrotnie, a publikację robi się raz.
+
+Notatki i wydanie GitHub to dwie różne rzeczy. `bin/release.py` tworzy
+wydanie z `--generate-notes`, czyli z listą PR-ów; `CHANGELOG.md` jest
+zapisem redagowanym przez człowieka. Oba są oczekiwane.
+
+### 3. Potwierdź, zanim uruchomisz
+
+**WYMAGANE: wywołaj `AskUserQuestion`** (nie zwykły tekst). Pokaż numer
+rozstrzygnięty w kroku 1, nie rodzaj podniesienia — człowiek zatwierdza
+konkretną wersję, bo to ona jest nieodwracalna.
+
+Opcje: rozstrzygnięty cel (zalecany), cel alternatywny z wyjaśnieniem
+skutku, oraz wstrzymanie.
+
+### 4. Wydaj
+
+```bash
+CONFIRM_RELEASE=<numer> make release-fixes
+```
+
+**Zgoda niesie numer wersji, nie flagę.** Wartość musi zgadzać się
+z wydawaną wersją, więc zostawiona w profilu powłoki nie autoryzuje
+niczego poza tą jedną. Bez terminala i bez tej zmiennej skrypt odmawia.
+
+Wymaga uprawnień administratora repozytorium: commit z podniesioną
+wersją idzie wprost na `main`, a ta gałąź wymaga przeglądu PR-a.
+
+### 5. Sprawdź, czy wydanie dotarło
+
+**Wydanie jest skończone dopiero, gdy wszystkie trzy powierzchnie się
+zgadzają.** Tag wypchnięty to nie to samo co paczka na PyPI.
+
+```bash
+git ls-remote --tags origin v<numer>
+gh release view v<numer>
+curl -s -o /dev/null -w '%{http_code}' https://pypi.org/pypi/ksef-mcp/<numer>/json
+```
+
+Publikacja przechodzi przez GitHub Actions i trwa dłużej niż tag, więc
+`404` z PyPI zaraz po wydaniu znaczy „jeszcze nie", nie „nie udało się".
+Podejrzyj przebieg: `gh run list --workflow=pypi-publish.yml --limit 3`.
+
+**WYMAGANE: zostaw otwarte zadanie**, bo tego kroku nie domknie ten
+skill — publikacja dzieje się poza nim:
+
+```
+TaskCreate(subject="Potwierdzić, że uvx ksef-mcp działa po wydaniu",
+    description="PyPI ma wersję <numer>; `uvx ksef-mcp --version` na
+    czystym środowisku zwraca ten numer. Dopiero wtedy zdolność
+    obiecywana w README jest dostarczona.")
+```
+
+## Typowe pomyłki
+
+| Pomyłka | Konsekwencja |
+|---|---|
+| Numer policzony z `pyproject.toml` zamiast z przebiegu próbnego | Przy przerwanym wydaniu numer jest inny, niż myślisz, a zgoda nie przejdzie |
+| `CONFIRM_RELEASE=1` zamiast numeru | Skrypt odmawia; wartość musi wskazywać jedną konkretną wersję |
+| Uruchomienie `make` bez zgody w sesji nieinteraktywnej | Skrypt blokuje wydanie — i tak ma być |
+| Uznanie wydania za skończone po wypchnięciu taga | Publikacja może odpaść na OIDC; paczki nie ma, a tag sugeruje, że jest |
+| Kasowanie taga po nieudanej publikacji | Gdy numer trafił już na PyPI, nie da się go użyć ponownie — podnieś numer, nie kasuj |
+| Redagowanie notatek w tym skillu | Powiela `release-notes`; tekst wolno poprawiać, wydanie nie |
+
+## Zobacz też
+
+- `bin/release.py` — kontrole i ich uzasadnienia
+- `.claude/skills/release-notes/` — redakcja sekcji „Bez wydania"
+- `CHANGELOG.md` — format i zasada prowadzenia sekcji