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

package/docs/updating-existing-project.md

@@ -0,0 +1,243 @@
+# Обновление 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, если он требуется.
+
+## 3.1. При необходимости включите delegated approval
+
+Delegated approval не включается автоматически после обновления. Существующие авторизации и
+terminal-сущности не меняются, а `stateSchemaVersion` остаётся `2`. Пользователь один раз
+подтверждает точную policy; после этого named delegate может выполнять только перечисленные
+переходы до истечения срока или revocation.
+
+Для заместителя, который должен планировать ещё не созданные Milestones и Tasks, нужен
+ограниченный по времени project scope. Более узкий Milestone/Task scope безопаснее, когда ID
+уже известен. Пример policy:
+
+```json
+{
+  "principal": "user:owner",
+  "delegate": "agent:deputy",
+  "scope": { "kind": "project" },
+  "transitions": [
+    "project_memory.approve",
+    "milestone.execution_authorize",
+    "milestone.final_accept",
+    "task.execution_authorize",
+    "task.final_accept"
+  ],
+  "expiresAt": "<ISO-8601 UTC>"
+}
+```
+
+Промпт для выпуска grant:
+
+```text
+Подготовь delegated approval policy для этого проекта: principal user:owner,
+delegate agent:deputy, project scope, переходы project_memory.approve,
+milestone.execution_authorize,
+milestone.final_accept, task.execution_authorize и task.final_accept, срок до
+<ДАТА_И_ВРЕМЯ_UTC>. Создай временный JSON вне репозитория и выполни только
+delegation prepare. Покажи всю policy, projectId, policyHash и DGA-код, затем
+остановись. Grant в этом же ответе не выпускай.
+```
+
+После проверки ответьте отдельным сообщением:
+
+```text
+Одобряю выпуск delegated approval grant для policy hash <POLICY_HASH>
+с кодом <DGA-CODE>. Выпусти grant и покажи DGR-ID, scope, transitions,
+expiresAt и revision.
+```
+
+`delegation list` и `status` показывают grants. Для досрочной остановки автономности агент
+выполняет `delegation revoke` от имени точного principal с текущей revision и причиной.
+Revocation запрещает будущие использования, но не переписывает уже записанные события.
+
+Важно: это локальная проверка policy и audit trail, а не криптографическая аутентификация
+Codex-процесса. Любой процесс с доступом к локальному state и CLI может заявить строку
+delegate. Поэтому project-wide grant должен быть короткоживущим, а секреты, платежи, реальные
+торговые операции и иные необратимые действия требуют отдельных технических ограничений и не
+должны полагаться только на delegated approval.
+
+## 3.2. Запустите delegate в новом чате
+
+Grant сам не запускает агента и не прикрепляется к существующему чату. После получения
+`DGR-ID` откройте новый Local-чат в том же Codex Project. Новый чат нужен ещё и потому, что он
+загрузит актуальную gateway-инструкцию. Передайте точные `delegate` и `DGR-ID`; `DGA-код`
+больше не нужен.
+
+Перед запуском проверьте выбор scope:
+
+- новый Milestone или новая standalone Task с `AUTO` требуют project scope;
+- существующий Milestone и его linked Tasks могут использовать Milestone scope;
+- одна существующая Task может использовать Task scope;
+- Knowledge Map approval доступен только project-scoped grant с
+  `project_memory.approve`.
+
+Полные копируемые промпты для Milestone delegate и Task delegate находятся в
+`docs/delegated-approval.md` и chat-only PDF. В обоих промптах delegate обязан сначала
+выполнить `delegation show`, а каждый approval применять только при exact записи в текущем
+`next.delegatedApprovalOptions`. Внутренние Worker и Independent Reviewer grant не используют:
+его применяет координатор после получения их evidence.
+
+Рекомендуемые названия чатов:
+
+```text
+NN - M2 delegated coordinator
+NN - M2/T1 delegated execution
+NN - Standalone delegated task
+```
+
+После завершения автономного окна попросите отдельный контрольный чат показать
+`delegation list`, использованные authorization events и отозвать ненужный широкий grant.
+
+## 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,36 @@
 # 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.4` 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 47 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,
