# Приложение A. Рабочие шаблоны

Это контракты для адаптации к репозиторию, а не установленная схема данных.
Модель заполняет их по источникам. `<...>` означает отсутствующее значение;
проверка готовности запрещает такие placeholders в обязательных полях.
Короткие ID учебных примеров не заменяют реальные устойчивые идентификаторы.
Неизвестное отмечается явно вместе с последствиями и способом проверки.

## A1. Паспорт проекта и карта обследования

```yaml
schema_version: 1
project_id: <stable-id>
snapshot:
  repository: <verified-identity>
  revision: <commit>
  dirty_state: <none-or-saved-manifest>
stack:
  python: <verified-version>
  django: <verified-version>
  database: <engine-version-and-isolation>
  workers: <engine-version-delivery-settings-or-none>
  dependencies: <lockfile-and-digest>
environment:
  bootstrap: <verified-adapter>
  test_data: <approved-fixture-or-dataset-ref>
  external_effects: <sandbox-and-egress-policy>
inventory:
  entrypoints: <manifest-ref>
  writers_and_readers: <manifest-ref>
  integrations_and_effects: <manifest-ref>
  deployments_and_jobs: <manifest-ref>
  owners_and_authority: <registry-ref>
baseline:
  tests: <evidence-ref>
  known_failures: <list-ref>
  unknowns: <list-ref-with-consequences>
```

Для каждого внешнего эффекта: операция, вызывающие пути, область данных,
ключ до вызова, дедупликация, запрос статуса, окно видимости, тайм-аут,
компенсация, полномочие, тест безопасного resume. Значение «неизвестно»
запрещает обещать безопасный повтор соответствующего эффекта.

## A2. Наблюдение о текущем поведении — OBS

```markdown
ID: <stable-id>
Lifecycle: draft | active | retired
Kind: observation
Source revision: <commit>
Evidence: <code-symbols, experiment, logs, interview>
Freshness: current | suspect | stale | unknown

## Наблюдение
Что фактически делает система и при каких условиях.
## Охват
Проверенные входные точки, состояния и исключённые области.
## Уверенность и неизвестное
Что наблюдали непосредственно, что вывели, что ещё может опровергнуть вывод.
## Связи
Правила, операции, тесты, конфликты и владельцы решения.
```

OBS не становится бизнес-требованием только потому, что код так работает.
Для повторения эксперимента сохраняются команда/адаптер, входные данные и
окружение. Секреты и необезличенные данные в Markdown не попадают.

## A3. Бизнес-правило — BR

```markdown
ID: <stable-id>
Kind: business_rule
Lifecycle: draft | active | retired
Normative status: proposed | accepted | superseded
Authority: <authorized-decision-ref>
Freshness: current | suspect | stale | unknown
Owner role: <role>

## Правило
Для какого актора, объекта и состояния что разрешено/обязательно/запрещено.
## Инварианты и исключения
Предикаты, конкурентные события, временные границы и допустимые исключения.
## Таблица решений
Входы → ожидаемое поведение → пример → проверка.
## Реализация
Все известные входные точки и места обеспечения правила; обходные писатели.
## Источники и конфликты
Решение, наблюдения, прежняя версия, несовпадения факта и намерения.
## Проверки и изменение
Тестовые обязательства, влияние изменения и условие пересмотра.
```

Мини-пример таблицы для BR «отмена заказа»:

| Актор / состояние | Ожидаемое поведение | Проверка |
| --- | --- | --- |
| Владелец / неоплачен / не в сборке | Отмена разрешена | Основной сценарий |
| Другой покупатель / те же состояния | Отказ без изменения объекта | Изоляция прав |
| Владелец / оплачен | Отказ | Запрет изменения оплаченного |
| Оплата и отмена одновременно | Согласованный инвариант, без двойного эффекта | Конкурентный сценарий на целевой БД |

Конкретный результат последней строки должен быть определён действующей
нормой или решением до реализации; слово «согласованный» не заменяет oracle.

## A4. Архитектурный поток и ADR

Для потока фиксируются: trigger, актор/права, входы, шаги и ветвления,
читаемые/изменяемые данные, транзакционные границы, асинхронные переходы,
повторы/дедупликация, внешние эффекты, конкурентные писатели, ошибки,
наблюдаемость, нагрузочные ограничения, тесты и известные обходы.

Для алгоритма добавляются предусловия, постусловия, состояние, завершение,
сложность, граничные случаи, детерминизм и причина выбора. Для цикла зависимостей
указывается вид: импортный, вызовов, бизнес-процесса, событийный; критерий
допустимости и способ обнаружения регрессии.

