Minimalny standard artefaktu zespołowego

Standard opiera się na modelu obiektowym VeriLex (koncepcja v0.2) na bazie JSON Schema 2020-12.

1. Cel i zasady

Standard określa minimalne wymagania dla pakietu pracy (Legal Work Package, LWP) — jednostki zespołowej wymiany wyników pracy prawnej. Zasady:

1. Otwarte formaty. Markdown, JSON/JSONL, YAML, CSV, Mermaid, Git. Żadnych zastrzeżonych kontenerów; pakiet jest czytelny dla człowieka w dowolnym edytorze i dla agenta w dowolnym środowisku.
2. Proporcjonalność. Trzy poziomy szczegółowości (podstawowy / rozszerzony / audytowy); poziom dobiera się według ceny błędu, a nie „na wszelki wypadek”.
3. Weryfikowalność ważniejsza niż kompletność. Każdy obowiązkowy element istnieje dlatego, że ktoś go weryfikuje — człowiek lub agent.
4. Interoperacyjność. Pakiet zmontowany w jednym środowisku agentowym (OpenAI Codex, Anthropic Claude Code, otwarte odpowiedniki) musi być akceptowany i weryfikowalny w każdym innym. Standard opiera się wyłącznie na gotowych, przemysłowo eksploatowanych środowiskach — nie trzeba opracowywać własnego oprogramowania do pracy z pakietami, a standard można stosować już dziś.
5. Brak źródła — brak mocnego wniosku. Agent proponuje — człowiek decyduje.

2. Osiem typów artefaktów (rdzeń standardu)

Dziedziczone z modelu obiektowego VeriLex v0.2:

Typ	Plik	Przeznaczenie
source_registry	sources/source-registry.json	Rejestr źródeł: co legło u podstaw pracy, z identyfikatorami, datami i statusami dostępu
evidence_pack	sources/evidence-pack.jsonl	Wyodrębnione fragmenty dowodowe, przypisane do konkretnego miejsca w konkretnym źródle
fact_matrix	analysis/fact-matrix.json	Fakty ze statusami, oddzielone od ocen prawnych
rules_matrix	analysis/rules-matrix.json	Właściwe normy i kryteria (z redakcjami i datami obowiązywania), powiązane z faktami
issue_tree	analysis/issue-tree.json	Drzewo kwestii prawnych: analiza jako zbiór weryfikowalnych pytań
critique_pack	analysis/critique-pack.json	Słabe punkty, kontrargumenty, alternatywne stanowiska — obowiązkowe dla każdego poważnego wniosku
decision_log	logs/decision-log.json	Dziennik kluczowych decyzji: rozwidlenia, alternatywy, niepewność, kto potwierdził
handoff_package	handoff/handoff.json	Pakiet przekazania: co zrobiono, co zweryfikowano, co jest sporne, co ma zrobić kolejna osoba; odwołuje się do konkretnych wersji artefaktów

3. Wspólna koperta metadanych

Każdy artefakt niesie kopertę:

artifact_type: fact_matrix        # jeden z 8 typów
schema_version: "0.1"             # wersja schematu standardu
matter_id: MAT-2026-0042          # identyfikator zlecenia/sprawy
version: 3                        # inkrement całkowitoliczbowy; wersje niezmienne
created_at: 2026-07-10T14:30:00+03:00
created_by:
  actor: "О. Шевченко"
  actor_type: human               # human | agent | joint
  agent_env: "claude-code 2.x"    # jeśli brał udział agent
review_status: human_confirmed    # draft | agent_generated | human_review_pending |
                                  # human_confirmed | returned_for_rework | archived
depends_on:                       # z jakich wersji wejść zmontowano
  - fact_matrix@2
  - rules_matrix@1
model_call_refs: []               # odwołania do dziennika wywołań modelu (poziom audytowy)
confidentiality: institutional    # public | institutional | confidential
language: uk

4. Statusy faktów (zbiór kanoniczny)

alleged (twierdzony) · established (ustalony) · disputed (kwestionowany) · inferred (wywnioskowany) · missing (brak danych) · rejected (odrzucony) · excluded (wyłączony).

Niezmienniki:

• established wymaga ≥1 powiązanego dowodu z evidence_pack oraz potwierdzenia przez człowieka;
• wniosek oparty wyłącznie na faktach alleged/inferred nie może być oznaczony jako mocny;
• każde istotne twierdzenie w tekście finalnym odwołuje się do fact_id / rule_id / source_id.

5. Łańcuch pochodzenia

