Канонический синтаксис и цепочки
Команды Harness используют форму DOMAIN ACTION [TARGET]. Внутри одного домена соседние операции можно объединять оператором >; домен и целевой объект наследуются только там, где это явно разрешено протоколом.
PROJECT INIT
STEP ADD: Добавить экспорт PDF
STEP PLAN STEP-024 > IMPLEMENT > REVIEW
GIT CHECK > COMMIT > PUSH > PR
HARNESS UPDATE CHECK TO <tag> > APPLYОбычный запуск канонической команды проходит через единую детерминированную границу .harness/tools/harness-dispatch.py. Dispatcher нормализует вход, проверяет всю цепочку по .harness/command-transitions.json, регистрирует состояние выполнения, применяет предусловия и затем либо вызывает машинный обработчик, либо передаёт модели точный смысловой навык и минимальный контекст. .harness/tools/validate-command.py остаётся отдельной диагностической проверкой без изменений. Отсутствующий переход означает INVALID_CHAIN: ни один сегмент не запускается; нарушенное предусловие возвращает BLOCKED.
Для команд с целью STEP можно вводить сокращение из трёх и более цифр: например, STEP RUN 024 нормализуется в STEP RUN STEP-024. Тот же реестр хранит краткое описание, стабильную ссылку на документацию и режим reasoning для каждой команды. Сгенерированная .harness/reasoning-boundaries.json показывает внешним инструментам, где модель обязательна, не нужна или зависит от сценария.
STEP RUN STEP-024 > GIT COMMIT не поддерживается: работа над STEP и публикация Git остаются отдельными запусками.Оперативная справка и диагностика
HARNESS HELP
Показывает доступные команды, их краткие описания и ссылки на документацию. Список формируется непосредственно из .harness/command-transitions.json, поэтому отдельного вручную поддерживаемого реестра справки нет.
HARNESS STATUS
Показывает снимок текущего состояния Harness и проекта: релиз, инициализацию, состояние Git, незавершённые исполнения и доступность работы с Pull Request.
HARNESS RESUME
Продолжает единственное незавершённое выполнение, которое можно безопасно возобновить. Если подходящих выполнений нет или их несколько, команда возвращает BLOCKED вместо выбора наугад.
HARNESS DOCTOR
Проверяет обязательные зависимости ядра и исправность Harness отдельно от необязательных возможностей. Отсутствие второго AI-инструмента или provider CLI для Pull Request не блокирует Harness целиком: GitHub использует gh, Gitea — tea.
HARNESS CONFIG
Показывает фактически применяемую конфигурацию manifest, Git и обновления вместе с файлами, из которых получены значения.
Инициализация и планирование
PROJECT INIT
Однократная инициализация из PROJECT_BRIEF.local.md. Создаёт базу знаний проекта и начальную дорожную карту, но не код продукта.
STEP ADD: <описание>
Преобразует человеческую задачу в новый STEP с границами, зависимостями, критериями приёмки и проверками.
STEP LIST
Показывает компактный список канонических STEP: ID, название, состояние жизненного цикла, приоритет, тип, фазу, состояние плана и путь к файлу.
STEP SHOW STEP-NNN
Показывает подробное состояние одного STEP: метаданные, план, зависимости, связанные REQ/ADR, флаги риска, последнюю применимую проверку и незавершённые исполнения. Допускает сокращённую цель, например STEP SHOW 024.
STEP PLAN STEP-NNN
Сначала проверяет непротиворечивость задачи, затем сохраняет план реализации и запускает независимую семантическую проверку плана. План становится готовым только при совпадающем PASS и актуальных отпечатках контекста и содержимого.
STEP NEXT
Детерминированно, без вызова модели, рекомендует следующую каноническую команду. Сначала учитывает безопасно возобновляемое выполнение, затем ранжирует доступные STEP по состоянию, приоритету, влиянию на последующие задачи, явным рискам и порядку дорожной карты. Это рекомендация, а не планирование спринта.
PROJECT STATUS
Детерминированно пересобирает проекции, проверяет целостность проекта и возвращает структурированный снимок состояния вместе с рассчитанным STEP NEXT. Модель не интерпретирует статус проекта и не дополняет результат предположениями.
Команды PLAN и REVIEW проходят разные проверки качества
STEP ADD / STEP PLAN
Requirements Quality проверяет, достаточно ли определён контракт; Planning Consistency — согласован ли он; применимые блокирующие PRN-NNN становятся обязательными инженерными ограничениями.
STEP REVIEW
Сначала проверяется реализация. Даже при вердикте ревью PASS STEP закрывается только после отдельного Completion / Convergence Gate.
PROJECT STATUS
Сводка использует детерминированное состояние проекта, покрытие прослеживаемости и актуальность планов; клиенты не должны восстанавливать эти факты из текста Markdown.
Выполнение и контроль
STEP IMPLEMENT STEP-NNN
Модель реализует только актуальный утверждённый план в пределах контракта задачи. Перед успешным завершением dispatcher запускает команды из раздела Verification через .harness/tools/verification.py, а фактические Evidence формируются детерминированно; ответ модели сам по себе не может объявить проверку успешной.
STEP REVIEW STEP-NNN
Независимая модель проверяет задачу, реализацию и доказательства для точной ревизии репозитория. При FAIL Review Contract v2 требует machine-readable findings со stable id/fingerprint, точным location, сценарием, expected/observed, влиянием, направлением исправления, ограничениями и evidence. Детерминированный отбор заранее определяет обязательные проверки безопасности и тестов, а .harness/tools/semantic-writer.py фиксирует точную ревизию, основания проверок и неизменяемый отчёт. Неполный или malformed v2 finding отклоняется fail-closed. Даже PASS закрывает STEP только при наличии требуемого для его типа доказательства завершения.
STEP FIX STEP-NNN
Исправляет только замечания к реализации и доказательствам из последнего применимого FAIL-отчёта. FIX получает findings через детерминированный parser .harness/tools/review_findings.py и использует stable fingerprint как identity замечания между циклами. Legacy/malformed/ambiguous handoff не угадывается: выполнение блокируется до свежего REVIEW. Проблема контракта переводит выполнение в BLOCKED, а не расширяет границы исправления.
STEP RUN STEP-NNN
Для обычных задач разработки dispatcher детерминированно оркестрирует переходы STEP PLAN → STEP IMPLEMENT → Verification → STEP REVIEW → STEP FIX/REVIEW → финализацию без отдельного вызова модели между фазами. Verification-команды запускаются через .harness/tools/verification.py. Модель по-прежнему выполняет смысловую работу внутри PLAN, IMPLEMENT, REVIEW и FIX; специальные типы STEP могут использовать смысловую оркестрацию самого STEP RUN.
execution.maxFixReviewCycles (1–5; по умолчанию 3), но может остановиться раньше по deterministic evidence. .harness/tools/repair_cycle.py сравнивает immutable Review Contract v2 reports и блокирует дальнейший FIX при NO_PROGRESS, REPEATED_FINDINGS или REGRESSION. Первый FAIL никогда не останавливается адаптивно; при изменении contract scope сравнение отключается fail-safe. Проверки безопасности и тестов подключаются только при необходимости.STEP AUDIT STEP-NNN
Без изменений проверяет фактическое состояние; найденные дефекты превращаются в замечания или корректирующие задачи.
PROJECT RECONCILE
Ищет расхождения между кодом, тестами и конфигурацией и REQ/ADR/OQ/архитектурой/STEP/доказательствами. Также выполняет ожидающую миграцию активных проектных документов после обновления Harness.
RELEASE CHECK
Проверяет условия выпуска: замечания, требования, миграции, тесты и сборку, безопасность, документацию и вопросы развёртывания.
Состояние выполнения и восстановление после прерывания
Каждый запуск имеет корневую команду и режим single, chain или orchestration. Текущее состояние хранится локально в .harness/local/execution/execution-status.json, а все read-modify-write операции сериализуются через .harness/local/execution/execution-status.lock. Это предотвращает потерю состояния между параллельными сессиями и подагентами.
Текущий формат schemaVersion: 2 хранит полные записи только для активных или возобновляемых выполнений, отдельные stepRecovery proofs и ограниченное окно recentTerminals. Для mutation-команд активная запись также может содержать bounded current.context.sideEffect: proof одной попытки с фазами prepared → side_effect_started → side_effect_observed → postconditions_verified. После restart executor сначала наблюдает внешний факт и классифицирует его как ALREADY_APPLIED, SAFE_RETRY или AMBIGUOUS, поэтому commit/push/PR не повторяются вслепую.
Завершённая история автоматически компактизируется вместо бесконечного роста файла, а миграция старого локального формата выполняется самим execution layer — PROJECT RECONCILE здесь не участвует. HARNESS STATUS показывает незавершённые исполнения вместе с остальным состоянием проекта, а HARNESS RESUME безопасно продолжает единственное однозначно возобновляемое выполнение. Во время активного .harness/local/update-journal/ тот же lock образует границу с самообновлением: новые канонические изменения execution state ждут завершения commit/rollback обновления.
Мелкие изменения
PROJECT QUICK FIX: <описание>
Небольшая правка с низким риском без искусственного REQ/ADR/STEP. Если меняется контракт или уровень риска, команда останавливается и предлагает STEP ADD.
Навыки и шаблоны GitHub
SKILL FIND: <описание>
Ищет и проверяет навыки, сохраняет отчёт с числом кандидатов до значения skills.search.maxResults и ничего не устанавливает.
SKILL INSTALL: <source | #N>
Повторно проверяет выбранный навык и устанавливает весь bundle с фиксацией exact provenance в UPSTREAM.md, реестра и маршрутизации. Third-party scripts не запускаются автоматически.
SKILL CREATE: <описание>
Создаёт собственный project-native навык, если подходящего готового варианта нет, и добавляет UPSTREAM.md с Source: project-native, references и rationale.
GITHUB GENERATE TEMPLATES
Перегенерирует формы задач GitHub и шаблон PR по фактическому набору инструментов проекта.
Обновление Harness
HARNESS UPDATE CHECK [TO <tag>]
Dispatcher вызывает детерминированный механизм .harness/tools/harness-update.py напрямую, без вызова модели: маршрут, правила владения, BASE/OURS/THEIRS и коллизии вычисляются машинно. Текущий BASE берётся из .harness/harness.lock.json, а допустимый маршрут — из канонического .harness/harness-update-graph.json. Без TO конечная версия берётся из поля latest; с TO <tag> используется указанный тег, но он всё равно должен быть достижим по графу. Проверка моделирует переходы по маршруту и не меняет рабочее дерево.
HARNESS UPDATE APPLY [TO <tag>]
Dispatcher выполняет обновление напрямую, без вызова модели. Каждый переход выполняется как отдельная аварийно-устойчивая транзакция с журналом .harness/local/update-journal/: до первой записи сохраняются затрагиваемые управляемые пути, lock и локальное состояние выполнения. После записи целевого состояния запускается валидатор постусловий, а неизменяемый отчёт UPDATE-*.md публикуется только после PASS. Если процесс оборвался, незавершённый журнал не маскируется как обычное состояние: HARNESS UPDATE CHECK возвращает UPDATE_JOURNAL_PENDING, а следующий HARNESS UPDATE APPLY сначала восстанавливает прерванный переход и только затем повторяет обновление. Если переход требует перезапуска, команда останавливается на достигнутом релизе и после перезапуска повторяется к исходной конечной версии.
.harness/harness-update-graph.json. Граф хранит только данные маршрутизации и не может запускать скрипты/хуки или подменять содержимое неизменяемых релизов.Операции Git
.harness/tools/git-preflight.py вычисляет PASS/BLOCKED и точный план операции; изменение выполняется только после PASS. Обычные GIT CHECK, GIT COMMIT, GIT PUSH и GIT SYNC требуют только Git. Для Pull Request Harness использует configured provider/tool pair: github → gh или gitea → tea; неизвестная или несовместимая пара блокируется fail-closed.GIT CHECK
Полностью детерминированная проверка без вызова модели: dispatcher запускает .harness/tools/git-preflight.py, который проверяет политику Git, ветку, удалённое состояние, расхождение, индекс и целостность Harness.
GIT COMMIT / GIT COMMIT: <подсказка>
Создаёт локальный коммит по правилам Conventional Commits и git-policy, но не доверяет состоянию между предварительной проверкой и фактическим git commit. До validator фиксируется снимок ветки, родителя и дерева индекса; прямо перед commit он сверяется повторно, а после commit проверяются фактические ветка/родитель/дерево. Пользовательские хуки Git выполняются штатно. Если hook изменил проверенное состояние, команда возвращает COMMIT_POSTCONDITION_FAILED и пытается компенсировать только доказанно принадлежащую этой операции изменение ref через reflog/CAS; разрушительный git reset --hard не используется.
GIT PUSH
Публикует текущую ветку без принудительной отправки после проверки удалённого состояния и правил безопасности. При отдельном запуске модель проверяет смысловую целостность отправляемого изменения; если PUSH идёт сразу после доказанного GIT COMMIT в той же цепочке, dispatcher использует детерминированный быстрый путь и машинно подтверждает, что удалённый HEAD действительно продвинулся.
GIT PR
Модель формирует только смысловые текстовые поля PR — заголовок и описание. Поиск существующего PR, создание или переиспользование, проверка опубликованной ветки и точного HEAD выполняются детерминированно через .harness/tools/pr_provider.py и .harness/tools/git-action.py. GitHub использует gh, Gitea — tea; для self-hosted Gitea host берётся из configured push.remote, а неоднозначный login profile возвращает PROVIDER_LOGIN_AMBIGUOUS. После успеха сохраняется локальный .harness/local/git/pr-state.json с provider identity, номером PR, ветками и точкой возврата.
GIT PR FINISH
Полностью детерминированно завершает локальный жизненный цикл ветки после слияния PR. Проверяет provider state MERGED, чистое рабочее дерево, совпадение локального HEAD с сохранённым head SHA и возможность безопасно обновить ветку возврата. Обычное, squash- и rebase-слияние поддерживаются без принудительного удаления ветки. Provider-specific чтение состояния проходит через тот же configured GitHub/Gitea adapter.
git branch -D, удаление удалённой ветки, reset и автоматический rebase не используются.GIT SYNC
Без вызова модели получает состояние удалённого репозитория и показывает расхождение веток; по умолчанию ничего не меняет, а в разрешённом режиме допускает только безопасный fast-forward.