# Pakiet dowodów: co musi udowodnić pull request agenta

URL: https://developertoolkit.ai/pl/workflows/ship/evidence-bundle/
Description: Kontrakt pull requesta agenta: zmiana specyfikacji, wyniki akceptacji, sprawdzenia, dowody z działania, klasa ryzyka, pochodzenie i wymuszający go check CI.

Pakiet dowodów (evidence bundle) to ustrukturyzowany blok w pull requeście agenta, który dowodzi zmiany: link do specyfikacji i zmiana zachowania, każde kryterium akceptacji przypisane do sprawdzenia, które się wykonało, wyniki poleceń, dowody z działania lub ewaluacji, klasa ryzyka, wrażliwe ścieżki, zmiany wyroczni i pochodzenie. Check w CI parsuje pakiet i blokuje merge, gdy jest niekompletny.

Agenci twojego zespołu otwierają kilkanaście pull requestów dziennie, a każdy opis brzmi tak samo: „Zaimplementowałem paginację, dodałem testy, wszystkie checki przechodzą”. Trzy z nich po cichu zmieniły fixture testowe, jeden dotknął webhooka płatności, a żaden nie mówi, którego kryterium akceptacji dowodzi który test. Nie odróżnisz bezpiecznych od ryzykownych bez czytania każdego diffa, a właśnie tę pracę agenci mieli ci oszczędzić.

Ta strona jest dla **programistów**, którzy konfigurują agentów, **tech leadów**, którzy odpowiadają za zasady review, i **CTO**, którzy potrzebują jednego zapisu audytowego na każdą zmianę. To kanoniczny schemat manifestu zmiany w całym serwisie: [pochodzenie zmian i routing według ryzyka](/pl/cto-scorecard-guide/ai-pr-labeling/) kieruje zmiany na podstawie tych pól, a [czytanie dowodów zamiast kodu](/pl/ladder/evidence-not-diffs/) wyjaśnia, jak recenzent je czyta.

## Co daje ci pakiet dowodów

- **Schemat pole po polu**, z informacją, kto wypełnia każde pole i jak CI je weryfikuje.
- **Szablon pull requesta**, który agenci i ludzie wypełniają tak samo.
- **Przetestowany check CI** (około 80 linii Node), który oblewa niekompletny pakiet i przelicza klasę ryzyka z diffa.
- **Tabelę routingu**, która zamienia klasę ryzyka w odpowiedź na pytania, kto zatwierdza i kto musi czytać kod.
- **Trzy prompty do skopiowania**: przygotuj pakiet, zaudytuj pakiet względem diffa, napraw oblany check.
- **Tryby awarii** bramki opartej na pakiecie i sposób wyjścia z każdego z nich.

## Dlaczego opis pull requesta nie jest dowodem

Opis to proza, którą agent napisał o własnej pracy. Może być błędny w sposób, którego nikt nie zauważy aż do produkcji. Skala, przy której ma to znaczenie, została zmierzona: raport *Acceleration Whiplash* firmy Faros AI (kwiecień 2026; telemetria z 22 000 programistów i ponad 4000 zespołów; telemetria dostawcy z bazy klientów Faros) pokazał wzrost mediany czasu w review o 441,5% i o 31,3% więcej pull requestów scalanych bez żadnego review. Generowanie się przeskalowało, czytanie nie.

Rozwiązaniem jest wymaganie wyników sprawdzeń zamiast deklaracji o nich. Jak ujął to jeden z praktyków: „Model może przekonywać, że jego praca jest skończona. Deterministyczny walidator może udowodnić, że brakuje wymaganego pola” (tłum. własne; oryginał: „A model can argue that its work is complete. A deterministic validator can prove that a required field is missing.”; NARESH, *Graph Engineering for AI Coding Agents*, DEV Community, 30 lipca 2025). Pakiet jest tym, co taki walidator czyta.

## Co zawiera pakiet dowodów?

Pakiet ma siedem sekcji. Sednem projektu jest kolumna **Weryfikacja w CI**: każde pole, w którym agent mógłby pomylić się na swoją korzyść, jest albo przeliczane z diffa, albo sprawdzane względem gałęzi.

