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

package/docs/updating-existing-project.md

@@ -92,6 +92,95 @@ handshake, doctor, status и next. Подтверди точную declared/inst
 нужно выполнить `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` остаётся закрытым. Для следующего результата нужно

package/docs/validation-report.md

@@ -1,26 +1,36 @@
 # V2 Alpha Validation Report
 
-Release candidate `2.0.0-alpha.3` was validated on 2026-08-12 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 41 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.
+- 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.3.tgz` with runtime, schemas,
+- 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.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.
+- 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.3",
+  "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

@@ -12,6 +12,7 @@ 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
 
@@ -29,6 +30,18 @@ codex-workflow milestone accept --repo <git-root> --id <MS-ID> \
 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
 
 The package returns:

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

@@ -64,7 +64,9 @@ independently blocks the workflow.
 
 ## Human Gates
 
-Treat `requiredHumanGate` from the project-local package as a mandatory turn boundary.
+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`.
@@ -75,6 +77,24 @@ A generic instruction such as “continue”, “finish”, or “bring it to fi
 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.
@@ -84,4 +104,4 @@ and ask again.
 - 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.
+  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
@@ -21,6 +29,10 @@ valid only after a later explicit user response repeats that code; the CLI requi
 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

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"] }
+  }
+}