codex-workflow-v2 2.0.0-alpha.2 → 2.0.0-alpha.3

package/docs/updating-existing-project.md

@@ -0,0 +1,154 @@
+# Обновление Workflow V2 в начатом проекте через Codex
+
+Эта инструкция предназначена для проекта, где Workflow V2 уже создал Discovery, Tasks или
+Milestones. Пользователь не выполняет команды самостоятельно: все проверки, установка и
+Git-операции поручаются Codex.
+
+## Что обновляется, а что сохраняется
+
+Версия `codex-workflow-v2` закреплена точным значением в `package.json` и lock-файле каждого
+проекта. Поэтому разные проекты могут использовать разные версии. Обновление одного проекта
+не переключает остальные.
+
+Состояние Workflow хранится отдельно от репозитория в
+`$CODEX_HOME/workflow-state/v2/projects/<project-id>`. Оно определяется идентичностью Git
+репозитория, а не версией npm-пакета. Обычное совместимое обновление заменяет зависимость и
+gateway, но не удаляет и не пересоздаёт это состояние. Уже принятые Milestones, ревизии,
+авторизации, evidence и Results сохраняются.
+
+Никогда не разрешайте агенту вручную редактировать, переносить или удалять внешний state.
+Команда миграции нужна только тогда, когда документация новой версии прямо сообщает о новой
+state schema. Совпадение `stateSchemaVersion` до и после обновления означает, что миграция не
+нужна.
+
+## 1. Подготовьте отдельный чат обновления
+
+Не обновляйте пакет во время выполняющегося Worker Step. Дождитесь завершения текущего ответа
+Codex и откройте в нужном проекте отдельный чат `Workflow update`.
+
+Передайте агенту этот промпт, заменив `<НОВАЯ_ВЕРСИЯ>` точной опубликованной версией:
+
+```text
+Обнови Codex Workflow V2 в этом проекте до точной версии <НОВАЯ_ВЕРСИЯ>
+из npm: https://www.npmjs.com/package/codex-workflow-v2.
+
+Все команды выполняешь ты. Сначала прочитай AGENTS.md и определи Git root.
+До изменений запусти project-local gateway handshake, doctor, status и next;
+зафиксируй текущую версию, protocolVersion, stateSchemaVersion, projectId,
+активные сущности и наличие writer lease. Если Worker сейчас выполняется,
+остановись без обновления.
+
+Обнови только точную npm-зависимость и lock-файл, без диапазона версий.
+Не удаляй и не редактируй вручную $CODEX_HOME/workflow-state/v2.
+Не запускай state migration, если stateSchemaVersion не изменилась.
+После установки проверь совпадение declared и installed версии, выполни
+handshake, doctor, status и next новой версией. Затем установи или обнови
+персональный codex-workflow-gateway из установленного npm-пакета штатным
+installer скриптом. Покажи diff файлов репозитория и результаты проверок.
+Не начинай продуктовую реализацию в этом чате.
+```
+
+Агенту может потребоваться ваше разрешение на установку npm-зависимости и запись персонального
+plugin за пределами workspace. Это ожидаемая граница безопасности Codex, а не миграция state.
+
+## 2. Проверьте отчёт чата обновления
+
+До завершения чат должен подтвердить:
+
+1. В `package.json` указана точная версия без `^`, `~`, `latest` или `next`.
+2. Lock-файл и фактически установленный пакет содержат ту же версию.
+3. Handshake возвращает ожидаемые package/protocol/state-schema версии.
+4. `doctor` не сообщает о несовместимой зависимости или повреждённом state.
+5. `projectId` совпадает со значением до обновления.
+6. Существующие Task/Milestone ID, revisions и terminal statuses сохранились.
+7. Персональный gateway обновлён из установленного пакета.
+
+Изменение `projectId`, исчезновение сущностей или ошибка unsupported state schema — причина
+остановиться. Не соглашайтесь на «починку» удалением state. Агент должен вернуть dependency к
+предыдущей точной версии либо ждать официального мигратора.
+
+## 3. Откройте новый чат после установки gateway
+
+Codex загружает набор skills/plugin при старте чата. Уже открытый чат может продолжать видеть
+старую gateway-инструкцию, даже если файлы plugin обновлены. Поэтому дальнейшую работу всегда
+начинайте в новом чате проекта.
+
+Промпт для контрольного чата:
+
+```text
+Возобнови проект через установленный Codex Workflow V2.
+Все команды выполняешь ты. Начни с AGENTS.md, project-local gateway
+handshake, doctor, status и next. Подтверди точную declared/installed
+версию, protocolVersion, stateSchemaVersion и прежний projectId.
+
+Проверь Knowledge Map штатно. Если изменение package.json или lock-файла
+сделало карту stale, выполни scan/reconcile и покажи мне классификацию и
+изменения до approve. Не редактируй внешний workflow-state вручную.
+Следуй только текущему ответу next и остановись перед любой human gate.
+```
+
+Обновление dependency меняет `package.json` и обычно lock-файл. Если один из этих файлов входит
+в Knowledge Map, изменение его content hash штатно делает карту `stale`. Это не потеря state:
+нужно выполнить `scan/reconcile`, показать пользователю изменения классификации и получить
+approval, если он требуется.
+
+## 4. Продолжите начатый Milestone или создайте следующий
+
+Terminal Milestone со статусом `accepted` остаётся закрытым. Для следующего результата нужно
+начать новый Discovery и материализовать новый Milestone; переписывать историю предыдущего не
+следует.
+
+Промпт для планирования следующего Milestone:
+
+```text
+Создай следующий Milestone проекта через Workflow V2.
+Все команды выполняешь ты. Начни с AGENTS.md, gateway handshake, doctor,
+status и next. Проверь Knowledge Map штатно и показывай мне её смысловые
+изменения до approve.
+
+Проведи Discovery: outcome, scope, out-of-scope, acceptance, constraints,
+unknowns и success signal. Не materialize сущность при blocking unknowns.
+После согласования создай Milestone и тонкие связанные Tasks, подготовь
+membership Plan и покажи его мне для execution authorization. После моей
+явной авторизации доведи Milestone до active, выдай порядок required Tasks
+и остановись. Реализацию в этом чате не начинай.
+```
+
+## 5. Как теперь закрывается Milestone
+
+После merge всех `required` Tasks откройте отдельный чат финальной проверки:
+
+```text
+Возобнови Milestone <MS-ID> и подготовь его к финальному принятию.
+Все команды и проверки выполняешь ты. Начни с AGENTS.md, handshake,
+doctor, status и next. Проверь, что все current required memberships merged,
+выполни штатную Milestone validation и покажи Result, evidence, checks и
+validated HEAD.
+
+Когда next вернёт requiredHumanGate, покажи мне все связанные поля и код
+подтверждения, запроси моё явное final acceptance и заверши ответ. Не
+вызывай milestone accept в этом же ответе и не считай этот промпт заранее
+выданным согласием.
+```
+
+После этого Codex должен остановиться. Если результат устраивает, ответьте отдельным сообщением:
+
+```text
+Принимаю Milestone <MS-ID> для revision <REVISION> с кодом <MSA-CODE>.
+Выполни штатный final acceptance и подтверди status accepted.
+```
+
+Код связан с Milestone ID, revision, Plan hash, Result hash, evidence hash и validated HEAD.
+Если любой из них изменился, старый код недействителен и агент должен повторно показать новую
+границу принятия.
+
+## 6. Проверка исправленного `next`
+
+`next` не должен возвращать незапущенную историческую Task, если её текущее membership имеет
+disposition `waived`/`cancelled` либо её Milestone уже `accepted`/`cancelled`. Для активного
+Milestone он выбирает только `required` Tasks. Уже начатая Task может завершить допустимый
+переход, поэтому её наличие анализируется отдельно от незапущенной истории.
+
+Если после совместимого обновления `next` всё ещё показывает неподходящую Task, агент должен
+собрать `status`, целевые Task/Milestone state и memberships и остановиться с диагностикой. Не
+следует вручную менять JSON state или обходить transition checks.

