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

package/docs/project-memory.md

@@ -20,12 +20,15 @@ approves canonical/supporting choices. Conflicts and missing categories remain e
   by the Plan.
 - Independent Reviewer checks that required durable knowledge changes are present and bound
   to the reviewed commit.
-- Delivery Coordinator re-scans after relevant changes and blocks stale Plan bindings until
-  the map is reconciled and reapproved.
+- Delivery Coordinator re-scans after relevant changes, reconciles and reapproves the map,
+  then uses `task knowledge-rebind` before requesting fresh execution authorization.
 
 If any approved file changes, the derived map becomes stale. `project-memory reconcile`
-updates discovered metadata; changed classifications require user approval. If local state
-is lost, the map is rebuilt from repository files.
+updates discovered metadata; changed classifications require user approval. A knowledge
+rebind is mechanical: it may change only the Plan's map revision/hash, preserves every Step
+definition, status, and evidence record, records the old/new binding, supersedes execution
+authorization, and cannot run while a Step is in progress. If local state is lost, the map
+is rebuilt from repository files.
 
 ## Codebase graph
 

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,19 +1,28 @@
 # V2 Alpha Validation Report
 
-Validated on 2026-07-16 with Node.js 24.17.0 and Codex CLI 0.144.5.
+Release candidate `2.0.0-alpha.3` was validated on 2026-08-12 with Node.js 24.17.0.
 
 - TypeScript typecheck and build passed.
-- 32 unit/integration tests passed, including Task lifecycle, Milestone amendments and
-  acceptance, Project Knowledge Map staleness, graph binding, deterministic V1 snapshot,
-  symlink rejection, writer leases, and strict reviewer fail-closed behavior.
-- npm dry-run packaging included runtime, schemas, roles, references, docs, and personal
-  plugin source.
-- downstream tarball installation and packaged CLI handshake passed; installation created
-  none of the forbidden repository workflow directories.
-- plugin source passed both the repository release check and the Codex plugin validator.
-- a real ephemeral `codex exec` read-only probe attempted to create
-  `.codex-reviewer-write-probe`; the runtime denied it with `Operation not permitted`, the
-  file did not appear, and structured output reported `isolationProbe: "denied"`.
+- 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 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.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.
 
-This report validates the listed runtime versions. The strict reviewer remains fail-closed
-on other versions: inability to prove isolation records `unverified` and blocks acceptance.
+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
+`isolationProbe: "denied"`. The reviewer remains fail-closed: inability to prove isolation
+records `unverified` and blocks acceptance.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-workflow-v2",
-  "version": "2.0.0-alpha.1",
+  "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

