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>
This commit is contained in:
63
docs/overview/tech-quality-security.md
Normal file
63
docs/overview/tech-quality-security.md
Normal file
@@ -0,0 +1,63 @@
|
||||
# Блок 6. Качество и безопасность
|
||||
|
||||
> Реестр гейтов и их распределение по стадиям — [блок 2](tech-pipeline.md); механизм
|
||||
> machine-verdict доков — [PIPELINE_DOCS §3](../_standards/PIPELINE_DOCS.md); машинный
|
||||
> контракт стадий — [HANDOFF_PROTOCOL](../_standards/HANDOFF_PROTOCOL.md).
|
||||
|
||||
## Философия 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](tech-pipeline.md)), включаются по конфигу и скоупятся по
|
||||
репозиториям.
|
||||
|
||||
## Канон секретов
|
||||
|
||||
- Секреты живут **только в `.env`-файлах на хосте** и никогда не коммитятся; в git — только
|
||||
канон-примеры с пустыми плейсхолдерами.
|
||||
- Для нового хоста секреты **выпускаются свежими** (`scripts/gen_secrets.py`), боевые не
|
||||
копируются.
|
||||
- Анти-регресс машинный: структурные тесты сканируют исполняемый код на боевые хост-литералы,
|
||||
а документацию — на секретоподобные значения; находка рвёт CI.
|
||||
|
||||
## Self-hosting-страховки
|
||||
|
||||
Платформа дорабатывает сама себя тем же конвейером — прод-инстанс при этом обслуживает и
|
||||
другие проекты. Страховки:
|
||||
|
||||
- **Песочница обязательна:** перед прод-выкладкой платформы изменение репетируется на
|
||||
staging-инстансе (отдельный порт/БД); guard не даёт staging-операциям коснуться прод-порта.
|
||||
- **Прод-выкладка — только по явному человеческому статусу Confirm Deploy** (обычный approve
|
||||
прод не выкатывает); деплой идёт детачнутым процессом с финализатором — честный исход
|
||||
фиксируется даже при рестарте.
|
||||
- **`main` неприкосновенен:** слияние только через PR-API, force-push запрещён всем.
|
||||
- **Прод-контейнер никогда не роняется задачей**: агенты проверяют изменения локально и на
|
||||
песочнице; рестарт прода — только штатным деплой-маршрутом.
|
||||
- **Пост-деплой наблюдение:** после выкладки платформа следит за своим здоровьем; деградация
|
||||
замораживает репозиторий и зовёт человека.
|
||||
|
||||
---
|
||||
|
||||
*Операционные детали и топология прода — `docs/operations/` (см.
|
||||
[инженерный справочник](../architecture/README.md)); наблюдение за здоровьем —
|
||||
[блок 7](tech-observability.md).*
|
||||
Reference in New Issue
Block a user