[English](/docs/receipts) | **Русский**

# Подписанные чеки верификации

<!-- doc-map: reader=user; zone=quality -->

После завершения `tausik verify` записывает компактный, **подписанный
ed25519** документ о том, что именно было проверено, — *чек* (receipt).
Ценность в одной строке:

> можно доказать, что задача действительно была проверена, а не просто заявлена
> проверенной.

Чек привязан к гейтам, которые отработали, и к текущему git `HEAD`. Поскольку
он подписан проектным ключом, «зелёный» вердикт **нельзя подделать или
переиграть** ручной правкой строки в БД или переносом старого результата на
новый коммит. `task done` (QG-2) перед закрытием задачи читает кэшированный
verify-прогон, поэтому подпись и есть доказательство за «зелёным».

Чеки **переносимы** и **проверяемы офлайн**: выгрузите его в JSON-файл,
приложите к PR или артефакту CI — и кто угодно перепроверит подпись без базы
данных, без хранилища ключей и без SDK TAUSIK.

## Как появляется чек

```bash
tausik key init                  # один раз на проект — создаёт пару ключей
tausik verify --task my-feature  # прогоняет гейты и подписывает чек
```

`verify` записывает `verification_run`, а затем выпускает для него чек. Выпуск —
best-effort: на проекте **без** ключа он деградирует до «нет ключа», и
verify-прогон всё равно успешен — просто без подписанного доказательства. В
конце прогона `verify` сообщает результат:

```
Recorded verification_run (task_slug=my-feature, exit=0).
Receipt: signed (run #412, key 9f3c1a2b4d5e6f70).
```

Чек удостоверяет только **фактически отработавшие** гейты — пропущенный
(skipped) гейт ничего не доказывает, поэтому в чек не попадает, даже если для
вердикта он считается «passed».

## Формат конверта (`tausik-signed/v1`)

Подписанный чек — это *конверт* (envelope), оборачивающий канонический чек и его
подпись. Подпись вычисляется по каноническим байтам **только** объекта
`receipt`, а не самого конверта.

```json
{
  "envelope": "tausik-signed/v1",
  "receipt": {
    "schema": "tausik-receipt/v4",
    "task_slug": "my-feature",
    "git_sha": "0123456789abcdef0123456789abcdef01234567",
    "scope": "standard",
    "gates": [
      {"name": "pytest", "passed": true, "severity": "block"},
      {"name": "ruff",   "passed": true, "severity": "warn"}
    ],
    "passed": true,
    "ran_at": "2026-06-13T10:42:07Z",
    "files_hash": "a1b2c3d4...",
    "key_fingerprint": "9f3c1a2b4d5e6f70",
    "declared_scope_status": "under-declared",
    "undeclared_files": ["CHANGELOG.md", "docs/ru/receipts.md"],
    "undeclared_count": 2,
    "files": ["scripts/verify_handle.py", "tests/test_verify_handle.py"],
    "gate_signature": "9c1f0b7a4e2d6538",
    "expires_at": "2026-06-13T11:42:07Z",
    "actor": {
      "session_id": "239",
      "model_id": "claude-opus-5",
      "model_version": null,
      "role": "developer"
    }
  },
  "signature": {
    "algorithm": "ed25519",
    "key_fingerprint": "9f3c1a2b4d5e6f70",
    "value": "<128 hex-символов — 64-байтная подпись ed25519>"
  }
}
```

Пояснения к полям:

- `git_sha` — sha `HEAD` на момент verify, либо `null` вне git-репозитория.
  Именно это привязывает «зелёный» к конкретному коммиту и блокирует перенос на
  новый код.
- `gates[]` — сведены к подписываемой тройке `{name, passed, severity}`.
  Объёмный и недетерминированный вывод гейтов в чек намеренно не входит.
- `passed` — общий вердикт: все непропущенные гейты со `severity: "block"`
  прошли и хотя бы один гейт отработал.
- `key_fingerprint` — первые 16 hex от SHA-256 публичного ключа; то же значение
  показывает `tausik key show`.