ADR хранит контекст, решение, рассмотренные варианты, аргументы, последствия,
область действия, authority и условие пересмотра. Извлечённое из кода решение
без подтверждённого происхождения помечается реконструкцией, не историческим фактом.

## A5. Контракт изменения — CHG

```yaml
change_id: <stable-id>
intent: <exact-intent-ref>
decisions: [<decision-ref>]
goal: <observable-result>
scope:
  included: [<behavior-or-component>]
  excluded: [<explicit-boundary>]
impact:
  rules: [<rule-ref>]
  entrypoints: [<entrypoint-ref>]
  writers: [<writer-ref>]
  dependencies: [<dependency-ref>]
  uncertainty: [<unknown-with-consequence>]
acceptance:
  obligations: [<condition-with-oracle-and-check>]
  compatibility: [<required-compatibility>]
  nonfunctional: [<measurable-bound>]
risk: <semantic-class-and-rationale>
context_manifest: <versioned-ref>
runbooks: [<id-and-version>]
test_plan: <versioned-ref>
rollout: <plan-ref-or-reason-not-applicable>
recovery: <tested-plan-ref-or-explicit-gap>
authority: <applicable-policy-and-grant-ref>
```

Изменение scope фиксируется в журнале и пересчитывает impact. Модель не должна
сохранять прежний класс риска лишь для прохождения gate.

## A6. Пакет решения и ограниченное полномочие

Decision packet: вопрос о поведении или последствиях; уже известное намерение;
почему действующих решений недостаточно; факты и неизвестное; варианты;
рекомендация; область, срок и последствия выбора; что система сделает после него.

Запись решения: точная формулировка выбора, кто вправе его принять, источник
ответа, время, область, связанные нормы, что заменено и условие пересмотра.
Обязательная привязка: `decision_packet_id`, `decision_packet_digest` и ссылка
на аутентифицированное событие ответа. Для исходного однозначного поручения
пакетом может быть само сообщение с неизменяемым ID и отпечатком, без
искусственного повторного согласования.
Если исходное сообщение уже однозначно решает вопрос в пределах полномочий,
модель оформляет запись без повторного approval.

```yaml
grant_id: <stable-id>
version: <immutable-version>
issued_under: <trusted-policy-version>
decision: <authorized-decision-ref>
subject: <executor-identity-or-role>
scope:
  project: <verified-identity>
  action: <one-action-or-explicit-action-set>
  change_class: <semantic-class>
  target: <branch-environment-data-boundary>
conditions: [<required-gates>]
validity: <expiry-or-explicit-valid-until-revocation>
limits: <impact-cost-concurrency-limits>
revocation: <trusted-registry-and-ordering-contract>
admission: <where-live-authority-and-candidate-are-checked>
```

Одна запись может разрешать класс однотипных действий, если это прямо выбрано.
Она не даёт общий доступ ко всем окружениям. Расширение scope не наследуется
автоматически. Текст grant в непроверенном PR не активирует полномочие.

Запись активации политики содержит: activation ID; новую версию и digest;
прежнюю активную версию, по которой разрешена активация; применимое решение
и полномочие; субъект; область; точку упорядочивания/время; что заменено;
результат и receipt доверенного исполнителя. Недоступность реестра не означает
активацию. Начальная политика получает явный bootstrap-мандат, а не одобряет
себя отсутствующей предыдущей версией.

## A7. Context manifest

```yaml
manifest_id: <stable-id>
task: <change-id>
snapshot: <revision>
mandatory:
  - ref: <rule-policy-intent-or-contract>
    version: <version-or-digest>
    reason: <why-required>
supporting: [<source-refs>]
conflicts: [<refs-and-resolution-state>]
unknowns: [<question-consequence-resolution>]
impact_basis: [<entrypoints-reverse-deps-writer-search-evidence>]
excluded:
  - ref: <nonmandatory-source>
    reason: <why-outside-scope>
budget: <context-budget-and-splitting-plan>
```

Обязательные нормы и существенное неизвестное не отбрасываются из-за лимита
контекста. Область делится; проверенное сжатое представление сохраняет ссылки,
версии, оговорки и возможность открыть источник.

## A8. Ранбук и checkpoint

