Слой проверок — часть протокола, а не набор вспомогательных скриптов
Harness разделяет рассуждение модели и детерминированные инварианты. Модель анализирует требования, архитектуру и код, но структура документов, переходы команд, отпечатки, проекции, схемы отчётов ревью, маршрут обновления и безопасность Git проверяются инструментами Python под .harness/tools/.
Главный валидатор целостности Harness
.harness/tools/validate.py
Агрегирует состояние репозитория, manifest и политики, целостность проекта, контракты планирования, проекции, отчёты, lock обновления и другие обязательные инварианты.
python3 .harness/tools/validate.py --mode manual
python3 .harness/tools/validate.py --mode commit
python3 .harness/tools/validate.py --mode ciВ tracked и staged файлах валидатор также проверяет гигиену секретов: вложенные .env, приватные SSH/PEM/PGP-ключи, хранилища сертификатов, Terraform state и характерные токены AWS/GitHub/GitLab/Slack. Разрешённые примеры вроде .env.sample и .env.template не должны давать ложный запрет.
.harness/tools/run-self-tests.py
Канонический runner synthetic regression suite автоматически обнаруживает все .harness/tools/*-self-test.py, запускает их в стабильном порядке и продолжает suite после отдельного failure, чтобы показать полный набор проблем. Новый self-test не требует отдельной ручной регистрации в CI.
python3 .harness/tools/run-self-tests.py
python3 .harness/tools/run-self-tests.py --list
python3 .harness/tools/run-self-tests.py --jsonPASS self-tests доказывает известные positive/negative regressions самих gates, но не заменяет запуск validate.py на текущем repository state.
Коды завершения validate.py: 0 — PASS, 1 — FAIL, 2 — BLOCKED: обязательный контекст или зависимости недоступны.
Маршрутизация и переходы команд
.harness/tools/harness-dispatch.py
Единая граница обычного выполнения канонической команды. Dispatcher принимает исходный ввод, нормализует его по .harness/command-transitions.json, выполняет структурную проверку всей цепочки, ведёт состояние выполнения, применяет предусловия и выбирает детерминированный обработчик либо точную смысловую передачу модели.
python3 .harness/tools/harness-dispatch.py start --command 'STEP RUN STEP-024'После смысловой работы фактический результат возвращается через complete; продолжение цепочки и восстановление после прерывания снова вычисляет dispatcher.
.harness/tools/validate-command.py
Диагностическая проверка без изменений: нормализует команду или цепочку и проверяет её по тому же реестру. Неизвестный переход означает INVALID_CHAIN и ноль выполненных сегментов.
python3 .harness/tools/validate-command.py --json -- 'GIT CHECK > COMMIT > PUSH > PR'.harness/tools/check-command-references.py
Ищет устаревшие или неканонические ссылки на команды в актуальных документах.
python3 .harness/tools/check-command-references.py
python3 .harness/tools/check-command-references.py --jsonDRIFT является результатом аудита и не считается сбоем самой проверки; BLOCKED используется, если документ нельзя безопасно прочитать или определить область проверки.
Справка и оперативная диагностика
.harness/tools/harness-help.py
Формирует справку HARNESS HELP непосредственно из метаданных .harness/command-transitions.json: каноническая команда, краткое описание и стабильная ссылка на документацию берутся из одного реестра.
python3 .harness/tools/harness-help.py
python3 .harness/tools/harness-help.py --json.harness/tools/harness-ux.py
Обслуживает команды без изменений для повседневной диагностики: состояние Harness, безопасное продолжение выполнения, диагностику зависимостей, эффективную конфигурацию и просмотр STEP.
python3 .harness/tools/harness-ux.py status --json
python3 .harness/tools/harness-ux.py resume --json
python3 .harness/tools/harness-ux.py doctor --json
python3 .harness/tools/harness-ux.py config --json
python3 .harness/tools/harness-ux.py step-list --json
python3 .harness/tools/harness-ux.py step-show --step STEP-024 --jsonРежим doctor разделяет обязательные зависимости ядра и необязательные возможности: отсутствие второго AI-инструмента или gh само по себе не делает Harness неработоспособным.
Граница между моделью и детерминированной механикой
Режим вычислений каждой команды хранится в .harness/command-transitions.json как reasoning: none | required | conditional. .harness/tools/reasoning-boundaries.py строит из него проверяемую документацию и машиночитаемую проекцию .harness/reasoning-boundaries.json.
.harness/tools/verification.py
Запускает машинно исполнимые Verification-команды без shell в отдельной группе процессов, применяет таймаут ко всей группе, считает хэш и размер полного вывода и держит в памяти только ограниченный tail. Изменение Git refs/HEAD во время проверки даёт VERIFICATION_MUTATED_REFS. Модель не может заменить реальный результат проверки.
.harness/tools/semantic-writer.py
Принимает структурированный смысловой результат модели и детерминированно записывает PLAN, planning review и STEP review: схему, отпечатки, точную ревизию и метаданные проверок.
.harness/tools/git-action.py
Выполняет разрешённые Git mutation и проверяет их постусловия. Для commit/push он повторно сверяет проверенное состояние, а Pull Request делегирует configured provider adapter.
.harness/tools/pr_provider.py
Provider-neutral слой Pull Request. Валидирует пары github → gh и gitea → tea, выполняет exact lookup/create/read и не позволяет модели выбирать provider или login profile.
.harness/tools/runtime_adapter_contract.py
Проверяет machine-readable Runtime Adapter Contract: lifecycle methods, capabilities Codex/Claude и закрытый набор normalized events. Unknown schema/event или неявная capability fail-closed.
.harness/tools/runtime_adapter_conformance.py
Общая deterministic conformance suite для runtime adapters и scripted test runtime.
.harness/tools/reasoning-boundaries.py
Проверяет и публикует границы вычислений модели. Изменение маршрутизации команды должно синхронно менять этот контракт.
Документы, планирование и целостность проекта
.harness/tools/document_contract.py
Парсер Markdown/frontmatter schema-v1: дубли разделов, H1, обязательные поля, заполнители, хэши и атомарная запись UTF-8.
.harness/tools/planning_contract.py
REQ/ADR/OQ/STEP IDs, зависимости, флаги риска, правила изменений, доказательства завершения, блокирующие OQ, отпечатки плана/контекста и соответствующая проверка плана.
.harness/tools/project_integrity.py
Собирает ошибки модели проектных документов в единый список для validate.py и INIT finalization.
.harness/tools/projection_contract.py
Строит канонические проекции, блокирует работу при ошибках построения и требует точного побайтового совпадения отслеживаемых копий.
.harness/tools/template_contract.py
Проверяет проектные шаблоны schema-v1 для STEP/REQ/ADR/OQ/review/report. Их изменение выполняется через восстановление согласованности, а не скрытое самообновление.
.harness/tools/harness_config.py
Строгий парсер manifest/frontmatter/TOML: дубли ключей и контроль путей относительно репозитория.
Эти модули в основном являются внутренними границами проверок. Пользователь обычно вызывает их через публичные CLI-проверки.
Качество, прослеживаемость и состояние проекта
Эти инструменты не дублируют смысловую работу модели. Они превращают её входы и результаты в единые машиночитаемые контракты, которыми одинаково пользуются Codex, Claude Code, UI и CI.
.harness/tools/requirements-quality.py
Проверяет машиночитаемый контракт обмена Requirements Quality Gate: статусы PASS, NEEDS_INPUT, BLOCKED, поля severity и owner и вопросы, которые действительно требуют решения пользователя.
python3 .harness/tools/requirements-quality.py --payload-file result.json.harness/tools/principles.py
Читает и валидирует Project Principles (PRN-NNN): жизненный цикл, severity, scope, ссылки на REQ/ADR и supersession. Применимость остаётся задачей planner/reviewer, а структура и актуальность — детерминированными.
.harness/tools/traceability-coverage.py
Строит граф без изменения репозитория REQ → STEP → completion/evidence proof и состояния uncovered, covered, verified, stale_evidence, blocked.
python3 .harness/tools/traceability-coverage.py --json.harness/tools/completion-gate.py
Перед закрытием STEP проверяет машинно доступные критерии приёмки, Verification PASS, актуальную ревизию и актуальный контракт задачи и предварительные условия. Смысловой результат проверки завершённости маршрутизируется в PASS, FIX или BLOCKED.
python3 .harness/tools/completion-gate.py STEP-024 --json.harness/tools/context-contract.py
Строит минимальный независимый от среды исполнения контекст для planner, implementer или reviewer вместо предварительной загрузки всего репозитория.
python3 .harness/tools/context-contract.py STEP-024 --role planner --json
python3 .harness/tools/context-contract.py STEP-024 --role reviewer --json.harness/tools/execution-groups.py
Проверяет необязательный DAG групп реализации, их зависимости, mutationPaths, покрытие плана реализации и потенциально независимые группы.
python3 .harness/tools/execution-groups.py STEP-024 --json.harness/tools/impact-analysis.py
Без изменений репозитория объясняет, какие готовые планы устарели после изменения REQ/ADR/OQ/STEP/PRN и какое точное действие требуется.
python3 .harness/tools/impact-analysis.py --step STEP-018 --json
python3 .harness/tools/impact-analysis.py --changed REQ-007 --json.harness/tools/project-state.py
Даёт UI и интеграциям стабильный JSON-снимок состояния проекта без изменений репозитория: артефакты, связи, блокирующие проблемы, битые ссылки, актуальность планов, группы выполнения и пути, определённые через manifest.
python3 .harness/tools/project-state.py --jsonВалидатор проекций
.harness/tools/sync-projections.py
Строит ожидаемые SPEC.md, STATUS требований/проекта, дорожную карту и индекс открытых вопросов из канонических REQ/STEP/OQ и сравнивает отслеживаемые копии побайтово.
# read-only
python3 .harness/tools/sync-projections.py --check --json
# regeneration
python3 .harness/tools/sync-projections.py --jsonВ --check: 0 — PASS, 1 — DRIFT. В режиме изменения: 0 — UPDATED/PASS, 2 — BLOCKED, если каноническое состояние нельзя безопасно превратить в проекцию.
Проверка финализации PROJECT INIT
.harness/tools/finalize-project-init.py
Единственный корректный путь выставить project.initialized=true. Проверяет описание проекта, канонические REQ, STEP, целостность проекта, проекции, два соответствующих PASS-отчёта INIT и отсутствие блокирующих OQ уровня проекта.
# только проверить preconditions
python3 .harness/tools/finalize-project-init.py \
--name '<project-name>' --check --json
# finalize
python3 .harness/tools/finalize-project-init.py \
--name '<project-name>' --jsonКоды завершения: 0 — PASS/INITIALIZED, 1 — BLOCKED. Изменение атомарно: при неуспешной postcondition исходный manifest восстанавливается.
Проверки ревью и неизменяемые контракты отчётов
.harness/tools/review_gates.py
Проверка без изменений определяет минимально обязательные проверки безопасности и тестов по политике, типу STEP, флагам риска и фактически изменённым областям. Ошибка Git не превращается в пустую поверхность ревью: такой случай блокирует проверку.
python3 .harness/tools/review_gates.py STEP-042 --json.harness/tools/review_contract.py
Проверяет историю ревью реализации, планирования, INIT и миграций: схему, точную ревизию репозитория, вердикт, specialized evidence, хэши и неизменяемую идентичность. Для Review Contract v2 machine section обязана быть полной: partial/legacy transport forms не принимаются как v2. Отчёт с недопустимо будущим created_at отклоняется, а активный STEP REVIEW сохраняет данные происхождения созданного отчёта — path, sha256, revision и основание gate.
python3 .harness/tools/review_contract.py --json
python3 .harness/tools/review_contract.py --step STEP-042 --json
python3 .harness/tools/review_contract.py --file planning/reviews/STEP-042/REVIEW-<timestamp>.md --current-revision --json.harness/tools/review_findings.py
Нормализует Review Contract v2 findings для deterministic REVIEW → FIX handoff. Проверяет обязательные поля, stable fingerprint и duplicate identity; неполная структура fail-closed блокируется вместо заполнения догадками.
.harness/tools/repair_cycle.py
Сравнивает consecutive immutable v2 reports по finding fingerprints, repository revision, contract_basis, verification_basis и factual verification status. Возвращает bounded telemetry и conservative stop decision continue | NO_PROGRESS | REPEATED_FINDINGS | REGRESSION.
Коды завершения review contract: 0 — PASS, 1 — FAIL.
Сохраняемые операционные отчёты
.harness/tools/report_contract.py
Проверяет отчёты аудита, готовности к релизу, поиска навыков и обновления Harness: схему, тип, метаданные, временную идентичность и обязательные разделы.
python3 .harness/tools/report_contract.py --all --json
python3 .harness/tools/report_contract.py \
--file planning/harness-updates/UPDATE-<timestamp>.md \
--kind harness_update --jsonКоды завершения: 0 — корректно, 1 — некорректно.
Детерминированная предварительная проверка Git
.harness/tools/git-preflight.py
Проверка безопасности без изменений перед изменяющей операцией Git. Проверяет строгий .harness/git-policy.toml, правила веток и защищённых веток, состояние индекса/рабочего дерева, расхождение с удалённой веткой, configured PR provider/tool pair и проверку Harness. Для Pull Request поддерживаются github → gh и gitea → tea; несовместимая пара блокируется до mutation. При PASS возвращает точный план изменяющей операции.
python3 .harness/tools/git-preflight.py check --json
python3 .harness/tools/git-preflight.py commit --commit-type feat --slug user-export --json
python3 .harness/tools/git-preflight.py push --json
python3 .harness/tools/git-preflight.py pr --json
python3 .harness/tools/git-preflight.py pr-finish --json
python3 .harness/tools/git-preflight.py sync --jsonДля commit/push plan привязан к конкретному проверенному snapshot. Executor сверяет вход повторно перед mutation и проверяет postconditions после неё; изменение индекса, HEAD, ветки или удалённого ref между фазами не считается автоматически допустимым.
Коды завершения: 0 — PASS, 2 — BLOCKED или ошибка конфигурации, ввода-вывода либо Git. --commit-type и --slug относятся только к предварительной проверке коммита.
Проверка состояния выполнения и recovery
.harness/tools/execution_status.py
Управляет локальным состоянием, устойчивым к сбоям, и всегда проверяет схему при чтении/записи: уникальные ID выполнения, режим/состояние, корневую/текущую команды, номер попытки, FIX/REVIEW budget, bounded repair telemetry и optional side-effect checkpoint. Повреждённый файл не трактуется как «нет незавершённых запусков».
.harness/tools/side_effect_recovery.py
Определяет bounded recovery proof для mutation attempt и классифицирует наблюдаемый внешний результат как ALREADY_APPLIED, SAFE_RETRY или AMBIGUOUS. Chat history и stdout не считаются proof.
.harness/tools/scripted_runtime.py
Test-only runtime для deterministic orchestration/fault-injection suite. Позволяет воспроизводимо инъецировать crash на logical boundaries, проверять restart/resume, exact event sequence и отсутствие duplicate side effects.
Самопроверки проверяют сами механизмы
Harness содержит синтетические регрессионные наборы для ссылок на команды, выполнения, контрактов планирования, отчётов, защиты репозитория, политики/предварительной проверки Git, конфигурации, самообновления и миграции обновлений.
python3 .harness/tools/command-references-self-test.py
python3 .harness/tools/execution-self-test.py
python3 .harness/tools/planning-contract-self-test.py
python3 .harness/tools/requirements-quality-self-test.py
python3 .harness/tools/project-principles-self-test.py
python3 .harness/tools/traceability-coverage-self-test.py
python3 .harness/tools/completion-gate-self-test.py
python3 .harness/tools/context-contract-self-test.py
python3 .harness/tools/execution-groups-self-test.py
python3 .harness/tools/impact-analysis-self-test.py
python3 .harness/tools/project-state-self-test.py
python3 .harness/tools/report-contract-self-test.py
python3 .harness/tools/repository-hardening-self-test.py
python3 .harness/tools/git-policy-self-test.py
python3 .harness/tools/git-preflight-self-test.py
python3 .harness/tools/harness-ux-self-test.py
python3 .harness/tools/harness-config-self-test.py
python3 .harness/tools/harness-update-self-test.py
python3 .harness/tools/update-migration-self-test.pyТиповые последовательности
Перед коммитом
python3 .harness/tools/git-preflight.py check --json
python3 .harness/tools/validate.py --mode commit
python3 .harness/tools/git-preflight.py \
commit --commit-type <type> --slug <slug> --jsonПосле изменения проектных документов
python3 .harness/tools/sync-projections.py --check --json
python3 .harness/tools/validate.py --mode manualПри проблемах маршрутизации команд
python3 .harness/tools/validate-command.py --json -- '<command-or-chain>'
python3 .harness/tools/check-command-references.py --json