+- Delegated approval coverage includes DGA-bound grant issuance, project/Milestone/Task
+  scopes, Knowledge Map approval, all Task/Milestone execution and final transitions,
+  `next.delegatedApprovalOptions`, explicit principal/delegate audit metadata, actor,
+  transition and scope rejection, expiry, revocation, duplicate issuance, and policy-hash
+  tamper rejection.
+- 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.4.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.4`.
+- The alpha.4 CLI read the existing Signal schema 2 project state without migration:
+  project ID `b06d0f18f790f4521a23c770`, accepted Milestone 1 revision 10, historical
+  authorization events, and all entity IDs were preserved; `delegations` was an empty
+  additive collection and repository-level `next` remained `idle`.
+- The three Russian PDFs were regenerated and all 40 pages were rendered to PNG for visual
+  inspection; delegated approval, compatibility, grant issuance, audit, revocation, and
+  chat-only grant issuance and Milestone/Task delegate launch prompts are present without
+  layout defects.
 
 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.4",
   "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,36 @@ 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`.
+Autonomous approval requires `delegated-approval-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.
+
+## Delegated Approval
+
+`delegation prepare --file <policy.json>` returns a `delegation_grant_issuance` gate with a
+project-bound policy hash and `DGA-*` confirmation code. Display it and end the turn. A later
+explicit user message containing the exact code permits `delegation grant`.
+
+Active eligible grants appear in `next.delegatedApprovalOptions`. Use only the option whose
+transition matches the requested command, with the named delegate as actor and the grant ID
+as `--delegation-grant`. The resulting authorization event records the grant and both actors.
+For `milestone.final_accept`, also pass the current `MSA-*` code; the existing grant replaces
+the later-message requirement, not the state binding.
 
 ## 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,39 @@ 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 unless
+the same `next` response contains a currently eligible `delegatedApprovalOptions` entry for
+the exact transition and the agent is the entry's named delegate.
+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.
+
+## Delegated Approval
+
+Delegation issuance is itself a mandatory human turn boundary. Run `delegation prepare` with
+the proposed policy, show the complete principal, delegate, scope, transitions, expiry,
+policy hash, and `DGA-*` confirmation code, then stop. Only after a later user message
+explicitly approves that exact code may `delegation grant` be invoked.
+
+Never create, broaden, renew, or replace a grant from an agent's own judgment. Never record
+the delegate as the user. When `next` exposes an eligible option, pass its grant ID through
+`--delegation-grant` and use the exact delegate string as `--actor`. The core remains the
+authority for status, expiry, scope, transition, and revocation checks.
+
+For delegated Milestone final acceptance, the current `MSA-*` code is still required, but a
+new user turn is not: the previously issued grant is the controlling decision. If no eligible
+option is returned, follow the ordinary human-gate rule above. Knowledge Map approval is
+delegable only through an explicit project-scoped `project_memory.approve` permission. Scope
+changes, grant issuance, and grant expansion are never delegated by `delegated-approval-v1`.
+
 ## Stop Conditions
 
 - Dependency version is missing, ranged, or differs from the installed package.
@@ -70,3 +103,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 and no exact eligible delegated approval option exists.

package/references/state-machine.md

@@ -6,6 +6,14 @@ 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.
 
+Human approval remains the default. A user may instead issue a time-bound delegation grant
+after confirming a deterministic `DGA-*` code bound to the project and exact policy hash.
+The policy names a distinct principal and delegate, a project/Milestone/Task scope, and an
+allow-list of approval transitions. Delegated transitions fail closed on actor, scope,
+transition, expiry, revocation, or project mismatch. Their authorization events record
+`authorizationMode: delegated` plus the grant ID, policy hash, principal, delegate, and exact
+transition; the delegate is never recorded as the user.
+
 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
@@ -15,4 +23,18 @@ 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.
+An already issued grant containing `milestone.final_accept` may cross that gate autonomously,
+but the acceptance command still requires the current `MSA-*` code so the use remains bound
+to the validated revision, hashes, and HEAD. Grant issuance itself always remains a prior
+human turn boundary.
+
+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.

package/schemas/authorization-event.schema.json

@@ -0,0 +1,55 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://codex-workflow.local/schemas/authorization-event.schema.json",
+  "title": "Codex Workflow V2 Authorization Event",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "kind", "decision", "actor", "recordedAt", "briefHash", "planHash", "resultHash",
+    "evidenceHash", "headCommit", "reason"
+  ],
+  "properties": {
+    "kind": { "enum": ["execution", "final_acceptance", "exception"] },
+    "decision": { "enum": ["approved", "rejected", "waived", "superseded"] },
+    "actor": { "type": "string", "minLength": 1 },
+    "recordedAt": { "type": "string", "format": "date-time" },
+    "briefHash": { "$ref": "#/$defs/nullableHash" },
+    "planHash": { "$ref": "#/$defs/nullableHash" },
+    "resultHash": { "$ref": "#/$defs/nullableHash" },
+    "evidenceHash": { "$ref": "#/$defs/nullableHash" },
+    "headCommit": { "$ref": "#/$defs/nullableHash" },
+    "reason": { "type": "string" },
+    "authorizationMode": { "enum": ["human", "delegated"] },
+    "delegation": { "$ref": "#/$defs/delegation" }
+  },
+  "allOf": [
+    {
+      "if": {
+        "properties": { "authorizationMode": { "const": "delegated" } },
+        "required": ["authorizationMode"]
+      },
+      "then": { "required": ["delegation"] }
+    }
+  ],
+  "$defs": {
+    "nullableHash": { "type": ["string", "null"], "pattern": "^[a-f0-9]{40,64}$" },
+    "delegation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["grantId", "policyHash", "principal", "delegate", "transition"],
+      "properties": {
+        "grantId": { "type": "string", "pattern": "^DGR-[0-9A-HJKMNP-TV-Z]{26}$" },
+        "policyHash": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+        "principal": { "type": "string", "minLength": 1 },
+        "delegate": { "type": "string", "minLength": 1 },
+        "transition": {
+          "enum": [
+            "project_memory.approve",
+            "task.execution_authorize", "task.final_accept",
+            "milestone.execution_authorize", "milestone.final_accept"
+          ]
+        }
+      }
+    }
+  }
+}

package/schemas/delegation-grant.schema.json

@@ -0,0 +1,69 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://codex-workflow.local/schemas/delegation-grant.schema.json",
+  "title": "Codex Workflow V2 Delegation Grant",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion", "revision", "id", "projectId", "createdAt", "updatedAt", "kind",
+    "status", "principal", "delegate", "scope", "transitions", "expiresAt", "policyHash",
+    "revokedAt", "revokedBy", "revokeReason"
+  ],
+  "properties": {
+    "schemaVersion": { "const": 2 },
+    "revision": { "type": "integer", "minimum": 1 },
+    "id": { "type": "string", "pattern": "^DGR-[0-9A-HJKMNP-TV-Z]{26}$" },
+    "projectId": { "type": "string", "pattern": "^[a-f0-9]{24}$" },
+    "createdAt": { "type": "string", "format": "date-time" },
+    "updatedAt": { "type": "string", "format": "date-time" },
+    "kind": { "const": "delegation-grant" },
+    "status": { "enum": ["active", "revoked"] },
+    "principal": { "type": "string", "minLength": 1 },
+    "delegate": { "type": "string", "minLength": 1 },
+    "scope": {
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["kind"],
+          "properties": { "kind": { "const": "project" } }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["kind", "id"],
+          "properties": {
+            "kind": { "const": "milestone" },
+            "id": { "type": "string", "pattern": "^MS-[0-9A-HJKMNP-TV-Z]{26}$" }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["kind", "id"],
+          "properties": {
+            "kind": { "const": "task" },
+            "id": { "type": "string", "pattern": "^TASK-[0-9A-HJKMNP-TV-Z]{26}$" }
+          }
+        }
+      ]
+    },
+    "transitions": {
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "items": {
+        "enum": [
+          "project_memory.approve",
+          "task.execution_authorize", "task.final_accept",
+          "milestone.execution_authorize", "milestone.final_accept"
+        ]
+      }
+    },
+    "expiresAt": { "type": "string", "format": "date-time" },
+    "policyHash": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+    "revokedAt": { "type": ["string", "null"], "format": "date-time" },
+    "revokedBy": { "type": ["string", "null"] },
+    "revokeReason": { "type": ["string", "null"] }
+  }
+}