- `value` — 128 hex-символов (64-байтная подпись ed25519).

### Честность области (схема v2)

Чек утверждает, что гейты прошли **на некотором наборе файлов**. Три поля ниже
говорят, был ли этот набор полон. Без них чек умалчивал ровно о том, что
подрывает его ценность: агент, объявивший `relevant_files=[README.md]` при
широкой правке, получал подписанный зелёный чек на `README.md`.

- `declared_scope_status` — одно из трёх:
  - `complete` — объявленный набор покрывает всё, что git видит изменённым с
    момента старта задачи;
  - `under-declared` — git видит изменения вне объявленного набора;
  - `unknown` — сравнение **не удалось провести**: вне git-репозитория, при
    пустом `relevant_files`, без `task_created_at` или при сбое вызова git.
- `undeclared_files` — отсортированный список файлов, которые git считает
  изменёнными, а `relevant_files` их не называет. Список ограничен 50 записями.
- `undeclared_count` — полное число таких файлов, **без** усечения. Если оно
  больше длины списка, значит список показан частично.

Три свойства, важных при чтении чужого чека:

1. **`unknown` — это не `complete`.** Отсутствие измерения никогда не
   засчитывается как подтверждённая полнота. Чеки схемы `v1`, выпущенные до
   этого изменения, полей не имеют — их область следует считать
   **непроверенной**, а не полной.
2. **`under-declared` — не признак обмана.** Расхождение возникает практически
   при каждом добросовестном закрытии: правки CHANGELOG, доки, сгенерированных
   констант и бейджей выходят за объявленный набор. Поэтому оно фиксируется,
   но **не блокирует**. Единственное исключение — недообъявленный файл,
   попадающий под security-предикат: гейты со scope по объявленному списку не
   проверили бы его вовсе, поэтому такой прогон падает со статусом
   `scope-security-mismatch` и просит добавить файл в `relevant_files`.
3. **Собственная бухгалтерия задачи против неё не считается.** Два файла
   пишет фреймворк, а не агент, и оба вычитаются до сравнения:
   - `tausik/tasks/<slug>.md`, собственный экспорт задачи — его переписывают
     `started_at`, каждый `task log`, объявленная область и сам чек;
   - `tausik/stories/<родитель>.md`, проекция родительской истории —
     `task start` переводит её `status: open -> active`.

   Только эти два файла ТЕКУЩЕЙ задачи. Чужой экспорт и любая другая история —
   настоящий продукт той задачи, которая их правит, и остаются в списке.
   Родительский ЭПИК не вычитается: замерено, что жизненный цикл задачи его не
   трогает. Если после вычитания не остаётся ничего, причина называет файлы, а
   не утверждает, что дерево не двигалось.
4. **Чужой закоммиченный результат вычитается только при доказательстве в том же коммите.** Активная
   задача может пересекаться с накопительным release-коммитом, но временная метка
   не приписывает ей все пути. Для каждого коммита после `started_at` `verify`
   читает три яруса доказательств и решает каждый изменённый путь на самом
   сильном ярусе, где есть хоть один претендент: один — владелец, два и больше —
   неоднозначность; более слабый ярус не читается, если сильный уже ответил:
   - *тот же коммит* — экспорт другой задачи, закоммиченный вместе с путём,
     объявляет его в `relevant_files`, либо экспорт в статусе
     `active`/`blocked`/`done` и его ACL `scope_paths` покрывает путь;
   - *родительское дерево* — экспорт в статусе `active`/`blocked`/`done`,
     закоммиченный раньше, уже объявлял путь в `relevant_files` (задача вправе
     объявить сначала, а реализацию закоммитить позже);
   - *проекция* — сам путь ЕСТЬ экспорт другой задачи, её родительская история
     или обновление только DYNAMIC-блока в `AGENTS.md`/`CLAUDE.md`.

   Задача никогда не держит рабочую претензию на собственный экспорт, каким бы
   полем он ни был назван. Незакоммиченные пути, повреждённые экспорты, экспорты
   в `planning` и пути с двумя претендентами на решающем ярусе остаются в
   сравнении.

