Files
crank/docs/development-evidence.md
T

90 lines
6.0 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Evidence разработки
Этот порядок помогает восстановить состояние кода и результат каждого
проверяемого этапа. Он не заменяет [Capability Baseline](./capability-baseline/manifest.json):
baseline хранит версионированный снимок capability Inventory и исторические
результаты, а completion evidence указывает, что именно проверено для текущего
этапа или завершения.
## Ревизии этапа
До начала этапа запишите полный Git commit `baseline_commit` и убедитесь, что
`git status --short` пуст. Это проверка tracked, staged и обычных untracked
изменений; игнорируемые локальные файлы не входят в Git baseline. Не записывайте
`baseline + uncommitted worktree` как revision.
После изменений сохраните проверенный implementation revision отдельным полным
commit hash. Проверки, которые подтверждают завершение этапа, должны относиться
к этому commit при чистом worktree. Укажите использованные конфигурацию и
класс окружения: одинаковый commit сам по себе не описывает их.
Если нужен RED до коммита, зафиксируйте его как промежуточное наблюдение: укажите
`baseline_commit`, SHA-256 сохранённого diff/artifact, включающего изменения
(в том числе untracked test files), команду и её фактический результат. Не
представляйте baseline вместе с незакоммиченным diff как implementation revision.
После RED повторите нужные проверки на отдельном чистом implementation revision.
## Запись completion evidence
Для текущего завершения используйте отдельный versioned index и sanitized
evidence-файлы с устойчивыми repository-relative ссылками. Запись должна позволять
повторно определить проверенное состояние и результат, не сохраняя секреты,
локальные абсолютные пути или произвольные payloads. Для каждой проверки укажите:
- идентификатор этапа/запуска и полный `baseline_commit`;
- полный `implementation_revision` проверенного commit;
- конфигурацию/toolchain и класс окружения;
- точную команду, exit code и фактические counts `passed`, `failed`, `skipped`
(или эквивалентный summary для команды без тестового счётчика);
- repository-relative путь к sanitised log/report и его SHA-256.
Если результаты не относятся к одной и той же ревизии, конфигурации или
окружению, записывайте их раздельно. Не выводите PASS из exit code без проверки
счётчиков и пропусков; сохраняйте fail, flaky, skipped, not-run и manual-only
как наблюдались. Новое completion evidence не переписывает historical baseline
или его manual failures.
Изменение canonical Capability Inventory status/evidence по-прежнему требует
обновить versioned `docs/capability-baseline/manifest.json`, sanitized
`docs/capability-baseline/results.json`, `baseline_version` и SHA-256 согласно
его schema и проверкам. Отдельный completion index не ослабляет и не обходит
этот gate.
Компактный шаблон записи:
```yaml
id: <stage-or-run-id>
baseline_commit: <full-git-commit>
implementation_revision: <full-git-commit>
environment:
class: <environment-class>
config: <tracked-config-or-versioned-reference>
command: <exact-command>
exit_code: <actual-integer>
counts:
passed: <actual-count>
failed: <actual-count>
skipped: <actual-count>
evidence:
path: <repository-relative-sanitized-report>
sha256: <sha256-of-report>
```
Для промежуточного RED вместо `implementation_revision` укажите
`diff_sha256` и ссылку на сохранённый diff/artifact; не выдавайте его за
проверенный implementation commit.
## Условия воспроизводимого запуска
Сохраняйте рабочие журналы за пределами временного каталога ОС и переносите
обезличенные summaries и digests в versioned evidence при завершении этапа.
Перезапуск окружения может удалить временные журналы; потерянный первичный лог
нельзя заменять утверждением, что проверка прошла.
Для разных checkout задавайте разные `CARGO_TARGET_DIR`: сборка baseline
с общим target может подменить артефакт проверяемой реализации. Полный
`just verify` запускайте отдельно от UI stack: startup tests используют
стандартные metrics ports. Для capture используйте pipe и запись родителем:
прямое перенаправление в обычный файл влияет на дочерние tests с `RLIMIT_FSIZE`.
Прерванный запуск сохраняйте отдельно от последующего успешного.