package/docs/validation-report.md

@@ -1,20 +1,26 @@
 # V2 Alpha Validation Report
 
-Release candidate `2.0.0-alpha.2` was validated on 2026-08-08 with Node.js 24.17.0.
+Release candidate `2.0.0-alpha.3` was validated on 2026-08-12 with Node.js 24.17.0.
 
 - TypeScript typecheck and build passed.
-- All 37 unit and integration tests passed. Coverage includes the complete Task lifecycle,
+- All 41 unit and integration tests passed. Coverage includes the complete Task lifecycle,
   a Project Knowledge Map change between Steps, preservation of completed Step evidence,
   mandatory reauthorization, the public `task knowledge-rebind` CLI route, no-op and active
   Worker rejection, current gateway capability negotiation, and rejection of deprecated
   state schema instead of migration.
-- Milestone amendments and acceptance, graph binding, deterministic V1 snapshot, symlink
-  rejection, writer leases, and strict reviewer fail-closed behavior also passed.
-- npm dry-run packaging produced `codex-workflow-v2-2.0.0-alpha.2.tgz` with runtime, schemas,
+- Milestone scheduling now ignores unstarted Tasks with cancelled/waived or terminal
+  membership paths. Final Milestone acceptance exposes a revision/hash/HEAD-bound human gate,
+  rejects a wrong code, and regenerates its code after base advancement and revalidation.
+- Milestone amendments, graph binding, deterministic V1 snapshot, symlink rejection, writer
+  leases, and strict reviewer fail-closed behavior also passed.
+- npm dry-run packaging produced `codex-workflow-v2-2.0.0-alpha.3.tgz` with runtime, schemas,
   roles, references, docs, and plugin source.
 - Downstream installation from that tarball and the packaged CLI handshake passed; the
   installation created none of the forbidden repository workflow directories.