```yaml
runbook_id: <stable-id>
version: <immutable-version>
purpose: <result>
inputs: [<typed-ref>]
preconditions: [<check>]
allowed_actions: [<authority-bound-action>]
transitions:
  - id: <step-id>
    from: <state>
    requires: [<predicate>]
    operation: <verified-adapter-with-typed-inputs>
    before_effect: <durable-intent-and-operation-key>
    outputs: [<artifact-or-external-id>]
    verify: <result-check>
    on_unknown: <reconciliation-procedure>
    on_failure: <bounded-recovery-procedure>
    next: <state>
decision_points: [<condition-and-decision-packet>]
limits: <attempt-time-cost>
completion: <verifiable-result>
```

Checkpoint содержит run/step ID, версию ранбука, event sequence, owner/lease,
snapshot входов, workspace manifest, operation key, известные внешние ID,
последний подтверждённый результат и следующий допустимый переход.
Он не должен хранить credentials. Lease и CAS дополняются защитой от позднего
вызова прежнего владельца после передачи lease: проверяемым поколением владельца
или сериализованным посредником. Два параллельных resume и пробуждение старого
runner должны быть испытаны; одного факта истечения lease недостаточно.

## A9. Candidate core и evidence

```json
{
  "schema_version": 1,
  "repository_id": "<verified-identity>",
  "head_sha": "<sha>",
  "base_sha": "<sha>",
  "merge_strategy": "<verified-strategy>",
  "candidate_tree": "<tree-or-merge-commit>",
  "source_digest": "<digest>",
  "dependency_digest": "<digest>",
  "configuration_digest": "<digest>",
  "environment_digest": "<digest>",
  "test_plan_digest": "<digest>",
  "test_data_digest": "<digest>",
  "trusted_runner_configuration_digest": "<digest>",
  "acceptance_contract_version": "<version>",
  "trusted_policy_version": "<active-version>",
  "runbook_versions": ["<id@version>"]
}
```

`candidate_id = SHA256(canonical_json(core))`; контракт адаптера фиксирует
канонизацию. Изменение значимого входа создаёт новый core. Никакой evidence
или собственный хеш внутрь core не добавляется.

Evidence manifest содержит candidate ID, check ID/version, producer identity,
проверяемое основание доверия к producer и конфигурации, фактические входы,
время, статус, exit code, выбранные/собранные/исполненные тесты, обоснованные
skip, все попытки, ссылки и хеши логов/отчётов, срок хранения. Файл, созданный
автором PR, становится лишь заявлением автора, пока доверенная система не
проверила происхождение. Ссылки на защищённый storage и подписи выбираются
по модели угроз; само наличие поля `producer` не является проверкой.

## A10. PR, приёмка и receipt действия

PR для человека:

```markdown
## Проблема и результат
Что происходило и как изменилось наблюдаемое поведение.
## Область и последствия
Совместимость, данные, внешние эффекты, существенные ограничения.
## Проверка
Что проверено, результат, ссылки на доказательства; что не проверено и почему.
## Выпуск и восстановление
Нужные действия и проверенные условия их применения.
## Технические ссылки
CHG, правила/решения, candidate, context manifest, runbook, evidence.
```

Acceptance record: независимый reviewer/runner; candidate ID; обязательства
контракта; проверка intent и authority; findings с важностью и доказательствами;
результат каждого gate; известные ограничения; решение accept/reject/blocked;
время. Модель пишет семантическое заключение, доверенный gate разрешает действие.

Admission receipt: конкретное действие, candidate, активная policy, версия
grant, порядок относительно revocation, момент допуска и вызывающий субъект.
Completion receipt: внешняя операция, фактический результат, head/base/tree
или deployment identity, доказательство сверки и состояние при неоднозначности.
Они различают «действие допущено» и «результат подтверждён».

## A11. Карточка пилота и готовность класса задач

```markdown
Класс и границы: <semantic-scope>
Действия, которые предлагается автоматизировать: <actions>
Набор задач: <development-set and unseen-holdout-set>
Baseline: <manual/current-process evidence>
Оракулы: <who/what establishes expected behavior>
Выпуски адаптеров: <policy, CI evidence, merge, resume>
Нормальные сценарии: <expected/actual/evidence>
Внедрённые сбои: <expected gate / actual gate / evidence>
Человеческие решения и ручная механика: <separate counts and causes>
Дефекты/инциденты/восстановление: <all outcomes>
Время/стоимость: <total and distribution with sample size>
Нерешённые ограничения: <consequence and owner>
Вердикт по каждому действию: <ready / limited / not-ready>
Разрешённая область и условие отзыва: <decision/policy/grant>
```

Число задач, доля успеха и допустимый риск выбираются под класс, а не берутся
из универсального магического процента. Все попытки остаются в знаменателе
соответствующей метрики. После исправления обнаруженной слабости добавляют
новые скрытые случаи, иначе повторный успех может отражать подгонку.
