# Používateľský manuál: ITHZ Invariant Diff

ITHZ Invariant Diff je lokálny nástroj na porovnanie dvoch verzií projektu
alebo dvoch `project.ithz` archívov.

Jeho hlavná otázka:

```text
Zmenil sa informačný stav, alebo sa zmenila iba reprezentácia?
```

Nie je to klon bežného textového diffu. Bežný diff povie, čo je iné. ITHZ
Invariant Diff sa snaží oddeliť:

- skutočnú materiálnu zmenu;
- zmenu formátu;
- zmenu poradia;
- presun alebo rename;
- rizikovú zmenu;
- claim-boundary zmenu;
- neznámu zmenu, ktorú treba reviewnúť.

## Základný príkaz

V tomto repozitári:

```powershell
$env:PYTHONPATH='C:\work\ITHKOR\ithz_mcp\src'
python -m ithz_mcp ithz-diff --help
```

Syntax:

```powershell
python -m ithz_mcp ithz-diff <left> <right> [options]
```

Podporované vstupy v MVP:

- folder vs folder;
- `.ithz` archive vs `.ithz` archive.

## Najčastejšie použitie

Porovnanie dvoch projektových priečinkov:

```powershell
python -m ithz_mcp ithz-diff `
  C:\work\project_before `
  C:\work\project_after `
  --mode project
```

Porovnanie a zápis JSON + HTML reportu:

```powershell
python -m ithz_mcp ithz-diff `
  C:\work\project_before `
  C:\work\project_after `
  --mode project `
  --json C:\work\tmp\diff_report.json `
  --report C:\work\tmp\diff_report.html `
  --canonical-hashes C:\work\tmp\canonical_hashes.json
```

Porovnanie dvoch ITHZ pamäťových archívov:

```powershell
python -m ithz_mcp ithz-diff `
  C:\work\old\project.ithz `
  C:\work\new\project.ithz `
  --mode ithz `
  --json C:\work\tmp\ithz_diff_report.json `
  --report C:\work\tmp\ithz_diff_report.html
```

## Options

`--mode`

```text
auto | project | folder | data | ithz
```

- `auto`: vyberie režim podľa vstupov;
- `project`: folder diff pre projekt;
- `folder`: aliasovo podobné projektovému folder diffu;
- `data`: folder/data diff s order-insensitive normalizáciou, keď ju zapneš;
- `ithz`: porovná `.ithz` archívy.

`--ignore-order`

Použi pri data-heavy vstupoch, kde poradie riadkov nie je informačná zmena:

```powershell
python -m ithz_mcp ithz-diff before after --mode data --ignore-order
```

`--json`

Zapíše úplný machine-readable report:

```powershell
--json report.json
```

`--json-output`

Vypíše úplný JSON report do terminálu:

```powershell
--json-output
```

`--report`

Zapíše HTML review report:

```powershell
--report report.html
```

`--canonical-hashes`

Zapíše iba canonical hash časť:

```powershell
--canonical-hashes canonical_hashes.json
```

## Terminálový výstup

Typický výstup:

```text
Invariant verdict: CLAIM_BOUNDARY_CHANGE
Canonical equal: false
Input type: folder
material: 2
representation_only: 1
risk_relevant_change: 1
claim_boundary_change: 1
Review priority:
- config/settings.json
- docs/claim.md
```

To znamená:

- sú tam skutočné zmeny;
- aspoň jedna zmena sa dotýka claim boundary;
- `config/settings.json` a `docs/claim.md` treba pozrieť ako prvé;
- nie všetky raw zmeny sú rovnako dôležité.

## JSON report

Report má schému:

```json
{
  "schema": "ithz_invariant_diff_report_v1",
  "mode": "project",
  "input_type": "folder",
  "verdict": "MATERIAL_CHANGE",
  "canonical_equal": false,
  "counts": {
    "material": 7,
    "representation_only": 143,
    "risk_relevant_change": 3,
    "claim_boundary_change": 1
  },
  "review_priority": [
    "config/security.yml",
    "docs/D_BRANCH_STATUS.md"
  ],
  "changes": []
}
```

Dôležité polia:

- `verdict`: celkové hodnotenie;
- `canonical_equal`: či je canonical stav rovnaký;
- `counts`: počty typov zmien;
- `review_priority`: odporúčané poradie review;
- `changes`: detailné zmeny;
- `canonical_hashes`: canonical identita ľavej a pravej strany;
- `normalization_rules`: pravidlá použité pri diffovaní.

## Verdicts

`EQUIVALENT`

Canonical stav je rovnaký. Ak sa bajty líšia, rozdiel je iba reprezentácia.

`REPRESENTATION_ONLY_CHANGED`

Raw diff existuje, ale canonical hash je stabilný. Príklady:

- iné line endings;
- trailing whitespace;
- JSON key order;
- ignorovaný timestamp-like JSON metadata kľúč.

`STRUCTURAL_ONLY_CHANGED`

Obsahové jednotky sú rovnaké, ale štruktúra alebo poradie sa zmenili. Typicky
presun sekcie v Markdown dokumente.

`MATERIAL_CHANGE`

Canonical obsah sa zmenil a zmena nie je iba formát alebo presun.

`RISK_RELEVANT_CHANGE`

Zmena sa dotýka cesty alebo textu, ktorý vyzerá bezpečnostne alebo konfiguračne
dôležito. Príklady:

- `config/`;
- `security`;
- `auth`;
- `permissions`;
- `mcp_server`;
- `native_archive_store`;
- `project_ledger`;
- `safety`;
- `risk`;
- `gate`.

`CLAIM_BOUNDARY_CHANGE`

Zmena sa dotýka claim textu alebo ledger/audit hranice. Príklady:

- `QPU`;
- `continuum`;
- `gravity`;
- `blocked claim`;
- `allowed claim`;
- `replaces Git`;
- `production database`;
- `ZIP superiority`.

`UNKNOWN_NEEDS_REVIEW`

Nástroj nevie bezpečne rozhodnúť. Typicky binárna zmena. Unknown zmeny sa nikdy
netvária ako ekvivalentné.

## Folder/project mode

Folder mode robí:

- deterministický scan súborov;
- ignoruje samotné `.ithz` archívy;
- normalizuje text;
- canonicalizuje JSON;
- vie rozpoznať presunuté/renamed súbory podľa canonical content hash;
- vie rozdeliť representation-only, structural, material, risk a claim zmeny.

Príklad: agent preformátoval projekt

```powershell
python -m ithz_mcp ithz-diff `
  C:\work\before_agent `
  C:\work\after_agent `
  --mode project `
  --json C:\work\tmp\agent_diff.json `
  --report C:\work\tmp\agent_diff.html
```

Čo hľadať:

- ak je `representation_only` vysoké a `material` nízke, veľa raw churnu je
  iba formát;
- `review_priority` ukáže, čo čítať prvé;
- `risk_relevant_change` si vyžaduje manuálnu kontrolu;
- `claim_boundary_change` si vyžaduje kontrolu tvrdení v docs alebo ledgeri.

## ITHZ archive mode

`.ithz` mode porovná pamäťové archívy.

Používa existujúcu ITHZ-MCP/native vrstvu:

- safe verify archívu;
- `archive_semantic_hash`;
- `project_semantic_hash`;
- event semantic hash;
- prompt semantic hash;
- ledger projections.

Príkaz:

```powershell
python -m ithz_mcp ithz-diff `
  C:\work\archive_old\project.ithz `
  C:\work\archive_new\project.ithz `
  --mode ithz `
  --json C:\work\tmp\archive_diff.json