| Sekcja | Pola | Kto wypełnia | Weryfikacja w CI | Kiedy wymagana |
| ------ | ---- | ------------ | ---------------- | -------------- |
| **Specyfikacja** | `spec.link`, `spec.delta` (zmiany zachowania prostymi zdaniami), `spec.unrequested` | Agent, na podstawie zgłoszenia lub `spec.md` | Link to URL albo plik istniejący w gałęzi; delta nie jest pusta | Zawsze |
| **Akceptacja** | Jeden wpis na kryterium: `criterion`, `check` (`plik:linia` albo polecenie), `result` | Agent, po uruchomieniu sprawdzeń | Każdy `result` to `pass`; każdy cytowany plik istnieje | Zawsze |
| **Sprawdzenia** | `command`, `exit_code`, opcjonalnie `summary` (np. wynik testów mutacyjnych) | Agent | Każdy `exit_code` to 0. CI uruchamia też własne wymagane joby; pakiet nigdy ich nie zastępuje | Zawsze |
| **Działanie** | `kind` (`screenshot`, `trace`, `video`, `preview-url`), `ref`, `covers` (identyfikatory kryteriów) | Agent, z podglądu lub przebiegu w przeglądarce | Obecne, gdy zmieniły się ścieżki UI | Gdy pasują globy z polityki |
| **Ewaluacje** | `suite`, `score`, `baseline` | Agent albo job ewaluacyjny w CI | `score` ≥ `baseline` | Gdy zmieniły się prompty, konfiguracja modelu lub harness agenta |
| **Ryzyko** | `class` (`low`, `standard`, `high`), `touches` (klasy wrażliwe), `oracle_changes` (ścieżka, kierunek, powód), `rollback` | Agent proponuje | CI przelicza klasy wrażliwe i pliki wyroczni z diffa, ustala próg i oblewa niższą deklarację | Zawsze |
| **Pochodzenie** | `agent` (narzędzie i wersja), `model`, `session`, `task`, `human_owner` | Agent oraz człowiek, który odpowiada za zmianę | `agent`, `model` i `human_owner` są wypełnione | Zawsze |

Trzy zasady pilnują uczciwości schematu:

1. **Zadeklarowana klasa ryzyka może tylko podnieść wyliczony próg.** Agent, który wpisze `class: low` przy zmianie w płatnościach, obleje check; człowiek, który oznaczy nieszkodliwą zmianę jako `high`, dostanie surowsze review i to jest dozwolone.
2. **Zmiana wyroczni nigdy nie jest domyślnie neutralna.** Każdy edytowany test, snapshot, workflow CI, konfiguracja lintera lub typów musi trafić na listę z kierunkiem (`direction`) `stricter`, `looser` albo `neutral`. Wpis `looser` wymusza `high`, bo zmienia znaczenie „zielonego” dla każdej innej zmiany.
3. **Pochodzenie się zapisuje, ale nie steruje routingiem.** Zmiany ludzi, zmiany wspierane przez AI i zmiany agentów używają tego samego pakietu i tego samego routingu. [Strona o pochodzeniu i routingu](/pl/cto-scorecard-guide/ai-pr-labeling/) wyjaśnia, dlaczego autorstwo jest słabym wskaźnikiem ryzyka.

## Jak skonfigurować bramkę pakietu dowodów?

Konfiguracja to pięć plików. Dodaj je w jednym pull requeście, scal go, a dopiero potem ustaw check jako wymagany. Kolejność ma znaczenie, co wyjaśnia sekcja o trybach awarii.

1. **Dodaj szablon pull requesta.** GitHub wypełnia opis pull requestów otwieranych w interfejsie webowym treścią `.github/pull_request_template.md`. Agenci, którzy otwierają pull requesty z wiersza poleceń, dostają tę samą strukturę z promptu do pakietu niżej, który wskazuje im ten plik.

    ```markdown
    <!-- .github/pull_request_template.md -->
    ## What changed and why

    <!-- Two or three sentences for a human. The bundle below is the evidence. -->

    ## Evidence bundle

    ~~~yaml
    evidence_bundle: 1
    spec:
      link: docs/specs/orders-pagination.md      # or the issue URL
      delta:
        - GET /orders returns 50 items per page and a next_cursor
        - The old page parameter returns 400
      unrequested: []                            # behavior nobody asked for
    acceptance:
      - criterion: "AC1: first page has 50 items and a next_cursor"
        check: tests/orders.contract.test.ts:42
        result: pass                             # pass | fail | unverified
      - criterion: "AC2: the page parameter returns 400"
        check: tests/orders.contract.test.ts:88
        result: pass
    checks:
      - command: npm test
        exit_code: 0
      - command: npx stryker run --mutate "src/orders/**/*.ts"
        exit_code: 0
        summary: 81% mutation score on changed files
    evals: []                                    # suite, score, baseline
    runtime: []                                  # kind, ref, covers
    risk:
      class: standard                            # low | standard | high
      touches: []                                # auth, money, schema, migrations, infra
      oracle_changes:
        - path: tests/orders.contract.test.ts
          direction: stricter                    # stricter | looser | neutral
          reason: new contract cases for AC1 and AC2
      rollback: revert the merge commit; no migration, no flag
    provenance:
      agent: Claude Code 2.1.283
      model: claude-opus-5-5
      session: https://claude.ai/code/session_EXAMPLE
      task: https://github.com/acme/shop/issues/412
      human_owner: "@anna"
    ~~~
    ```