@@ -9,7 +9,25 @@ codex-workflow gateway handshake --repo <git-root>
 ```
 
 Require package name `codex-workflow-v2`, protocol version `1`, state
-schema version `1`, and the capabilities needed for the requested operation.
+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

@@ -6,6 +6,23 @@ to the task commit and Brief, Plan, and evidence hashes. Final acceptance is a s
 human event bound to Result, evidence, and commit. Locks expire only diagnostically;
 removing a stale lock is always an explicit repair operation.
 
+When an approved Project Knowledge Map changes between Task Steps, the coordinator first
+reconciles and obtains approval for the new map, then uses `task knowledge-rebind`. This
+mechanical transition preserves Step definitions, runtime status, and evidence, records both
+bindings, supersedes execution authorization, and returns the Task to
+`awaiting_execution_authorization`. It cannot run while a Step is `in_progress` or while the
+Task is `blocked`; unrelated blocks must be resolved through their owning transition.
+
 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

@@ -3,8 +3,15 @@
 Own state transitions, dispatch envelopes, evidence collection, and recovery guidance.
 
 - Verify Project Knowledge Map freshness before Plan authorization and role dispatch.
+- After an approved knowledge change between Steps, reconcile and approve the map, perform
+  the mechanical Task knowledge rebind, and request fresh user authorization.
 - 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.

package/schemas/discovery.schema.json

@@ -5,7 +5,7 @@
   "type": "object",
   "required": ["schemaVersion", "revision", "id", "projectId", "kind", "status", "goal", "acceptance"],
   "properties": {
-    "schemaVersion": { "const": 1 },
+    "schemaVersion": { "const": 2 },
     "revision": { "type": "integer", "minimum": 1 },
     "id": { "type": "string", "pattern": "^DISC-[0-9A-HJKMNP-TV-Z]{26}$" },
     "projectId": { "type": "string", "pattern": "^[a-f0-9]{24}$" },

package/schemas/graph-binding.schema.json

@@ -6,7 +6,7 @@
   "additionalProperties": false,
   "required": ["schemaVersion", "revision", "id", "projectId", "kind", "graphKind", "provider", "rootFingerprint", "mode", "status", "observedAt", "evidenceHash", "previous"],
   "properties": {
-    "schemaVersion": { "const": 1 },
+    "schemaVersion": { "const": 2 },
     "revision": { "type": "integer", "minimum": 1 },
     "id": { "enum": ["GRAPH-product", "GRAPH-workflow"] },
     "projectId": { "type": "string", "pattern": "^[a-f0-9]{24}$" },

package/schemas/milestone.schema.json

@@ -11,7 +11,7 @@
     "evidenceHash", "acceptedHead", "cancellationReason"
   ],
   "properties": {
-    "schemaVersion": { "const": 1 },
+    "schemaVersion": { "const": 2 },
     "revision": { "type": "integer", "minimum": 1 },
     "id": { "type": "string", "pattern": "^MS-[0-9A-HJKMNP-TV-Z]{26}$" },
     "projectId": { "type": "string", "pattern": "^[a-f0-9]{24}$" },

package/schemas/project-knowledge-map.schema.json

@@ -6,7 +6,7 @@
   "additionalProperties": false,
   "required": ["schemaVersion", "revision", "id", "projectId", "kind", "status", "entries", "gaps", "conflicts", "approval"],
   "properties": {
-    "schemaVersion": { "const": 1 },
+    "schemaVersion": { "const": 2 },
     "revision": { "type": "integer", "minimum": 1 },
     "id": { "const": "PROJECT-KNOWLEDGE-MAP" },
     "projectId": { "type": "string", "pattern": "^[a-f0-9]{24}$" },

package/schemas/task.schema.json

@@ -3,9 +3,9 @@
   "$id": "https://codex-workflow.local/schemas/task.schema.json",
   "title": "Codex Workflow V2 Task State",
   "type": "object",
-  "required": ["schemaVersion", "revision", "id", "projectId", "kind", "status", "title", "knowledgeImpact", "knowledgeTargets", "knowledgeMapRevision", "knowledgeMapHash", "graphUse", "steps", "authorizations"],
+  "required": ["schemaVersion", "revision", "id", "projectId", "kind", "status", "title", "planObjective", "knowledgeImpact", "knowledgeTargets", "knowledgeMapRevision", "knowledgeMapHash", "graphUse", "steps", "authorizations", "knowledgeRebinds"],
   "properties": {
-    "schemaVersion": { "const": 1 },
+    "schemaVersion": { "const": 2 },
     "revision": { "type": "integer", "minimum": 1 },
     "id": { "type": "string", "pattern": "^TASK-[0-9A-HJKMNP-TV-Z]{26}$" },
     "projectId": { "type": "string", "pattern": "^[a-f0-9]{24}$" },
@@ -27,6 +27,7 @@
       ]
     },
     "title": { "type": "string", "minLength": 1 },
+    "planObjective": { "type": ["string", "null"] },
     "knowledgeImpact": { "enum": ["none", "update", "create", "retire", null] },
     "knowledgeImpactReason": { "type": ["string", "null"] },
     "knowledgeTargets": { "type": "array" },
@@ -34,6 +35,23 @@
     "knowledgeMapHash": { "type": ["string", "null"], "pattern": "^[a-f0-9]{64}$" },
     "graphUse": { "enum": ["code-aware", "not-applicable", null] },
     "steps": { "type": "array" },
-    "authorizations": { "type": "array" }
+    "authorizations": { "type": "array" },
+    "knowledgeRebinds": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["recordedAt", "fromKnowledgeMapRevision", "fromKnowledgeMapHash", "toKnowledgeMapRevision", "toKnowledgeMapHash", "previousPlanHash", "reboundPlanHash"],
+        "properties": {
+          "recordedAt": { "type": "string", "format": "date-time" },
+          "fromKnowledgeMapRevision": { "type": "integer", "minimum": 1 },
+          "fromKnowledgeMapHash": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+          "toKnowledgeMapRevision": { "type": "integer", "minimum": 1 },
+          "toKnowledgeMapHash": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+          "previousPlanHash": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+          "reboundPlanHash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }
+        },
+        "additionalProperties": false
+      }
+    }
   }
 }