loopagent-gate 0.4.2__py3-none-any.whl

loopgate/templates/configs/fixtures/review_approve.json

@@ -0,0 +1,5 @@
+{
+  "runId": "run_fixture_approve_001",
+  "status": "ok",
+  "summary": "## Findings\nNo blockers found. The design is clean and matches the acceptance criteria.\n\n## Missing tests or evidence\nNone; the mandatory evidence bundle was proved and reproduced.\n\n## Questions for the author\nNone.\n\nVERDICT: APPROVE"
+}

loopgate/templates/configs/fixtures/review_changes.json

@@ -0,0 +1,5 @@
+{
+  "runId": "run_fixture_changes_001",
+  "status": "ok",
+  "summary": "## Findings\n- `scripts/review_pr.py`: line 42: major: failure to handle missing verdict line leads to undefined behaviour.\n\n## Missing tests or evidence\nMissing offline unit test coverage for error conditions.\n\n## Questions for the author\nCan we avoid network calls when reading from result files?\n\nVERDICT: CHANGES"
+}

loopgate/templates/configs/fixtures/review_no_verdict.json

@@ -0,0 +1,5 @@
+{
+  "runId": "run_fixture_no_verdict_001",
+  "status": "ok",
+  "summary": "This change looks generally good and well thought out. The comments are helpful and everything seems to run properly. Thanks for working on this!"
+}

loopgate/templates/configs/repo_profiles.example.json

@@ -0,0 +1,63 @@
+{
+  "version": 1,
+  "note": "PER-REPOSITORY CONTRACT — this is the example shipped with the public tree, copied to configs/repo_profiles.json by loopgate/gates/export_public.py. Replace it with your own repository: the evidence bundle is the machine-readable form of the rule that a worker must prove EVERY gate its repository requires, not a subset. Add a profile before queueing issues for a new repository; the bridge refuses to mint a brief for an unknown profile (fail-closed). local_path may stay null: pass --repo-path, or set the environment variable named in local_path_env.",
+  "profiles": {
+    "sample-service": {
+      "repo": "example/sample-service",
+      "base_branch": "main",
+      "local_path": null,
+      "local_path_env": "EXAMPLE_REPO",
+      "sources_of_truth": [
+        "AGENTS.md",
+        "Makefile"
+      ],
+      "evidence_bundle": [
+        {
+          "command": "make build",
+          "source": "Makefile target 'build': a change is not accepted uncompiled"
+        },
+        {
+          "command": "make lint",
+          "source": "AGENTS.md -> code quality rules, item 1 (mandatory before any commit, 0 issues)"
+        },
+        {
+          "command": "make test",
+          "source": "AGENTS.md -> code quality rules, item 4 (all tests pass before creating a commit)"
+        }
+      ],
+      "bundle_source": "AGENTS.md -> 'code quality rules (mandatory before any commit)' plus the Makefile build target",
+      "branch_pattern": "<role>/issue-<n>",
+      "pr_rules": [
+        "one task = one PR: exactly one issue, one branch, one pull request",
+        "PR body embeds the evidence bundle verbatim (command, output, exit code)",
+        "branch <role>/issue-<n> off main; never commit or push to main",
+        "changes stay inside this repository; no infra/GitOps repos",
+        "the reviewer re-runs the bundle in a separate worktree of the PR head commit: an unproven command is a REJECT regardless of the code"
+      ],
+      "kanban": {
+        "assignee": "dev",
+        "assignee_by_label": {
+          "qa": "qa",
+          "ux": "qa"
+        },
+        "project": "example",
+        "workspace": null,
+        "priority": 0,
+        "note": "project=<slug> anchors the task in an isolated git worktree of the target clone with a deterministic branch; the worker commits and pushes that branch and opens the PR itself when `gh auth status` succeeds. Without an execution backend use --target backlog."
+      },
+      "triage_labels": [
+        "valid",
+        "triaged",
+        "approved"
+      ],
+      "skip_labels": [
+        "invalid",
+        "wontfix",
+        "duplicate",
+        "needs-info",
+        "question",
+        "blocked"
+      ]
+    }
+  }
+}

loopgate/templates/configs/tree_parity.example.json

