Files

claude-bot 6d798c01ef docs(overview): витрина системы docs/overview/ — бизнес+тех, 3 аудитории, презентация (ORCH-011)

Единая точка входа в документацию платформы (ADR-001 D1–D9):
- docs/overview/ — 10 файлов: индекс (маршруты «Я заказчик / Я менеджер /
  Я разработчик» + норматив «изменил функциональность → обнови витрину в том же
  PR»), business.md (без жаргона, 6 сценариев), 7 тех-блоков (link-first),
  presentation.md (16 слайдов + процедура сборки «команда + Проверка:»).
- scripts/build_presentation.py — генератор .pptx в тёмном дизайне (python-pptx;
  чистый stdlib-парсер parse_slides + ленивый import pptx; бинарь не коммитится,
  build/ в .gitignore; зависимость НЕ в прод-образе — машинный гард TC-09).
- tests/test_system_docs.py — структурный анти-дрейф: derive-сверки стадий/
  гейтов/агентов импортом STAGE_TRANSITIONS/QG_CHECKS/glob промптов/config,
  валидность ссылок, FORBIDDEN-скан + секрет-эвристика, слайды каноническим
  парсером, NFR-2, указатели.
- reviewer.md — ось обзорных доков ORCH-079 расширена на витрину (D7; канон 52d
  байт-в-байт, только текст внутри секций) + анти-регресс ассерт в
  test_agent_prompts_canon.py.
- Указатели: README.md, CLAUDE.md (правила №2/№6, «Структура»),
  PRODUCT_VISION.md (врезка-ссылка), CHANGELOG.md.

Рантайм байт-в-байт: src/**, docker-compose.yml, Dockerfile, requirements* —
ноль изменений (docs+tests+dev-скрипт, паттерн ORCH-102/103). pytest: 1873 passed.

Refs: ORCH-011

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

2026-06-11 09:36:40 +03:00

5.2 KiB

Raw Permalink Blame History

Блок 6. Качество и безопасность

Реестр гейтов и их распределение по стадиям — блок 2; механизм machine-verdict доков — PIPELINE_DOCS §3; машинный контракт стадий — HANDOFF_PROTOCOL.

Философия Quality Gates

Вердикты — машинные, никогда проза. Гейт читает вердикт ТОЛЬКО из YAML-frontmatter артефакта (ключи вида verdict:, result:, staging_status:, deploy_status:, security_status: — имена и регистр неизменны байт-в-байт). Агент не может «уговорить» гейт красивым отчётом: нет ключа — нет прохода. Парсинг frontmatter сведён к единому контракту src/frontmatter.py — одна точка чтения для всех гейтов.

Гейт ≠ маршрутизация. Маршруты задач (багфикс-трек, авто-лейблы, serial gate) — свойство планировщика; ни один из них не ослабляет ни одного гейта. Любая новая способность платформы проектируется так, чтобы реестр гейтов и карта стадий не трогались.

Анти-петля. Откаты на доработку ограничены (max 3 подряд); инструментальные сбои вспомогательных проверок по умолчанию fail-open с предупреждением (не запирают конвейер), критичные проверки — fail-closed.

Специальные гейты деплойного ребра

Security-гейт (check_security_gate) — детерминированная (без LLM) проверка секретов и зависимостей перед продом; вердикт — security_status: в отчёте задачи.
Coverage-гейт (check_coverage_gate) — покрытие тестами измеряется на финальном коде ветки; базовая линия по репозиторию растёт только вверх (ratchet при подтверждённом слиянии) — покрытие не может деградировать молча.

Оба — врезки в переход (блок 2), включаются по конфигу и скоупятся по репозиториям.

Канон секретов

Секреты живут только в .env-файлах на хосте и никогда не коммитятся; в git — только канон-примеры с пустыми плейсхолдерами.
Для нового хоста секреты выпускаются свежими (scripts/gen_secrets.py), боевые не копируются.
Анти-регресс машинный: структурные тесты сканируют исполняемый код на боевые хост-литералы, а документацию — на секретоподобные значения; находка рвёт CI.

Self-hosting-страховки

Платформа дорабатывает сама себя тем же конвейером — прод-инстанс при этом обслуживает и другие проекты. Страховки:

Песочница обязательна: перед прод-выкладкой платформы изменение репетируется на staging-инстансе (отдельный порт/БД); guard не даёт staging-операциям коснуться прод-порта.
Прод-выкладка — только по явному человеческому статусу Confirm Deploy (обычный approve прод не выкатывает); деплой идёт детачнутым процессом с финализатором — честный исход фиксируется даже при рестарте.
main неприкосновенен: слияние только через PR-API, force-push запрещён всем.
Прод-контейнер никогда не роняется задачей: агенты проверяют изменения локально и на песочнице; рестарт прода — только штатным деплой-маршрутом.
Пост-деплой наблюдение: после выкладки платформа следит за своим здоровьем; деградация замораживает репозиторий и зовёт человека.

Операционные детали и топология прода — docs/operations/ (см. инженерный справочник); наблюдение за здоровьем — блок 7.

5.2 KiB Raw Permalink Blame History Unescape Escape