### Что чек говорит о себе (схема v3)

Схема `v2` называла `files_hash` — непрозрачный отпечаток, который можно
**сравнить**, но нельзя **прочитать**. Такой чек не мог ответить на два вопроса,
без которых его нельзя предъявить как доказательство: «над какими файлами?» и
«каким набором гейтов?». Схема `v3` добавляет три поля, и именно они превращают
чек из печати поверх строки в документ.

- `files` — отсортированный список объявленных путей. Именно к нему, а не к
  аргументу вызова `task done`, применяется security-предикат: иначе закрывающий
  мог бы объявить безобидную область, предъявив чек, покрывший `auth/`.
- `gate_signature` — те же 16 hex, что уходят в `verification_runs.command`. Это
  **не** повторное вычисление: подпись набора гейтов берётся из одного источника,
  иначе чек мог бы сойтись сам с собой и разойтись со строкой, которая его
  породила.
- `expires_at` — срок годности **внутри подписи**. Политика, лежащая рядом с
  документом, редактируется вместе с ним; политика внутри подписи — нет.

Чеки схем `v1` и `v2` остаются криптографически валидными, и старый путь
закрытия (поиск свежего прогона) принимает их по-прежнему. Но **предъявить**
такой чек по хендлу нельзя: он читается как **частичный**, и отказ прямо
перечисляет недостающие поля. Неизвестное сообщается как неизвестное — не
округляется ни до «полного», ни до «подделки».

## Хендл прогона — предъявление вместо поиска

Решение #218, приём SEP-2567 «explicit state handles».

**Как было.** `task done` искал в `verification_runs` строку: зелёную, с тем же
`files_hash`, с той же подписью гейтов и моложе 600 секунд. Связь между «я
проверил» и «я закрываю» была *поиском*, а не предъявлением. Три следствия, и
все три — дефекты: содержательный отказ («объявленная область уже изменений по
git») доходил до агента как **промах кэша**; окно свежести принадлежало серверу
и модели видно не было; два процесса с разным состоянием модулей в памяти
считали «свежесть» по-разному.

**Как стало.** `tausik verify --task <slug>` печатает хендл:

```
Verify handle: 4821.9f3c1a2b4d5e6f7089abcdef01234567
  valid until 2026-06-13T11:42:07Z (single use). Present it:
  tausik task done my-feature --ac-verified --verify-handle 4821.9f3c...
```

Хендл — это `<run_id>.<nonce>`, где nonce — 128 бит из `secrets` (требование
SEP-2567). Сервер делает **точечный** lookup по `run_id`, а не поиск по
свежести.

**Срок годности — 3600 секунд (1 час)**, против 600 у прежнего кэша. Это не
ослабление, а следствие того, что часы перестали быть основным критерием:
при погашении `files_hash` пересчитывается по **живым** файлам, а подпись
гейтов — по **живому** конфигу. Дерево, которое сдвинулось, ловится тем, что
действительно изменилось, а не таймером. Часы остались лишь границей того,
сколько непогашенный хендл может висеть. Переопределяется ключом конфига
`verify_handle_ttl_seconds`.

Срок назван в описании инструмента `tausik_verify`, в выводе CLI и в поле
`expires_at` самого чека — по прямому требованию SEP-2567: «A policy only in
server documentation is not visible to the model».

### Проверка при предъявлении — fail-closed

Каждый пункт отказывает, ни один не проходит молча:

| Условие | Отказ говорит |
|---|---|
| хендл не той формы | ожидался `<run_id>.<32-hex>` |
| прогона нет в этой БД | хендл выпущен другим проектом |
| nonce не совпал (сверка constant-time) | хендлы одноразовы и заменяются каждым verify |
| прогон красный | красный прогон не даёт права закрыть задачу |
| прогон верифицировал другую задачу | хендл действителен для задачи, под которую выпущен |
| прогон помечен `noncacheable\|` | записан для аудита, а не как сертификат |
| хендл уже погашен | одноразовость (replay, SEP-2322) |
| срок истёк / срок нечитаем | нечитаемый срок **не** трактуется как «без срока» |
| у проекта нет пригодного публичного ключа | путь через хендл ЗАКРЫТ; это **именованный режим**, а не провалившаяся проверка — либо `tausik key init`, либо закрывать без `--verify-handle` |
| чека нет / битый JSON / плохая подпись | предъявлять нечего |
| чек подписан на другую задачу, чем строка прогона | подменённый чек |
| `ran_at` чека не совпадает со строкой прогона | подменённый чек |
| чек схемы v1/v2 | перечисляются недостающие поля v3 |
| `files` покрывают security-путь | такие области перепроверяются при каждом закрытии |
| `files_hash` по живым файлам разошёлся | **содержательный** отказ, а не промах кэша |
| `files_hash` чека разошёлся со строкой прогона | документ и запись описывают разные наборы файлов |
| подпись гейтов разошлась со строкой или с живым конфигом | чек удостоверяет уже не тот набор гейтов |
| git видит изменённым security-файл, которого чек НЕ называет | гейты со scope по списку чека этот файл не смотрели вовсе |