source → evidence → fact → rule → issue → conclusion → decision_log → handoff

Powiązania są przechowywane w samych artefaktach (pola source_id, evidence_ids, fact_ids, rule_ids, issue_id) i tworzą weryfikowalny graf. Walidator musi umieć zbudować ten graf i wykryć: wnioski wiszące w powietrzu (bez podstaw), nieużywane źródła, przerwy w łańcuchu i cykle.

6. Trzy poziomy pakietu

Podstawowy (praca codzienna)

Obowiązkowe: final/ (tekst) + source_registry + kluczowe fakty (uproszczona fact_matrix) + krótki dziennik weryfikacji + open-questions.md.

Rozszerzony (złożone analizy)

Poziom podstawowy + pełne fact_matrix, rules_matrix, issue_tree, critique_pack, tabela dowodów, graf powiązań (reasoning-graph.mmd), protokół weryfikacji.

Audytowy (wysoka cena błędu)

Poziom rozszerzony + decision_log z polami potwierdzenia, dziennik działań (activity.jsonl), identyfikatory modeli/instrukcji (model_call_refs, wersja instrukcji), sumy kontrolne plików (checksums.sha256), role uczestników, migawka pakietu w momencie podjęcia decyzji.

7. Obowiązkowe kontrole przy odbiorze pakietu

Strona odbierająca (jej agent) wykonuje co najmniej:

1. Walidację schematu wszystkich artefaktów JSON/YAML.
2. Kontrolę łańcucha: brak mocnych wniosków bez podstaw (check_unsupported_claims).
3. Kontrolę cytatów: wyodrębnione fragmenty odpowiadają źródłom pierwotnym (validate_evidence_links).
4. Kontrolę dat: redakcje norm obowiązują na prawnie istotne daty (date-check).
5. Kontrolę poufności: pakiet nie zawiera danych zakazanych do przekazania na tym poziomie (redaction-check) — ukraiński słownik danych wrażliwych: numery identyfikacji podatkowej (РНОКПП/ІПН), dane paszportowe, adresy, dane bankowe, tajemnica lekarska i adwokacka.
6. Kontrolę kompletności handoff: wskazano nierozwiązane kwestie i kolejny krok.

Pakiet, który nie przejdzie kontroli 1–3, jest zwracany automatycznie ze strukturalną listą blokerów (nie jest to „odrzucenie”, lecz normalny cykl).

8. Zasady tworzenia i odbioru

1. Wersje artefaktów są niezmienne; poprawka = nowa wersja. Poprzednie wersje nie są usuwane, lecz archiwizowane.
2. handoff_package odwołuje się do konkretnych wersji (fact_matrix@4), a nie do „stanu ostatniego”.
3. Uwagi formułuje się jako critique_pack skierowany do konkretnych elementów (fact_id, conclusion_id) — nie prozą w wiadomości.
4. Dokument finalny (final/*.md) jest artefaktem pochodnym: w razie rozbieżności między tekstem a matrycami priorytet mają matryce; rozbieżność = defekt pakietu.
5. Języki: artefakty w języku roboczym (uk), metadane i klucze — alfabetem łacińskim zgodnie ze standardem; dopuszczalne jest równoległe pole _en.
6. Pakiet znajduje się w repozytorium Git zlecenia; tag handoff/<n> oznacza moment przekazania.

9. Metryki jakości pakietu

Metryka	Formuła	Docelowy próg pilotażu
Source coverage	udział istotnych twierdzeń powiązanych ze źródłami	≥ 90%
Unsupported claim rate	udział mocnych wniosków bez podstaw	→ 0
Handoff completeness	udział przekazań przyjętych bez zwrotu z przyczyn formalnych	≥ 80%
Time to review	mediana czasu weryfikacji pakietu przez odbiorcę	↓ ≥ 50% względem punktu odniesienia
Reproducibility score	udział wniosków z odtwarzalnym łańcuchem „z jakich wersji wejść”	≥ 95%

10. Status i rozwój standardu

Wersja 0.1 jest punktem wyjścia dla pilotaży; jest celowo minimalna. Zmiany wprowadza się przez PR do otwartego repozytorium (kwestie pozycjonowania opisano osobno); każda zmiana schematu = inkrement schema_version + notatka migracyjna. Pełne schematy JSON ośmiu artefaktów już istnieją w modelu obiektowym VeriLex i są przenoszone do otwartego repozytorium jako normatywny załącznik do niniejszego standardu; przykład wypełnionego pakietu — przykład pakietu artefaktów.