-- Plugin validation and the repository release check passed for `2.0.0-alpha.2`.
+- Plugin validation and the repository release check passed for `2.0.0-alpha.3`.
+- The alpha.3 CLI read the existing Signal project state created by alpha.2 without migration:
+  project ID and accepted Milestone 1 were preserved, while repository-level `next` returned
+  `idle` instead of the historical cancelled Task.
 
 The strict reviewer implementation did not change in this release candidate. Its original
 2026-07-16 real Codex CLI isolation probe denied a repository write and returned

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-workflow-v2",
-  "version": "2.0.0-alpha.2",
+  "version": "2.0.0-alpha.3",
   "description": "Requirements-first Codex development workflow with local state and explicit Git ownership.",
   "repository": {
     "type": "git",

package/plugins/codex-workflow-gateway/references/protocol.md

@@ -11,6 +11,23 @@ codex-workflow gateway handshake --repo <git-root>
 Require package name `codex-workflow-v2`, protocol version `1`, state
 schema version `2`, and the capabilities needed for the requested operation. Task execution
 that may cross a Project Knowledge Map revision requires `task-knowledge-rebind-v1`.
+Milestone final acceptance requires `milestone-human-final-gate-v1`.
+
+## Milestone Human Gate
+
+At `awaiting_final_acceptance`, `next` returns `requiredHumanGate` with kind
+`milestone_final_acceptance`, Milestone ID, revision, Plan/Result/evidence hashes, validated
+HEAD, and a confirmation code. Display the complete object and end the turn. Only a later
+explicit user message that approves the same code authorizes:
+
+```text
+codex-workflow milestone accept --repo <git-root> --id <MS-ID> \
+  --expected-revision <REVISION> --actor <USER-ACTOR> \
+  --confirmation-code <MSA-CODE>
+```
+
+Do not infer approval from the request that initiated validation. A changed revision, hash,
+or HEAD requires a new gate.
 
 ## Graph Refresh Request
 

package/plugins/codex-workflow-gateway/skills/codex-workflow-gateway/SKILL.md

@@ -45,7 +45,7 @@ Do not create a memory directory or write project files during scan.
 3. Stop for user selection when more than one project remains plausible.
 4. Check `index_status`; call `index_repository` with the request source root,
    mode, and `persistence: false` when missing or stale.
-5. Build evidence exactly as specified in `references/protocol.md`.
+5. Build evidence exactly as specified in `../../references/protocol.md`.
 6. Pipe `{ "request": ..., "evidence": ... }` to `graph bind --stdin`, passing
    the current binding revision when one exists.
 
@@ -62,6 +62,19 @@ independently blocks the workflow.
 - Independent Reviewer: receives recorded evidence and confirms critical
   claims against files, Git, and tests.
 
+## Human Gates
+
+Treat `requiredHumanGate` from the project-local package as a mandatory turn boundary.
+For `milestone_final_acceptance`, show the user the Milestone ID, revision, Plan hash,
+Result hash, evidence hash, validated HEAD, and confirmation code. Ask whether the user
+accepts that exact result, then stop without invoking `milestone accept`.
+
+Only after a later user message explicitly approves and repeats the same confirmation code
+may you invoke `milestone accept` with explicit `--actor` and `--confirmation-code` values.
+A generic instruction such as “continue”, “finish”, or “bring it to final status” is not
+final acceptance. If `next` returns a different code or binding, discard the old response
+and ask again.
+
 ## Stop Conditions
 
 - Dependency version is missing, ranged, or differs from the installed package.
@@ -70,3 +83,5 @@ independently blocks the workflow.
 - A request changes before evidence is bound.
 - An action would make MCP or the local map authoritative project memory.
 - A requested mutation is not authorized by the package CLI state.
+- A human gate was emitted but the user has not approved its exact confirmation code in a
+  later message.

package/references/state-machine.md

@@ -15,4 +15,14 @@ Task is `blocked`; unrelated blocks must be resolved through their owning transi
 
 Milestone authorization is bound to its Plan and membership revision. Plan amendments
 supersede authorization. Milestone validation and acceptance are bound to the current base
-HEAD; cancellation records intent but performs no Git reversal.
+HEAD. In `awaiting_final_acceptance`, `next` returns a state-bound human gate. The agent must
+display its revision, hashes, HEAD, and confirmation code, then end the turn. Acceptance is
+valid only after a later explicit user response repeats that code; the CLI requires both an
+explicit actor and the exact code. Cancellation records intent but performs no Git reversal.
+If the base HEAD or final artifacts change before acceptance, `next` withholds the gate and
+requires Milestone validation again; revalidation supersedes the previous candidate binding.
+
+Repository-level scheduling respects current Milestone membership. An unstarted linked Task
+is eligible only for an `active` Milestone with `required` disposition. Historical unstarted
+Tasks from `waived`, `cancelled`, accepted, or cancelled Milestone paths cannot shadow the
+Milestone/repository transition returned by `next`.

package/references/validation-and-review.md

@@ -11,3 +11,8 @@ configuration and rules ignored, a read-only sandbox, structured output, and an
 write probe. The core seals repository HEAD, status, and content before/after the process.
 Any process error, malformed output, successful write, or changed seal records an
 `unverified` review and blocks Result creation and final acceptance.
+
+Milestone validation similarly binds Result and evidence to the clean base HEAD. Its final
+acceptance is a separate turn: `next` emits a confirmation code bound to the current
+revision, Plan, Result, evidence, and HEAD; the coordinator shows it and stops. A later user
+response must explicitly approve that exact code before the CLI transition is invoked.

package/roles/delivery-coordinator.md

@@ -8,5 +8,10 @@ Own state transitions, dispatch envelopes, evidence collection, and recovery gui
 - Own derived map revisions and context selection, but never edit the meaning of canonical project files.
 - Treat CLI `status`, `next`, revision, and lock state as authoritative machine state.
 - Never bypass authorization, scope checks, failed validation, or stale review.
+- When `next.requiredHumanGate` is present, show every bound field and confirmation code,
+  request the user's explicit decision, and end the turn. Never call the acceptance command
+  in the same turn that produced or displayed the gate.
+- Accept a Milestone only after a later user message explicitly approves that exact
+  confirmation code. Do not infer approval from a request to validate, finish, or continue.
 - Dispatch one Worker at a time for a concrete Step.
 - Do not make product-scope decisions or implement production changes.