```

Ako čítať výsledok:

- `byte_equal=true`: archívy sú bajtovo rovnaké;
- `canonical_equal=true`: archive semantic stav je rovnaký;
- `project_semantic_equal=true`: source/project semantic stav je rovnaký;
- event delty ukazujú, aké pamäťové udalosti pribudli alebo zmizli;
- claim/blocked-claim/replication/reviewer zmeny idú do claim-boundary zmien;
- risk/gate/must-not-break zmeny idú do risk-relevant zmien.

## Kedy použiť `git-diff-ithz` a kedy `ithz-diff`

Použi `git-diff-ithz`, keď chceš stable textconv summary pre Git:

```powershell
python -m ithz_mcp git-diff-ithz --archive project.ithz
```

Použi `ithz-diff`, keď chceš porovnať dve verzie:

```powershell
python -m ithz_mcp ithz-diff old.ithz new.ithz --mode ithz
python -m ithz_mcp ithz-diff before_dir after_dir --mode project
```

Jednoducho:

- `git-diff-ithz`: jeden archív ako text pre Git diff;
- `ithz-diff`: ľavá verzia vs pravá verzia.

## Praktické scenáre

### Agent zmenil veľa súborov

```powershell
python -m ithz_mcp ithz-diff before after --mode project --json report.json --report report.html
```

Pozri:

- `verdict`;
- `material`;
- `representation_only`;
- `risk_relevant_change`;
- `claim_boundary_change`;
- `review_priority`.

### Chceš zistiť, či dva archívy majú rovnaký informačný stav

```powershell
python -m ithz_mcp ithz-diff old.project.ithz new.project.ithz --mode ithz
```

Ak výstup je:

```text
Invariant verdict: EQUIVALENT
Canonical equal: true
```

tak canonical archive stav je rovnaký.

### Chceš HTML report pre review

```powershell
python -m ithz_mcp ithz-diff before after --mode project --report diff_report.html
```

Otvor `diff_report.html` v prehliadači a reviewni tabuľku zmien.

### Chceš output pre ďalšieho agenta

```powershell
python -m ithz_mcp ithz-diff before after --mode project --json diff_report.json
```

Agentovi daj najmä:

- `verdict`;
- `review_priority`;
- `changes`;
- `normalization_rules`.

### Chceš porovnať data-only priečinky

```powershell
python -m ithz_mcp ithz-diff data_before data_after --mode data --ignore-order
```

Použi iba vtedy, keď je poradie riadkov alebo blokov skutočne irelevantné.

## Normalizačné pravidlá

Text:

- normalizuje CRLF/LF;
- odstraňuje trailing whitespace;
- zachováva canonical obsah.

JSON:

- canonicalizuje key order;
- ignoruje timestamp-like metadata kľúče ako `updated_at`, `created_at`,
  `generated_at`, `timestamp`, `mtime`;
- používa stabilný JSON hash.

Markdown:

- vie zachytiť presun sekcií;
- pri rovnakých section units dá structural-only zmenu;
- zmena claim textu môže byť claim-boundary.

Binary:

- binary zmena ide do `UNKNOWN_NEEDS_REVIEW`;
- nástroj ju nepovažuje za ekvivalentnú.

Folder scan:

- ignoruje traversal order;
- v project/folder mode ignoruje `.ithz` archívy;
- `.ithz` porovnávaj cez `--mode ithz`.

## Hranice produktu

ITHZ Invariant Diff netvrdí:

- že rozumie významu každého dokumentu;
- že vie dokázať sémantickú rovnosť ľubovoľných projektov;
- že nahrádza review;
- že nahrádza Git;
- že ITHZ archívy sú všeobecne lepšie ako ZIP/tar.gz/7z;
- že ITHZ-MCP je produkčná databáza alebo cloud sync.

Správne znenie:

```text
canonical/invariant diff with explicit normalizers
```

Nesprávne znenie:

```text
AI understands your project perfectly
```

## Troubleshooting

Help:

```powershell
python -m ithz_mcp ithz-diff --help
```

Ak `.ithz` mode zlyhá, skontroluj archive status:

```powershell
python -m ithz_mcp archive-memory-status --project C:\work\project
```

Ak chýba native exe:

```powershell
$env:ITHZ_NATIVE_EXE="C:\path\to\ithz-native.exe"
```

Ak je výsledok `UNKNOWN_NEEDS_REVIEW`, nejde o chybu. Znamená to, že nástroj
nechce predstierať istotu. Pozri manuálne zmeny v `review_priority` alebo
`changes`.

Ak je `representation_only` nečakane vysoké, pozri `normalization_rules`.
Možno si zapol `--ignore-order` pri vstupe, kde na poradí záleží.

## Najkratší checklist

Projektové priečinky:

```powershell
python -m ithz_mcp ithz-diff before after --mode project --json report.json --report report.html
```

ITHZ archívy:

```powershell
python -m ithz_mcp ithz-diff old.project.ithz new.project.ithz --mode ithz --json report.json
```

Čítaj v tomto poradí:

1. `verdict`;
2. `canonical_equal`;
3. `counts`;
4. `review_priority`;
5. `changes`;
6. `normalization_rules`.