2. **Napisz plik polityki.** Nazywa klasy wrażliwe z ich minimalnym ryzykiem, ścieżki wyroczni oraz ścieżki, które wymagają dowodów z działania lub ewaluacji. Dopasuj globy do swojego repozytorium; te odpowiadają [klasom eskalacji](/pl/ladder/evidence-not-diffs/), których używa reszta serwisu.

    ```yaml
    # .github/evidence-policy.yml (owned by CODEOWNERS; editing it is an oracle change)
    sensitive:
      auth:       { globs: ['**/auth/**', '**/middleware/**', '**/*permission*'], min_risk: high }
      money:      { globs: ['**/billing/**', '**/payments/**', '**/pricing/**'], min_risk: high }
      schema:     { globs: ['**/*.sql', '**/openapi*', '**/*.proto'], min_risk: high }
      migrations: { globs: ['**/migrations/**'], min_risk: high }
      infra:      { globs: ['infra/**', '**/*.tf', '.github/workflows/**'], min_risk: standard }
    oracle:
      - '**/*.test.*'
      - '**/__snapshots__/**'
      - '.github/workflows/**'
      - '.github/evidence-policy.yml'
      - '.github/CODEOWNERS'
      - 'scripts/check-evidence.mjs'
      - 'tsconfig*.json'
      - 'eslint.config.*'
    runtime_required:
      - 'src/components/**'
      - 'src/pages/**'
    evals_required:
      - 'prompts/**'
    ```