@@ -0,0 +1,16 @@
+{
+  "note": "Example parity policy for a project that is developed in one checkout and published from another. Copy it to configs/tree_parity.json (gitignored by convention in the tree that holds the real paths), fill in the two roots, then run `make parity POLICY=configs/tree_parity.json`. Every may-differ entry needs a reason: an exception without one is reported as drift regardless of the paths involved. Anything that differs and is covered by no rule at all is reported as unclassified drift, so a new file cannot be added to one checkout and forgotten in the other.",
+  "a": "/path/to/development/tree",
+  "b": "/path/to/published/tree",
+  "must_match": [
+    "loopgate/gates/*.py",
+    "Makefile",
+    ".github/workflows/*.yml",
+    "pyproject.toml"
+  ],
+  "may_differ": {
+    "loopgate/gates/private_tool.py": "development-only tooling that is not published",
+    "configs/*": "the development tree names real targets; the published tree carries sanitized ones",
+    "README.md": "the published README is rewritten for strangers"
+  }
+}

loopgate/templates/skills/loop-engineering/SKILL.md

@@ -0,0 +1,281 @@
+---
+name: loop-engineering
+description: Use when a task needs a bounded multi-round loop with evidence instead of a one-shot prompt — plan, verify with the local gate, repair, review, hand off. Trigger keywords: loop engineering, bounded loop, iterate until green, build fail repair prove, round-by-round evidence.
+---
+
+# Loop Engineering (bounded loop with proof)
+
+Превращает работу агента в ограниченную петлю, которую принимают по доказательству, а не по
+уверенности: `Build → Fail → Repair → Prove → Review → Handoff`.
+
+Скилл — это процедура. Гейт, который её принимает, — отдельный pip-пакет `loopgate`; раздел ниже
+ставит его в проект. Ссылки на `course/**` в этом тексте — материал автора, в поставку не входит.
+
+## Установка в проект (скилл скачан отдельно)
+
+```bash
+pip install loopagent-gate      # PyPI; or: pip install "git+https://github.com/mjeksonpx/loopagent.git@v0.4.2"
+cd <проект>                 # git-репозиторий или каталог с AGENTS.md
+loopgate init               # этот скилл -> .agents/skills/, контракт -> AGENTS.md/PLANS.md/README.md, холодный старт
+loopgate gate --strict      # STOP: перечисляет измерения, которые проект настраивает сам
+```
+
+Дистрибутив называется `loopagent-gate`, команда — `loopgate`: имя `loopgate` на PyPI занято чужим проектом,
+а `loopagent` отклонён как слишком похожий на `loop-agent`.
+Без консольной команды те же шаги: `python3 -m loopgate.init` и
+`python3 -m loopgate.gates.check_loop --strict`.
+
+Первый вердикт нового проекта — `STOP`, а не `PASS`: D10–D14 описывают факты самого проекта (бандл
+команд, сценарии продукта, ключ подписи, визуальные сценарии, baseline метрик). `init` их не выдумывает
+и не подставляет шаблон вместо доказательства.
+
+В Hermes проектные скиллы грузятся только из доверенного репозитория: один раз `hermes skills trust`
+из каталога проекта. В других агентах (Claude Code, Cursor, Copilot) `init` кладёт файл в ту же
+кросс-инструментальную конвенцию `.agents/skills/`.
+
+## Когда включать
+
+- Работа требует нескольких раундов с накоплением evidence (readiness, безопасность, рефакторинг, релиз-гейт).
+- Нужны состояние, артефакты раундов, stop-условия и финальный handoff.
+- Нужен локальный гейт, который печатает PASS-маркер и `exit 0`.
+
+## Когда НЕ включать
+
+- Одноразовая правка текста/файла без раундов и evidence.
+- Задачи, где достаточно `verify-changes` за один проход.
+- Настройка расписания/крона как таковая (это автоматизация, а не содержание петли).
+
+## Контракт рана (заполнить до первой правки)
+
+```
+Goal:          <что должно стать правдой>
+Sources:       <файлы/команды — источник истины, не выдумывать evidence>
+Constraints:   <что можно менять; что нельзя: сеть, секреты, вне репо>
+Done-when:     loopgate/gates/check_loop.py (python3 -m loopgate.gates.check_loop) → LOOP_ENGINEERING_PASS_0001, exit 0
+Stop-if:       нужного файла нет / нужна сеть или секреты / правка выходит за репо / гейт не зеленеет после 3 раундов
+```
+
+## Гейт (Prove)
+
+```bash
+python3 -m loopgate.gates.check_loop            # обычный режим; опциональные измерения могут SKIP
+python3 -m loopgate.gates.check_loop --strict   # SKIP становится FAIL (после Этапа 2)
+python3 -m loopgate.gates.check_loop --report artifacts/loop_gate_report.json
+```
+
+Гейт **read-only**: сам ничего не чинит и не пишет (кроме явного `--report`). Стартует красным —
+печатает список failures и `LOOP_ENGINEERING_STOP_0001` с `exit 1`; после ремонта — `[OK]` по
+измерениям и `LOOP_ENGINEERING_PASS_0001` с `exit 0`. Маркер печатает **только гейт**, не агент.
+
+Guardrail-скан не должен ловить evidence: транскрипты раундов и собственные транскрипты гейта
+цитируют текст failures. Поэтому в markdown вызовом считается только строка, начинающаяся с бинаря
+агента, а исходник гейта и оба его транскрипта (`artifacts/loop_gate_report.json`,
+`artifacts/loop_gate_pass.json`) исключены из скана целиком.
+
+Приёмка проекта — только `--strict`: обычный режим печатает `acceptance: stage-1`, строгий —
+`strict-complete`. Якорь `loop_gate_pass.json` пишется, когда зелены **все измерения кроме тех, что
+читают сам якорь** — `D05` (связывает handoff с якорем) и `D12` (проверяет подпись якоря); хэш вердиктов
+считается без обоих, иначе измерение сертифицировало бы само себя. Из этой пары следует восстановление
+потерянного состояния: дерево без якоря не может его выпустить, если `D12` требуется для выпуска —
+`D12` ждёт подписи, подпись ждёт якоря, якорь ждёт `D12`. Поэтому первый прогон после смены вердиктов
+падает на `D05` (якорь устарел) и на `D12` (подписи нет), хэш из якоря прописывается в handoff, якорь
+подписывается, и только следующий прогон даёт fixpoint.
+
+| id | измерение | что проверяет |
+|---|---|---|
+| D01 | contract_skill | этот файл: контракт, маркер, команда гейта, правило ywcrew |
+| D02 | sources_of_truth | `AGENTS.md` (Sources of truth / Done-when / Stop), `PLANS.md`, `README.md` |
+| D03 | loop_state | `artifacts/loop_state.json`: схема, диапазоны 0..100, phase, маркер |
+| D04 | rounds | ≥3 `artifacts/rounds/round_NN.md` с разделами Gap/Change/Evidence/Metrics/Next |
+| D05 | handoff | `handoff/latest_loop.json` (status pass, нулевые blockers, непустой `reviewed_by`, существующие артефакты) + `handoff/supervisor_synthesis.md`; привязан к якорю `artifacts/loop_gate_pass.json`: хэш вердиктов без D05 **и** сверка состояния `(ok, skip)` якоря с состоянием текущего прогона — подделанный якорь не описывает текущий прогон и падает |
+| D06 | guardrail_no_direct_cli | нет прямых вызовов CLI-агентов: код сканируется целиком, в markdown вызовом считается только строка, начинающаяся с бинаря агента (плюс строгий скан shell-блоков) |
+| D07 | guardrail_no_secrets | нет строк, похожих на ключи/токены |
+| D08 | course_corpus | `course/` собран: 17 уроков, ≥40k слов OCR, ≥15k байт промптов |
+| D09 | roles_fanout | 4 артефакта ролей ≥300 символов с атрибуцией `runId:` (SKIP, если артефактов нет) |
+| D10 | issue_bridge | этап 6: мост `sync_issues_to_kanban.py` + профили репозиториев; бриф из `worker_brief.py` содержит все команды бандла и правила доказательств; правило есть и в kanban-теле, и в `task.constraints` ywcrew-задачи; валидатор бандла атакован 5 фальсификациями (полный транскрипт принят; неполный, падающий, пустой и «заимствованный exit-код» — отклонены) |
+
+| D11 | product_gate | этап 7: второй вердикт — пользовательские сценарии продукта (`configs/product_scenarios.json` + `check_product.py`); у каждого сценария строка `why`, у профиля — `local_path`; evaluator атакуется мутацией ожиданий каждого сценария (15 фальсификаций отклонено) |
+
+| D12 | anchor_witness | якорь не сертифицирует сам себя (исключён из своего хэша вместе с D05); вердикт якоря подписан отдельным SSH-ключом (публичная половина в `configs/allowed_signers`), запись свидетеля совпадает с текущим вердиктом, перезапись якоря не верифицируется; внешний журнал объявлен (проверка сети — шаг оператора `check-external`) |
+| D13 | visual_gate | визуальная половина qa: сценарии `configs/visual_scenarios.json` (у каждого `why`), headless-браузер реально доступен, минимум один сценарий требует скриншот, evaluator отклоняет 23 фальсифицированные страницы |
+
+## Цикл
+
+1. **Инспекция + план.** Прогнать гейт, взять список failures как план работ. Правок нет, ждать одобрения.
+2. **Один раунд за раз.** Закрыть один gap → обновить `artifacts/loop_state.json` → добавить evidence → записать `artifacts/rounds/round_NN.md`.
+3. **Метрики монотонны** в правильную сторону: readiness/evidence растут, risk/blockers падают.
+4. **Перепрогон гейта** после значимых изменений; вывод гейта — единственный источник истины.
+5. **Ревью отдельным движком:** `ywcrew panel` (codex + grok + agy/claude-sonnet). Оценщик имеет право сказать «нет».
+6. **Стоп** только когда гейт печатает PASS-маркер. Затем — короткий handoff.
+
+## Контекст и итерации (свежий контекст против `/loop`)
+
+Правило взято из Ralph Loop (раздел 5 курса) и проверено на собственной практике: итерация должна
+начинаться с **чистого контекста**, а память между итерациями живёт в файлах, не в окне модели.
+
+- **Поток задач** (N карточек) идёт только через очередь: каждая карточка — новый процесс, свежий
+  контекст, бриф вместо накопленной истории. Воркер не помнит прошлую карточку и не должен.
+- **`/loop` в сессии** крутит тот же контекст: модель тащит свои прошлые правки, окно растёт, после
+  десятков итераций качество падает. Годится только чтобы «дожать гейт до зелёного» на одной задаче.
+  Для потока из N задач `/loop` не использовать.
+- **Читать в начале итерации:** `AGENTS.md`, свой бриф, `artifacts/loop_state.json`, последний
+  `artifacts/rounds/round_NN.md`, `git log --oneline -5`. Всё, что не в этих файлах — не существует.
+- **Писать в конце итерации:** раунд-артефакт (или комментарий в карточку) с командой, выводом и
+  exit-кодом. Знание, оставшееся только в контексте, теряется вместе с ним.
+- **Ремонт не бесконечен:** одна и та же команда, красная третий раз подряд, — это стоп и сдача с
+  выводом, а не десятая попытка (лимит закрепляется в брифе и в `verify`, см. PLANS.md п.33).
+
+## Роли при fan-out (bounded, ровно четыре)
+
+| Роль | Границы | Артефакт |
+|---|---|---|
+| explorer | read-only, карта репо и состояние гейта | `handoff/agents/explorer_findings.md` |
+| reviewer | read-only, оспаривает слабое evidence | `handoff/agents/reviewer_risks.md` |
+| worker | scoped edit, минимальная правка по evidence | `handoff/agents/worker_changes.md` |
+| evaluator | верификация, прогон гейта | `handoff/agents/evaluator_verification.md` |
+| supervisor (Hermes) | собирает evidence в одно решение | `handoff/supervisor_synthesis.md` |
+
+`ywcrew panel` для reviewer, `ywcrew run --mode edit` для worker, read-only для explorer/evaluator.
+Никаких прямых вызовов CLI-агентов — только через ywcrew.
+
+Основной worker по умолчанию — `harness` (DeepSeek Harness, модель `deepseek-v4.1-flash` через
+провайдера `opencode-go`): `ywcrew run --backend harness --mode edit`. DSH выполняет команды без
+авто-отказов, но **песочницы в `dsh headless` нет** — read-only и edit одинаково идут в git-worktree,
+поэтому запись в дерево оператора не попадает, а gitignored-состояние приезжает через
+`.worktreeinclude`.
+
+## Сколько ревьюеров нужно (цена против независимости)
+
+- **По умолчанию — ОДИН ревьюер**, не панель: `ywcrew run --mode read-only --backend agy
+  --model claude-sonnet-4-6` (он в живом прогоне сам перепрогнал build+lint+test и снял возражение
+  фактом). Панель из трёх моделей стоит ~3× токенов и времени ревью.
+- **Панель — только для высокой ставки**: релиз, безопасность, архитектурные решения, крупный PR,
+  или когда предыдущий вердикт оспорен. Три семейства моделей нужны там, где цена ошибки выше цены
+  ревью.
+- Почему не «одной модели всегда достаточно»: в первом же живом PR-прогоне три члена панели дали
+  ACCEPT / REJECT / «нет вердикта». Одна модель = монетка по вопросу «принимать или нет». При этом
+  REJECT был по существу (неполные доказательства), и его снял именно перепрогон гейтов, а не голос.
+
+## Доказательства воркера и консенсус панели (уроки живого PR-прогона)
+
+- **Бандл доказательств = все гейты, которые требует `AGENTS.md` репозитория, а не подмножество.**
+  Воркер, доказавший только `go build`, получил законный REJECT: репозиторий требовал ещё
+  `golangci-lint run ./...` и `go test -count=1 ./...` перед коммитом. Правило переехало **в сам бриф**:
+  бриф рендерит `loopgate/gates/worker_brief.py` из `configs/repo_profiles.json` (команды + файл-источник
+  требования + формат транскрипта + output-контракт), а `worker_brief.py verify --profile <p>
+  --evidence <файл>` печатает `WORKER_EVIDENCE_PASS_0001` / `WORKER_EVIDENCE_STOP_0001` и называет
+  незапущенные команды, невидимые exit-коды и ненулевые возвраты. Прогонять verify до ревью —
+  дешевле, чем получать REJECT и доигрывать доказательства после.
+- **Бриф — это тело задачи в kanban, а не отдельный документ.** `loopgate/gates/sync_issues_to_kanban.py`
+  берёт open issues (`gh`), отсеивает невалидные машино-проверяемым подмножеством (labels, объём тела,
+  наличие acceptance-критериев; семантический триаж остаётся роли), и создаёт задачу с брифом как
+  телом, идемпотентно по ключу `gh-<owner>-<repo>-<n>`. `--apply` отказывает, если у профиля не задан
+  workspace/project: очередь, которую некому исполнить, — не очередь.
+- **Ревьюер, который перепрогоняет гейты сам, сильнее ревьюера, который судит по присланному.**
+  В том же прогоне второй член панели сам прогнал build+lint+test в отдельном worktree ветки и снял
+  возражение фактом. Разрыв «доказательства неполные» закрывается не спором, а прогоном гейтов на
+  head ветки (отдельный `git worktree` того же коммита — доказательство привязано к ревизии).
+- **Exit-код принадлежит своей команде.** Требовать `exit=0` отдельной строкой *внутри блока этой
+  команды* (до следующей команды). Свободное окно «N строк после команды» пропускает один хвостовой
+  `exit=0`, который доказывает все гейты сразу — это нашёл живой ревьюер в первом же прогоне этапа 6,
+  и это ровно тот дефект, ради которого бандл и заводился. Регресс-кейс: транскрипт со всеми командами
+  и одним кодом в конце должен краснеть.
+- **Бандл — пол, а не доказательство полноты.** Список команд в профиле всегда может быть неполным,
+  поэтому в профиле хранится `bundle_source` (файл + раздел, откуда гейты взяты), а воркер обязан
+  перевывести список из источника и назвать гейты, которые он прогнал сверх списка. Гейт проверяет
+  наличие `bundle_source` и этой инструкции в брифе; сама полнота остаётся человекочитаемым остатком.
+- **Триаж-лейбл — это решение роли, а не критерии.** `classify()` в мосте называет основание вердикта
+  (секция acceptance-критериев vs лейбл), а бриф требует от воркера назвать конкретные критерии, против
+  которых он работал. Иначе «очередь валидна» и «работа проверяема» — разные утверждения.
+- **Реальность воркспейса важнее брифового идеала.** Kanban-задача с `--project` приезжает воркеру уже
+  как git-worktree с собственной ветвью, а `gh` в окружении воркера может быть не авторизован: пуш по SSH
+  работает, PR открывает оркестратор из транскрипта. Бриф, требующий конкретного имени ветки и
+  собственноручного PR, отправляет воркера в тупик — проверено на первом же живом прогоне.
+- **Повторный прогон команды — это тоже её результат.** Проверять все вхождения команды, а не первое:
+  «прошло, потом упало» — это упавший гейт, спрятанный за первым успехом (нашёл второй живой ревьюер).
+  И `NOT RUN` должен ловиться в любом месте блока команды, а не в первых трёх строках.
+- **Валидатор честно объявляет свою терпимость.** Наш валидатор мягче буквы брифа по префиксу промпта
+  (`$` необязателен) и по написанию exit-кода (`exit code: 0`, `Exit=0`) — это записано как осознанная
+  терпимость, а не выдаётся за строгость: ревьюер должен видеть, где правило строгое, а где снисходительное.
+- **Надёжность движков на ревью различается, и это часть evidence.** В одном и том же раунде
+  `harness:deepseek-v4.1-flash` (read-only) дал конформный вердикт с четырьмя MINOR, `codex` упирался в
+  квоту, `agy` дважды ушёл в таймаут на 900 с (крупная задача), `grok` дважды вернул преамбулу вместо
+  вердикта. Планировать ревью с запасным движком и фиксировать «нет вердикта» как отсутствие голоса.
+  Отдельно про agy: read-only **выполняет** команды — проверено на двух моделях (claude-sonnet-4-6:
+  точный sha256, живой timestamp, exit code 7; gemini-3.8-flash: то же плюс прогон строгого гейта с
+  `LOOP_ENGINEERING_PASS_0001` и exit 0). Значит `contract_violated` у gemini-3.8-flash означал ответ,
+  не попавший в контракт, а не неспособность. Два таймаута на 900 с дала ширина задачи: agy раскладывает
+  широкую задачу на фоновые подзадачи и уходит в ожидание до 20 минут. Лимит ywcrew на ран поднят до
+  1 800 000 мс (30 мин) и стал конфигурируемым — `defaults.timeoutMs` в `~/.ywcrew/config.json`,
+  приоритет у явного `timeoutMs` в задаче. Панель ywcrew: `harness` + `agy` + `codex` (grok выключен).
+- **Несоответствующий output-контракту ответ члена панели = «нет вердикта», а не голос.** Один член
+  вернул преамбулу вместо вердикта; в наивном большинстве это исказило бы консенсус. Требовать
+  минимум два конформных вердикта, прежде чем объявлять консенсус.
+
+## Два вердикта и время (этапы 7)
+
+- **Продуктовая приёмка — отдельный вердикт с отдельным владельцем.** Техгейт отвечает «дисциплинирована
+  ли петля», продуктовый (`loopgate/gates/check_product.py`) — «может ли пользователь делать работу этим
+  продуктом». Смешав их, получаешь зелёный техгейт над продуктом, который не стартует. У каждого сценария
+  обязательна строка `why` — последствие для пользователя; сценарий без неё не принимается (D11).
+- **Ожидания измеряются до того, как записываются.** Все сценарии sample-service сначала проверены руками
+  (200 у проб, Prometheus-текст у метрик, exit 1 с именем поля у невалидной конфигурации, ~250 мс на
+  SIGTERM) и только потом записаны. Первый же живой прогон гейта нашёл дефект в самом гейте — сценарий
+  невалидного порта перекрывался выдачей свободных портов; это и есть цена записи ожиданий заранее.
+- **Оценку делает очередь, а не супервизор.** `loopgate/gates/estimate_task.py` считает p50/p90 по завершённым
+  ранам и предлагает `cap = max(15 мин, round_up(2 × p90))` при ≥3 измерениях; при меньшем числе ранов —
+  пол и явная пометка. Мост передаёт cap как `--max-runtime`: на cap-е диспетчер убивает воркера и
+  пере-ставит задачу, поэтому «работал вечно» — видимый отказ. Оценивать себя — работа того, чью
+  оптимизм проверяют, поэтому цифра берётся из истории, а не из обещания.
+
+## Внешний якорь и визуальные проверки (этап 7)
+
+- **Подписывать надо вердикт, а не файл.** Якорь `loop_gate_pass.json` на каждом прогоне получает новый
+  `generated_at`, поэтому подпись над файлом умирает на следующем прогоне. Подписывается канонический
+  payload (`marker` + `verdict_hash`) — он стабилен, пока стабилен набор вердиктов.
+- **`ssh-keygen -Y sign` не перезаписывает существующий `.sig`** (exit 0, старая подпись остаётся на
+  месте): после смены вердикта повторная подпись молча верифицировала бы предыдущий. Удалять целевой
+  файл подписи перед подписью; регресс R24 держит это.
+- **Свидетеля проверяет оператор, а не гейт.** Локальная проверка подписи офлайн (D12), внешняя запись
+  (комментарий в `example/sample-service#5`) — отдельный шаг `check-external`, потому что гейт не ходит в сеть.
+  Граница честности: ключ на этой же машине доказывает владение ключом, а не независимость; внешняя запись
+  делает заметной согласованную перезапись.
+- **Визуальная проверка — не «скриншот ради скриншота».** Сценарии требуют минимум один скриншот, а
+  evaluator ловит то, чего не видит JSON: первый же vision-разбор нашёл заголовок, обрезанный посреди
+  слова без многоточия. Правило проверялось снятием фикса — иначе оно декорация.
+- **Headless-браузер обязателен и проверяется гейтом.** Визуальный чек, который молча скипается при
+  отсутствии браузера, хуже отсутствия чека (D13 падает, если браузера нет).
+
+## Артефакты
+
+```
+artifacts/loop_state.json        состояние петли (round, phase, readiness/evidence/risk, blockers, marker)
+artifacts/rounds/round_NN.md     по одному файлу на раунд: gap → change → evidence → metrics → next
+artifacts/loop_gate_report.json  машинный вывод гейта (--report)
+artifacts/issue_bridge_report.json  что мост сделал с очередью issues (queued / needs-triage / skipped)
+handoff/latest_loop.json         маркер, статус, пути артефактов
+handoff/supervisor_synthesis.md  один синтез супервизора
+configs/repo_profiles.json       контракт репозитория-цели: бандл доказательств, PR-правила, assignee
+```
+
+`artifacts/` и `handoff/` — состояние, а не исходники: они в `.gitignore`.
+
+## Инварианты
+
+- Никакого заявления об успехе без воспроизводимой команды или видимого артефакта.
+- Ремонт только по релевантным файлам; широкие переписывания запрещены.
+- Секреты, ключи и приватные данные в артефакты не попадают.
+- Маркер PASS печатает только гейт, не агент.
+- Печать вердикта никогда не зависит от возможности записи: если `--report` или якорь не пишутся
+  (read-only песочница codex/agy), гейт печатает warning и всё равно выдаёт маркер — гейт, умирающий
+  после «9 ok», неотличим от сломанного.
+- Метрики в `loop_state.json` не выдумываются: они должны согласовываться с артефактами раундов.
+
+## Маршрутизация ролей по движкам (проверено прогонами)
+
+| Задача | Движок | Почему |
+|---|---|---|
+| карта репо, чтение, ревью, команды, прогон гейта | `agy` | read-only идёт в git-worktree: команды выполняются, записи не попадают в твоё дерево; gitignored-состояние попадает в worktree через `.worktreeinclude` (`artifacts/`, `handoff/`) — проверено: гейт в worktree даёт 9 ok и PASS |
+| прогон проектного гейта, evaluator, всё, что должно видеть реальное дерево | `codex` | нативный read-only sandbox: читает дерево целиком (включая gitignored), запись запрещена |
+| второе мнение, независимое ревью, команды | `grok` | read-only разрешает выполнение команд, видит реальное дерево |
+| worker по умолчанию: фичи, фиксы, тесты, правки скриптов | `harness` | DeepSeek Harness (`deepseek-v4.1-flash` через `opencode-go`), edit в git-worktree; песочницы нет — изоляцию даёт worktree |