**И `verify` никогда не выдаёт того, что эта таблица отвергнет.** Хендл
чеканится только тогда, когда чек, за который он стоит, ПОДПИСАН (GitLab #15).
Две разные строки заменяют готовую к копированию команду `--verify-handle`,
которую `task done` обязан был отвергнуть: в проекте без ключа —
«Verify handle: none — no project key, so no signed receipt (tausik key init
enables them)»; при ключе, которым не удалось подписать, — «Verify handle: none
— the receipt could not be signed (see .tausik/tausik.log, tausik key show)».
Обе заканчиваются рабочей командой закрытия — `task done <slug> --ac-verified`,
поиск по свежести. CLI и `tausik_verify` рисуют это одним рендером.

Одно расхождение НЕ блокирует и это намеренно: если git видит изменения вне
области чека, но ни одно из них не security-чувствительно, хендл засчитывается,
а расхождение попадает в текст вердикта (решение #138 — оно срабатывает почти
при каждом добросовестном закрытии: CHANGELOG, доки, сгенерированные константы).
Расхождение, которого никто не видит, равно неизмеренному, поэтому оно
проговаривается вслух.

Погашение атомарно: `UPDATE ... WHERE handle_redeemed_at IS NULL` с проверкой
`rowcount`, поэтому два одновременных закрытия не могут оба увидеть непогашенный
хендл.

**Проверяется на гейте, ТРАТИТСЯ при закрытии.** Хендл списывается внутри той же
транзакции, что пишет `status='done'`, а не в момент проверки. Разница видна,
когда закрытие проходит Verify-First и падает на ПОЗДНЕЙШЕЙ проверке: раньше
хендл уже был потрачен, и полутораминутный прогон verify сгорал ради задачи,
которая не закрылась. Ничего при этом не удостоверялось, значит и безопасности
трата не покупала. Одноразовость нужна для того, чтобы один зелёный не закрыл
две задачи, — а это свойство ЗАКРЫТИЯ, не прохождения гейта. Откат транзакции
возвращает хендл в непогашенное состояние вместе со всем остальным.

**Совместимость.** `task done` **без** `--verify-handle` работает как раньше —
через поиск свежего прогона. Тихое ужесточение недопустимо: хендл меняет способ
**предъявления** зелёного, а не то, какие зелёные засчитываются.

**Чего хендл не даёт.** Это не авторизация. Приватный seed лежит в рабочем
дереве (см. «Что подпись НЕ доказывает» ниже), поэтому агент способен выпустить
подпись, которую ключ примет. Задача хендла — сделать связь «проверил →
закрываю» явной и проверяемой, а replay — счётным; не удержать решительного
агента. Именно поэтому всё, что проверял прежний поиск, здесь **пересчитывается
заново по живому состоянию**, а не берётся на веру из предъявленного документа
(SEP-2322: «servers MUST always validate that state, as the client is an
untrusted intermediary»).

Аудит непогашенных хендлов:

```sql
SELECT id, task_slug, handle_expires_at FROM verification_runs
WHERE handle_nonce IS NOT NULL AND handle_redeemed_at IS NULL;
```

Чек **каноничен** (в духе JCS / RFC 8785): ключи отсортированы на каждом уровне,
без пробелов, только ASCII, числа с плавающей точкой отвергаются. Один и тот же
логический чек всегда сериализуется в одни и те же байты, поэтому подпись
проверяется одинаково на любой машине и платформе.

## Управление ключами

```bash
tausik key init    # создать проектную пару ed25519 (не перезапишет существующую)
tausik key show    # показать публичный ключ и отпечаток (никогда — seed)
```

Ключи лежат в `.tausik/keys/`:

| Файл | Содержимое | Можно делиться? |
|---|---|---|
| `project.key` | приватный 32-байтный seed (`ed25519:<64 hex>`) | **Нет** — не покидает машину; `.tausik/` в gitignore |
| `project.pub` | публичный ключ (`ed25519:<64 hex>`) | Да — раздавайте по доверенному каналу для проверки |

Ротация — `tausik key init --force`. Учтите: **существующие подписи перестанут
проверяться** против нового ключа.

## Работа с чеками

### `tausik receipt show`

Показать последний сохранённый конверт для задачи (или конкретного прогона) и
перепроверить его подпись против проектного ключа.

```bash
tausik receipt show --task my-feature      # либо: --run 412
tausik receipt show --task my-feature --json   # сырой JSON конверта
```

Коды выхода: `0` — валидна, `1` — подпись **невалидна** (изменены данные или
подпись), `2` — не найдено / нет ключа.

### `tausik receipt export`

Сформировать самодостаточный переносимый артефакт — конверт плюс встроенный
публичный ключ — для PR или внешнего аудита. Экспорт откажется работать, если
сохранённая подпись не проверяется против текущего ключа (испорченная строка
или сменённый ключ).

```bash
tausik receipt export --task my-feature           # пишет в .tausik/receipts/
tausik receipt export --task my-feature --out receipt.json
tausik receipt export --task my-feature --stdout  # вывести, а не записывать
```

Экспорт оборачивает конверт в артефакт `tausik-receipt-export/v1`, встраивающий
публичный ключ, — его можно проверить где угодно:

```json
{
  "export": "tausik-receipt-export/v1",
  "envelope": { "...tausik-signed/v1, без изменений..." },
  "public_key": "ed25519:<64 hex>",
  "key_fingerprint": "9f3c1a2b4d5e6f70"
}
```

### `tausik receipt verify <file>`

Офлайн-проверка целостности экспортированного артефакта — **без базы данных, без
хранилища ключей, без SDK**. По умолчанию используется публичный ключ, встроенный
в файл. Чтобы не доверять этому ключу, передайте свой по доверенному каналу:

```bash
tausik receipt verify receipt.json
tausik receipt verify receipt.json --pub ed25519:7c2f...e0
```

Коды выхода: `0` — валидна, `1` — настоящий артефакт с плохой подписью, `2` —
файл не является корректным артефактом экспорта.

## Модель доверия

Подпись доказывает **целостность** — чек не изменялся после подписания. Сама по
себе она **не** доказывает **происхождение**: встроенный отпечаток доверия
ровно столько, сколько файл, в котором он едет. Чтобы привязать происхождение,
сверьте `key_fingerprint` с доверенным каналом — выводом `tausik key show`,
зафиксированной переменной CI или описанием PR — и никогда не доверяйте
отпечатку, встроенному в тот же артефакт, который вы проверяете.

### Что подпись НЕ доказывает — граница ключа

Формулировка здесь юридически значима с учётом EU AI Act (обязательства по
логированию для high-risk-систем действуют с августа 2026), поэтому важна
точность. Приватный seed лежит в `.tausik/keys/project.key` **внутри рабочего
дерева** — того самого, которое читает агент, чью работу этот ключ подписывает
(`mode 0600` — best-effort на POSIX и no-op на Windows). Отсюда:

- Валидная подпись — это **tamper-evidence против ВНЕШНИХ правок** `tausik.db`:
  никто не переписал «зелёный» вердикт и не перенёс старый результат на новый
  коммит *без доступа к ключу*. То же верно для подписи `events_anchor` над
  цепочкой событий.
- Это **НЕ attestation против агента**. Агент (или что угодно) с доступом на
  чтение рабочего дерева может прочитать seed и выпустить подпись, которую ключ
  примет. Чек доказывает «это произвёл кто-то с доступом к файловой системе», а
  не «независимая сторона свидетельствует, что агент вёл себя честно».

Чтобы получить attestation, который агент не может подделать, ключ подписи
обязан лежать **вне зоны записи (и чтения) агента** — managed-путь, OS-keychain
или отдельный процесс-подписант. Этот вынос осознанно отложен (см. запись
`tausik decide` по `l26-signing-key-boundary`): это самостоятельный
кросс-платформенный дизайн key-custody, а немедленный выигрыш по целостности —
честно назвать эту границу, а не подразумевать attestation, который текущее
хранилище дать не может.

## Офлайн / проверка без SDK по HTTP

Для агентов и CI, которым недоступны CLI или MCP, `tausik serve` отдаёт то же
подписание и проверку через stateless HTTP-эндпоинт — отправьте результаты
гейтов и получите тот же чек `tausik-signed/v1`. Эндпоинты, клиент на stdlib и
сниппет для GitHub Actions — в [no-sdk-verify.md](https://github.com/Kibertum/tausik-core/blob/v1.11.0/docs/ru/no-sdk-verify.md).

## Смотрите также

- [cli.md](https://github.com/Kibertum/tausik-core/blob/v1.11.0/docs/ru/cli.md) — полный справочник CLI (`key`, `verify`, `receipt`).
- [mcp.md](/ru/docs/mcp) — эквивалентные MCP-инструменты.
- [no-sdk-verify.md](https://github.com/Kibertum/tausik-core/blob/v1.11.0/docs/ru/no-sdk-verify.md) — HTTP-эндпоинт верификации (`tausik serve`).
- [senar.md](/ru/docs/senar) — принцип verify-first из SENAR, стоящий за QG-2.


## Кто делал работу (`actor`, v4)

Чек подписывается ключом **проекта** и отвечает, какие гейты прошли на каком
состоянии кода. До v4 он не отвечал, КТО их прогнал, — а весь контроль качества
стоит на разделении обязанностей: внешний ревьюер на другой модели, а с приходом
P8 ещё и «автор теста не есть исполнитель». Всё это было объявлено и ничем не
предъявлено.

Замер, из-за которого поле появилось: 1686 чеков, ни одного поля о деятеле;
`claimed_by` пуст у всех 1574 задач; задач с известными стартовой и закрывающей
моделью — 29, и модели **не различаются ни в одной**. То есть на пути verify
разделения не просто не засвидетельствовано — его там нет.

`actor` есть **содержимое** подписанного чека, а не второй подписант. Второй
ключ означал бы управление ключами агентов и реестр идентичностей; ни того, ни
другого не заводится, ключи остаются локальными. Поле входит в канонические
байты, поэтому подменить деятеля, не сломав подпись, нельзя.

**Сравнение двух чеков даёт ТРИ исхода, а не два:** `same`, `different` и
`unknown`. Чек без поля `actor` — это не чек другого деятеля, и проверка вида
`!= same` засчитала бы каждый из 1686 старых чеков как разделённый. Требовать
надо `different` явно.

**Граница.** Чек записывает деятеля **прогона проверки**. Он не говорит, кто
писал тест, а кто код: это предмет P8. Предъявлять это поле как доказательство
такого утверждения нельзя.

Чеки v1–v3 остаются валидными: поле добавляется, а не требуется. `actor`
намеренно не входит в `V3_REQUIRED_FIELDS` — иначе 1686 закрытий разом перестали
бы читаться.