3. **Dodaj skrypt sprawdzający.** Czyta treść pull requesta ze zdarzenia GitHuba, parsuje pierwszy blok `yaml` zaczynający się od `evidence_bundle:` i porównuje go z diffem. Zależy od `yaml` (2.9.1 w npm) i `minimatch` (10.2.6 w npm); obie wersje sprawdzone 2026-09-26.

    ```js
    // scripts/check-evidence.mjs: fails a pull request whose evidence bundle is
    // missing, incomplete, or contradicted by the diff. Usage:
    //   node check-evidence.mjs <policy.yml>
    import { appendFileSync, existsSync, readFileSync } from 'node:fs';
    import { execFileSync } from 'node:child_process';
    import { parse } from 'yaml';
    import { minimatch } from 'minimatch';

    const RANK = { low: 0, standard: 1, high: 2 };
    const policy = parse(readFileSync(process.argv[2], 'utf8'));
    const pr = JSON.parse(readFileSync(process.env.GITHUB_EVENT_PATH, 'utf8')).pull_request;
    const errors = [];
    const fail = (msg) => errors.push(msg);

    // 1. What CI knows without asking the agent: the changed files.
    const changed = (process.env.EVIDENCE_CHANGED_FILES ??
      execFileSync('git', ['diff', '--name-only', `${pr.base.sha}...HEAD`], { encoding: 'utf8' }))
      .split('\n').filter(Boolean);
    const touching = (globs) => changed.filter((f) => globs.some((g) => minimatch(f, g, { dot: true })));

    // 2. The bundle: the first yaml fence (backticks or tildes) that starts with evidence_bundle:
    const block = (pr.body ?? '').match(/(`{3}|~{3})ya?ml\r?\n(evidence_bundle:[\s\S]*?)\1/);
    if (!block) {
      console.error('No evidence bundle found. Fill in the template from .github/pull_request_template.md.');
      process.exit(1);
    }
    const b = parse(block[2]) ?? {};

    // 3. Spec link and delta
    if (!b.spec?.link) fail('spec.link is empty');
    else if (!/^https?:\/\//.test(b.spec.link) && !existsSync(b.spec.link)) fail(`spec.link ${b.spec.link} does not exist`);
    if (!b.spec?.delta?.length) fail('spec.delta lists no behavior change');

    // 4. Acceptance: every criterion names a check that exists and passed
    if (!b.acceptance?.length) fail('acceptance is empty');
    for (const a of b.acceptance ?? []) {
      if (a.result !== 'pass') fail(`acceptance "${a.criterion}" is ${a.result ?? 'missing a result'}`);
      const ref = /^([^\s:]+):(\d+)$/.exec(a.check ?? '');
      if (!a.check) fail(`acceptance "${a.criterion}" names no check`);
      else if (ref && !existsSync(ref[1])) fail(`acceptance "${a.criterion}" cites ${ref[1]}, which is not in the branch`);
    }
    for (const c of b.checks ?? []) if (c.exit_code !== 0) fail(`check "${c.command}" exited ${c.exit_code}`);
    if (!b.checks?.length) fail('checks lists no command that ran');

    // 5. Sensitive paths: CI recomputes them and sets the risk floor
    let floor = 'low';
    const declared = new Set(b.risk?.touches ?? []);
    for (const [name, rule] of Object.entries(policy.sensitive)) {
      const hits = touching(rule.globs);
      if (!hits.length) continue;
      if (!declared.has(name)) fail(`diff touches ${name} (${hits.join(', ')}) but risk.touches omits it`);
      if (RANK[rule.min_risk] > RANK[floor]) floor = rule.min_risk;
    }

    // 6. Oracle changes: every edited test, CI or lint file is declared with a direction
    const listed = new Map((b.risk?.oracle_changes ?? []).map((o) => [o.path, o.direction]));
    for (const f of touching(policy.oracle)) {
      const dir = listed.get(f);
      if (!dir) fail(`oracle file ${f} changed but is not in risk.oracle_changes`);
      else if (!['stricter', 'looser', 'neutral'].includes(dir)) fail(`oracle change ${f} has direction ${dir}; use stricter, looser or neutral`);
      if (RANK[floor] < RANK.standard) floor = 'standard';
      if (dir === 'looser') floor = 'high';
    }

    // 7. Runtime evidence and evals, where the policy requires them
    if (touching(policy.runtime_required).length && !b.runtime?.length) fail('UI paths changed but runtime lists no screenshot or trace');
    if (touching(policy.evals_required).length) {
      if (!b.evals?.length) fail('prompt or model paths changed but evals is empty');
      for (const e of b.evals ?? []) if (!(e.score >= e.baseline)) fail(`eval ${e.suite} scored ${e.score} against baseline ${e.baseline}`);
    }

    // 8. Risk class and provenance
    if (!Object.hasOwn(RANK, b.risk?.class ?? '')) fail('risk.class must be low, standard or high');
    else if (RANK[b.risk.class] < RANK[floor]) fail(`risk.class is ${b.risk.class}, but the diff requires at least ${floor}`);
    if (!b.risk?.rollback) fail('risk.rollback is empty');
    for (const k of ['agent', 'model', 'human_owner']) if (!b.provenance?.[k]) fail(`provenance.${k} is empty`);

    const risk = RANK[b.risk?.class] > RANK[floor] ? b.risk.class : floor;
    if (process.env.GITHUB_OUTPUT) appendFileSync(process.env.GITHUB_OUTPUT, `risk=${risk}\n`);
    console.log(`Changed files: ${changed.length}. Risk class: ${risk}.`);
    if (errors.length) {
      console.error(`Evidence bundle incomplete (${errors.length}):\n- ${errors.join('\n- ')}`);
      process.exit(1);
    }
    console.log('Evidence bundle complete.');
    ```

4. **Dodaj workflow.** Dwa szczegóły sprawiają, że można mu ufać. Ładuje skrypt i politykę z commita **bazowego**, więc pull request nie osłabi skryptu ani polityki, które go oceniają. Sam plik workflow uruchamia się jednak z pull requesta, dlatego krok 5 daje katalogowi `.github/workflows/` właściciela kodu i wymaga review od właścicieli kodu (albo robisz z niego workflow wymagany przez ruleset). Checkout ustawia `persist-credentials: false`, więc token nie trafia do `.git/config`; `gh pr edit` czyta `GH_TOKEN` z własnego kroku. Uruchamia się też na `edited`, więc poprawienie opisu ponownie uruchamia check bez nowego pusha.

    ```yaml
    # .github/workflows/evidence-bundle.yml
    name: evidence-bundle
    on:
      pull_request:
        types: [opened, edited, synchronize, reopened, ready_for_review]
    permissions:
      contents: read
      pull-requests: write
    jobs:
      evidence:
        runs-on: ubuntu-latest
        steps:
          - uses: actions/checkout@v7
            with:
              fetch-depth: 0
              persist-credentials: false
          - uses: actions/setup-node@v7
            with:
              node-version: 24
          - name: Load the checker and policy from the base branch
            run: |
              mkdir -p /tmp/evidence
              git show "${{ github.event.pull_request.base.sha }}:scripts/check-evidence.mjs" > /tmp/evidence/check.mjs
              git show "${{ github.event.pull_request.base.sha }}:.github/evidence-policy.yml" > /tmp/evidence/policy.yml
              npm install --prefix /tmp/evidence --no-save yaml@2.9.1 minimatch@10.2.6
          - name: Check the evidence bundle
            id: check
            run: node /tmp/evidence/check.mjs /tmp/evidence/policy.yml
          - name: Label the risk class
            if: always() && steps.check.outputs.risk != ''
            env:
              GH_TOKEN: ${{ github.token }}
              RISK: ${{ steps.check.outputs.risk }}
              PR_NUMBER: ${{ github.event.pull_request.number }}
            run: |
              STALE=$(printf 'risk:%s\n' low standard high | grep -vx "risk:$RISK" | paste -sd, -)
              gh pr edit "$PR_NUMBER" --remove-label "$STALE" --add-label "risk:$RISK"
    ```

    Utwórz raz etykiety `risk:low`, `risk:standard` i `risk:high`; `gh pr edit --add-label` nie tworzy brakujących etykiet. Krok zdejmuje też dwie pozostałe etykiety `risk:*`, bo samo `--add-label` nigdy żadnej nie usuwa: pull request, który po pushu przechodzi ze `standard` do `high`, miałby inaczej obie, a wszystko, co kieruje zmiany według etykiet, odczytałoby nieaktualną klasę.

5. **Ustaw check jako wymagany i chroń bramkę.** W rulesecie gałęzi `main` wymagaj statusu `evidence` i review od właścicieli kodu. Potem daj właściciela, który nie jest agentem, trzem grupom ścieżek: plikom samej bramki (łącznie z samym `CODEOWNERS`, promptami i szablonem pull requesta, bo GitHub stosuje `CODEOWNERS` z gałęzi bazowej, więc pull request, który go edytuje, mógłby inaczej bez review usunąć własnego właściciela), każdemu globowi z `min_risk: high` oraz **chronionym wyroczniom**: testom akceptacyjnym lub kontraktowym, które kodują specyfikację, i konfiguracji typów oraz lintera dla całego repozytorium. To właśnie egzekwuje wiersz `high` w tabeli routingu dla tych ścieżek: wymagane review właściciela kodu obejmuje każdy pull request, który ich dotyka, niezależnie od etykiety.

    Nie dawaj właściciela każdej ścieżce `**/*.test.*` ani snapshotom. Zwykłe testy zmieniają się w większości pull requestów `standard`, więc objęcie ich własnością postawiłoby każdy z nich przed właścicielem kodu i zlikwidowało ścieżkę z jednym recenzentem. Takie zmiany nadal trafiają do `risk.oracle_changes` i czyta je recenzent `standard`. Jedno ograniczenie: zmiana `looser` w teście bez właściciela podnosi klasę do `high`, a etykietę do `risk:high`, ale `CODEOWNERS` nie widzi etykiet, więc nic nie wymusza na niej właściciela kodu. Recenzent eskaluje ją ręcznie, a test, którego osłabienie byłoby kosztowne, powinien leżeć na chronionej ścieżce.

    ```text
    # .github/CODEOWNERS
    .github/evidence-policy.yml     @acme/platform
    .github/workflows/              @acme/platform
    scripts/check-evidence.mjs      @acme/platform
    .github/CODEOWNERS              @acme/platform
    .github/prompts/                @acme/platform
    .github/pull_request_template.md  @acme/platform
    # Every min_risk: high glob in the policy
    **/auth/**                      @acme/security
    **/middleware/**                @acme/security
    **/*permission*                 @acme/security
    **/billing/**                   @acme/payments
    **/payments/**                  @acme/payments
    **/pricing/**                   @acme/payments
    **/*.sql                        @acme/data
    **/openapi*                     @acme/data
    **/*.proto                      @acme/data
    **/migrations/**                @acme/data
    # Protected oracles only: spec-level tests and repo-wide config
    **/*.contract.test.*            @acme/platform
    tsconfig*.json                  @acme/platform
    eslint.config.*                 @acme/platform
    ```

### Skąd wiesz, że sam skrypt sprawdzający działa?

Testuj bramkę tak jak każdą wyrocznię: fixture’ami, które muszą przejść, i fixture’ami, które muszą oblać. Zmienna `EVIDENCE_CHANGED_FILES` zastępuje `git diff`, więc fixture potrzebuje tylko sztucznego pliku zdarzenia i listy ścieżek:

```bash
# Terminal, repository root. ev-billing.json holds {"pull_request":{"base":{"sha":"x"},"body":"..."}}
GITHUB_EVENT_PATH=fixtures/ev-billing.json \
EVIDENCE_CHANGED_FILES=$'src/billing/refund.ts\nsrc/pages/orders.astro' \
node scripts/check-evidence.mjs .github/evidence-policy.yml
```

Uruchomiony na szablonie z góry, ze zmienionym plikiem płatności i stroną UI oraz z cytowanymi plikami specyfikacji i testu (`docs/specs/orders-pagination.md`, `tests/orders.contract.test.ts`) obecnymi w gałęzi, skrypt kończy się kodem 1 i trzema błędami: `risk.touches` pomija `money`, `runtime` jest puste oraz `risk.class is standard, but the diff requires at least high`. Trzymaj jeden fixture na każdą regułę (brak pakietu, niezweryfikowane kryterium, brak cytowanego pliku testu, niezadeklarowana zmiana wyroczni, zmiana wyroczni `looser`, brak ewaluacji) i uruchamiaj je w zwykłym jobie testowym. Zmiana bramki, która psuje fixture, zostanie wyłapana, zanim trafi do `main`.

## Kto zatwierdza każdą klasę ryzyka?

Pakiet rozstrzyga, kto robi review i co czyta. Ta tabela to polityka na start; wersja dla całej organizacji należy do [polityki autonomii i klas ryzyka](/pl/org/governance-autonomy/).

| Klasa ryzyka | Typowy wyzwalacz | Zatwierdzenie | Kto czyta kod | Po merge’u |
| ------------ | ---------------- | ------------- | ------------- | ---------- |
| `low` | Dokumentacja, teksty, izolowany UI z dowodami z działania, bez zmian wyroczni | Jeden recenzent na podstawie pakietu albo reguła zatwierdzania (zob. zakładkę Cursor) | Domyślnie nikt; próbkowanie według [dziennika zaufania](/pl/ladder/evidence-not-diffs/) | Zwykły deploy |
| `standard` | Zmiana zachowania w pokrytym kodzie; zmiany wyroczni `stricter` lub `neutral`; infrastruktura | Jeden recenzent na podstawie pakietu plus [ustalenia agenta recenzującego](/pl/workflows/ship/agent-pr-review/) | Recenzent czyta zmiany wyroczni i każde zachowanie z `unrequested` | Canary lub flaga, jeśli są dostępne |
| `high` | Uwierzytelnianie, pieniądze, schematy, migracje, zmiana wyroczni `looser` | Właściciel kodu z `CODEOWNERS` | Wskazany właściciel czyta kod, oprócz pakietu | Stopniowe wdrożenie i [bramka zatwierdzenia produkcyjnego](/pl/developer-scorecard-guide/production-approval-gate/) |

Ścieżki wpisane do `CODEOWNERS` (pliki samej bramki, wrażliwe globy i chronione wyrocznie) wymagają swojego właściciela kodu niezależnie od klasy. Zmiana zwykłego testu lub snapshotu w kierunku `stricter` albo `neutral` zostaje na ścieżce z jednym recenzentem; zmiana `looser` dostaje etykietę `risk:high`, a recenzent musi ręcznie przekazać ją właścicielowi kodu, bo `CODEOWNERS` nie widzi etykiet.

`standard` odpowiada klasie `medium` w polityce organizacji; zmiany `critical` to tutaj `high` plus bramka zatwierdzenia produkcyjnego.

Przy `low` i `standard` zadaniem recenzenta jest przeczytanie pakietu w kolejności: zmiana specyfikacji, linie akceptacji, zmiany wyroczni, dowody z działania. Kolejność czytania i klasy eskalacji opisuje [czytanie dowodów zamiast kodu](/pl/ladder/evidence-not-diffs/), a protokół triage’u — [code review PR-a agenta](/pl/workflows/ship/agent-pr-review/).

## Jak Claude Code, Codex i Cursor przygotowują pakiet?

Format pakietu i check w CI są identyczne dla wszystkich trzech narzędzi. Różni się miejsce, w którym agent działa, gdy wypełnia pakiet. W każdym narzędziu najpierw dodaj ten fragment do pliku instrukcji, który agent czyta (`CLAUDE.md` w Claude Code, `AGENTS.md` w Codeksie, reguła projektu w Cursorze):

```markdown
## Pull requests
Every pull request body contains the evidence bundle from
.github/pull_request_template.md. Run every check you cite and paste real exit
codes. Never mark a criterion `pass` without running its check. List every
test, snapshot, CI or lint file you changed under risk.oracle_changes. Never
edit .github/evidence-policy.yml or scripts/check-evidence.mjs.
```

**Claude Code**

    Z terminala, na własnej gałęzi funkcji, uruchom prompt do pakietu w trybie headless i otwórz pull request z jego wynikiem. `dontAsk` z dokładną allowlistą to udokumentowany wzorzec dla przebiegów bez nadzoru: wszystko, co wymagałoby pytania i nie jest na liście, zostaje odrzucone, zamiast czekać na odpowiedź:

    ```bash
    # Terminal, feature branch checked out (Claude Code 2.1.283, `latest` channel)
    claude -p "$(cat .github/prompts/evidence-bundle.md)" --permission-mode dontAsk \
      --allowedTools "Read,Grep,Glob,Bash(git diff:*),Bash(git log:*),Bash(npm test:*),Bash(npx stryker run:*)" \
      > pr-body.md
    gh pr create --title "Cursor pagination for GET /orders" --body-file pr-body.md
    ```

    W GitHub Actions `anthropics/claude-code-action@v1` przyjmuje `--json-schema` w `claude_args` i udostępnia zwalidowany wynik jako wyjście kroku `structured_output`. Przydaje się, gdy chcesz mieć pakiet jako dane, a nie jako komentarz. W CI na gałęzi, której nie ufasz, dodaj `--bare --setting-sources "" --strict-mcp-config`, nie przekazuj żadnych sekretów poza kluczem API i nie dawaj agentowi powyższych reguł `Bash(npm test:*)` ani `Bash(npx stryker run:*)`: te polecenia wykonują kod z gałęzi, gdy klucz API jest w środowisku. Testy i przebieg mutacyjny uruchom we wcześniejszych krokach bez żadnego sekretu, a agentowi pozwól tylko czytać ich raporty (`Read,Grep,Glob`).

    Claude Code może dodawać atrybucję do commitów i pull requestów; zostaw ją włączoną: to darmowy zapis pochodzenia, zgodny z polem `provenance.agent` w pakiecie.

**Codex**

    `codex exec` uruchamia ten sam prompt nieinteraktywnie. `-o` zapisuje ostatnią wiadomość agenta do pliku, który staje się treścią pull requesta:

    ```bash
    # Terminal, feature branch checked out (Codex CLI 0.157.1)
    codex exec -c default_permissions=":workspace" \
      -o pr-body.md "$(cat .github/prompts/evidence-bundle.md)"
    gh pr create --title "Cursor pagination for GET /orders" --body-file pr-body.md
    ```

    Profil uprawnień `:workspace` (beta) pozwala przebiegowi uruchamiać testy wewnątrz repozytorium. Jeśli chcesz drugiej opinii przed otwarciem pull requesta, masz dwa osobne polecenia, bo `codex exec review` odrzuca `--base` razem z własnymi instrukcjami (sprawdzone w Codex CLI 0.157.1):

    ```bash
    # Plain branch review against main, no custom instructions
    codex exec review --base main

    # The audit prompt below, saved as .github/prompts/evidence-audit.md
    codex exec -c default_permissions=":read-only" \
      -o audit.md "$(cat .github/prompts/evidence-audit.md)"
    ```

    W profilu `:read-only` audyt może otwierać pliki, ale może nie móc ponownie uruchomić testów, które zapisują na dysk; jeśli chcesz ponownych uruchomień, użyj `:workspace`.

    W CI polecenie `codex exec` uruchamia `openai/codex-action@v1`; zob. [GitHub Action dla Codeksa](/pl/codex/ship/ci-cd/).

**Cursor**

    Wklej prompt do pakietu do agenta przed otwarciem pull requesta i użyj jego wyniku jako opisu. Umieść blok instrukcji z góry w regule projektu, żeby Cloud Agents stosowały go w pull requestach, które otwierają.

    Na pull requeście Bugbot według Cursora przegląda pull requesty i wykrywa błędy, problemy bezpieczeństwa i jakości kodu, a PR Routing & Approval przydziela recenzentów na podstawie własności kodu i historii commitów oraz może zatwierdzać pull requesty niskiego ryzyka, gdy spełnione są twoje kryteria (opisy produktów na cursor.com, sprawdzone 2026-08-28). Zapisz te kryteria tak, by odpowiadały wierszowi `low` w tabeli routingu, a zanim oprzesz się na etykietach `risk:*`, sprawdź w dokumentacji Cursora, jakie sygnały kryteria potrafią odczytać. Zob. [Rollouts oraz PR Routing & Approval w Cursorze](/pl/cursor-ide/ship/rollouts-and-approval/).

Dowody z działania zbierzesz skillem [`agent-browser`](/pl/ecosystem/skills/agent-browser/): każdy z trzech agentów może nim sterować działającą aplikacją i zapisywać zrzuty ekranu. Zainstaluj CLI poleceniem `npm install -g agent-browser && agent-browser install`, a skill poleceniem `npx skills add vercel-labs/agent-browser` (flagi dla poszczególnych agentów i przypinanie wersji opisuje podlinkowana strona). Wgraj zrzuty jako artefakty workflow i podaj URL artefaktu w `runtime.ref`.

## Prompty do skopiowania dla pakietu dowodów

Zapisz pierwszy prompt jako `.github/prompts/evidence-bundle.md`, żeby polecenia powyżej mogły go wczytać.

**Prompt do skopiowania: przygotuj pakiet dowodów dla tej gałęzi**

```text
Produce the pull request body for the changes on this branch against main.
Use the template in .github/pull_request_template.md exactly: a short summary
for a human, then the evidence_bundle YAML block.

Rules:
1. spec.link: the issue URL or spec file this work implements. spec.delta:
   each behavior change as one plain sentence a product manager could check.
   Put any behavior change nobody asked for under spec.unrequested.
2. acceptance: one entry per acceptance criterion in the spec. Run the check
   for each one now. result is pass only if you ran it and it passed;
   otherwise fail or unverified. Cite file:line or the exact command.
3. checks: every command you ran, with its real exit code.
4. risk.touches: every class from .github/evidence-policy.yml whose globs match
   a changed file. risk.oracle_changes: every changed test, snapshot, CI, lint
   or type-config file, with direction stricter, looser or neutral and one
   reason. risk.class: the highest min_risk that applies, or higher.
5. provenance: your tool and version, model ID, session link if you have one,
   the task link, and human_owner as given below.

human_owner: @anna
Do not edit any file. Output only the pull request body.
```

**Prompt do skopiowania: zaudytuj pakiet dowodów względem diffa**

```text
You are reviewing pull request evidence, not code style. Read the pull request
body and the diff against main. Do not edit files, approve, or merge.

For each section of the evidence_bundle, report CONFIRMED or CONTRADICTED:
- spec.delta: is every behavior change in the diff listed? Name any missing.
- acceptance: open each cited file:line. Does that test exercise the criterion,
  and would it fail if the behavior were wrong? Re-run the command if cheap.
- risk.oracle_changes: for each changed test or config, is the stated direction
  true? Flag removed assertions, loosened matchers, skipped tests and
  regenerated snapshots as looser.
- risk.class and risk.touches: do they match the diff and
  .github/evidence-policy.yml?
- runtime: does each screenshot or trace cover the criterion it claims?

End with one verdict: BUNDLE HOLDS, or BUNDLE CONTRADICTED with the fields
to fix, each with file and line.
```

**Prompt do skopiowania: napraw oblany check pakietu dowodów**

```text
The evidence-bundle CI check failed on this pull request. Its output is below.

For each error, fix the evidence, not the gate:
- If a criterion is unverified or failing, run its check; if it fails, fix
  the code or report that it cannot pass.
- If the diff touches an undeclared sensitive class or oracle file, add it to
  the bundle truthfully and raise risk.class if the policy requires it.
- Never edit .github/evidence-policy.yml, scripts/check-evidence.mjs, CI
  workflows, or a test's assertions to make this check pass.
Then output the corrected pull request body.

CHECK OUTPUT:
<paste the failing job log here>
```

## Co się psuje, gdy wymuszasz pakiet dowodów?

**Check nie znajduje skryptu przy pierwszym pull requeście.** Workflow czyta `scripts/check-evidence.mjs` z commita bazowego, a w pull requeście, który go dodaje, baza jeszcze go nie ma. Wyjście: najpierw scal pięć plików bez wymaganego checka, potem dodaj wymagany check do rulesetu.

**Pakiet podaje `pass` dla sprawdzeń, które nigdy się nie wykonały.** Agent wkleja wiarygodnie wyglądające kody wyjścia. Wyjście: trzymaj prawdziwe joby testowe jako osobne wymagane checki, żeby sekcja `checks` była deklaracją, którą CI potwierdza niezależnie. Dodaj prompt audytowy jako krok agenta recenzującego dla pull requestów `standard` i `high`, a sprzeczny pakiet traktuj jak oblane review.

**Linie akceptacji cytują testy, które nie testują kryterium.** `tests/orders.test.ts:1` istnieje i przechodzi, ale nie dowodzi niczego o paginacji. Skrypt widzi, że plik istnieje, a nie co sprawdza. Wyjście: przy zmianach `standard` recenzent otwiera każdą cytowaną linię, a [miary siły wyroczni](/pl/workflows/test/oracle-strength/), takie jak wynik testów mutacyjnych na zmienionych plikach, trafiają do `checks`.

**Agent osłabia test i nazywa to `neutral`.** Skrypt ufa zadeklarowanemu kierunkowi. Wyjście: umieść testy kodujące specyfikację na chronionej ścieżce z właścicielem w `CODEOWNERS`, niech recenzent `standard` porówna zadeklarowany kierunek każdej innej zmiany wyroczni z jej diffem, a [ochrona wyroczni](/pl/workflows/test/protect-the-oracle/) pokazuje hooki, które w ogóle nie pozwalają agentowi edytować testów.

**Globy polityki rozjeżdżają się z kodem.** Nowy katalog `src/checkout/` obsługuje pieniądze, ale nie pasuje do żadnego globu, więc zmiany w płatnościach przechodzą jako `low`. Wyjście: przeglądaj `.github/evidence-policy.yml` przy każdym nowym katalogu najwyższego poziomu i dodaj fixture dla każdego wrażliwego katalogu, żeby zmiana nazwy oblała test fixture’ów.

**Każdy pull request staje się `high`.** Jeśli globy polityki obejmują pół repozytorium, pakiet kieruje wszystko do właścicieli kodu i wracasz do czytania każdego diffa. Wyjście: zawęź globy do kodu, w którym błąd jest drogi i późno wykrywany, a resztę przenieś do `standard` z dowodami z działania.

**Etykiety nie działają w pull requestach z forków.** `GITHUB_TOKEN` w zdarzeniu `pull_request` z forka ma tylko prawo odczytu, więc `gh pr edit` się nie powiedzie. Wyjście: uruchamiaj agentów na gałęziach w tym samym repozytorium albo pomiń krok etykietowania dla forków i kieruj zmiany na podstawie wyniku checka.

**Pakiet staje się formalnością wypełnianą ręcznie.** Wyjście: śledź jedną liczbę na zespół, **kompletność dowodów**: scalone pull requesty, których pakiet przeszedł check za pierwszym podejściem, podzielone przez wszystkie scalone pull requesty, miesięcznie. Spadający trend oznacza, że agenci albo ludzie zgadują. Definicja i wartości bazowe są w [ramach metryk](/pl/org/metrics-frameworks/).

## Dokąd dalej po pakiecie dowodów

- [Code review PR-a agenta](/pl/workflows/ship/agent-pr-review/) — Protokół triage’u, który czyta ten pakiet: zmiana specyfikacji, dowody, flagi ryzyka, próbkowane miejsca.
- [Czytanie dowodów zamiast kodu](/pl/ladder/evidence-not-diffs/) — Dlaczego pakiet zastępuje diff jako pierwsza rzecz do przeczytania i które klasy nadal wymagają czytania kodu.
- [Wykonywalne kryteria akceptacji](/pl/workflows/plan/acceptance-criteria/) — Skąd biorą się linie akceptacji: kryteria zapisane jako czerwone testy, zanim agent zacznie pracę.
- [Pochodzenie zmian i routing według ryzyka](/pl/cto-scorecard-guide/ai-pr-labeling/) — Perspektywa governance: kontrole kierowane na podstawie pól ryzyka i pochodzenia z pakietu.
- [Od zgłoszenia do pull requesta bez rąk na klawiaturze](/pl/workflows/automate/issue-to-pr-pipeline/) — Potok end-to-end, który kończy się pull requestem z tym pakietem.
- [Progressive delivery dla zmian pisanych przez agentów](/pl/workflows/ship/progressive-delivery/) — Siatka bezpieczeństwa po merge’u dla każdej klasy ryzyka.
