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

package/docs/decisions.md

@@ -50,3 +50,33 @@ This document closes the requirement gaps identified during the V2 design review
    evidence, and base HEAD. The gateway must end the turn after showing it, and the CLI accepts
    only an explicit actor and exact code from a later user-confirmed turn. This is state-bound
    consent, not cryptographic proof of human identity.
+10. **Delegated approval.** Human approval stays the default, but a principal may issue a
+    project-bound, expiring grant to a distinct delegate after a separate confirmation-code
+    turn. Grants allow only enumerated Knowledge Map, Task, or Milestone approval transitions
+    and are scoped to the project, one Milestone, or one Task. Each use records
+    both actors and the policy hash; revocation blocks future uses. This is an additive schema
+    2 entity and optional authorization metadata, so existing schema 2 projects require no
+    migration. It is local policy evidence, not a cryptographic identity signature.
+11. **Core-owned Step commit.** `task run` dispatches a Worker that leaves changes
+    uncommitted. For an active Step, `next` returns the exact `task step-complete` transition
+    and Step ID. That transition validates history and allowed paths, runs checks, creates
+    the atomic commit, and records evidence. A manual Worker commit is unrecorded history and
+    fails closed without changing persisted Task state. This changes navigation and
+    diagnostics only; state schema 2 and protocol 1 remain unchanged.
+12. **Autonomous correction guardrail.** The initial Plan must make migration,
+    concurrency, restart/replay, crash-window, and provider risks visible. After two failed
+    independent reviews, another corrective Plan requires a distinct Auditor covering every
+    latest finding. The audit is append-only artifact evidence; no Task state field or schema
+    change is required.
+13. **Content-only context refresh.** A delegate may compose reconcile, approval, knowledge
+    rebind, and execution reauthorization only when the approved source classification is
+    identical and only content hashes changed. Core validates both delegated transitions
+    before writing. Source-set, category, scope, authority, gap, or conflict changes stay on
+    the ordinary visible approval path. State schema 2 and protocol 1 remain unchanged.
+14. **Autonomous chat and closure boundary.** A Milestone coordinator owns orchestration and
+    final acceptance while each required Task uses a dedicated user-visible Task chat.
+    `next` exposes the Milestone completion contract, and delegated acceptance retains the
+    delegate actor and exact state-bound MSA code.
+15. **Safe update preflight.** Dependency updates begin with a read-only preflight requiring
+    a clean checkout, no running Step, and no active writer lease. It does not install,
+    migrate, or mutate project state.

package/docs/delegated-approval.md

@@ -0,0 +1,189 @@
+# Delegated Approval
+
+Delegated approval is an optional local authority grant. It lets a named agent actor cross
+selected Project Knowledge Map, Task, and Milestone approval transitions without pretending
+to be the user. Human approval remains the default.
+
+## Policy and issuance
+
+A policy contains:
+
+- `principal`: the user audit identity;
+- `delegate`: a distinct agent audit identity;
+- `scope`: the current project, one Milestone, or one Task;
+- `transitions`: an allow-list of Knowledge Map, Task, and Milestone approvals;
+- `expiresAt`: a required future UTC timestamp.
+
+`delegation prepare` normalizes the policy, hashes it with the local project ID, and returns
+a deterministic `DGA-*` confirmation code. The gateway displays the complete binding and
+ends the turn. `delegation grant` is permitted only after a later user message confirms the
+same code. Duplicate issuance of the same exact policy is rejected.
+
+## Storage and compatibility
+
+Each grant is an independently revisioned schema 2 entity at:
+
+```text
+$CODEX_HOME/workflow-state/v2/projects/<project-id>/delegations/<DGR-ID>/state.json
+```
+
+Existing schema 2 project, Task, Milestone, Knowledge Map, graph, and authorization records
+are not rewritten. The new directory and authorization metadata are additive, so an existing
+project needs no state migration. After the first delegated transition, downgrading is not
+recommended because an older package cannot enforce or fully explain the new audit metadata.
+
+## Use and audit
+
+The core checks current status, expiry, actor equality, allowed transition, and scope before
+writing the lifecycle change. A Milestone-scoped grant also covers linked Tasks in that
+Milestone. Every delegated authorization event contains:
+
+```text
+authorizationMode = delegated
+actor = <delegate>
+delegation.grantId
+delegation.policyHash
+delegation.principal
+delegation.delegate
+delegation.transition
+```
+
+`next` exposes active matching grants as `delegatedApprovalOptions`. Milestone final
+acceptance still requires the current `MSA-*` code, preserving the revision/hash/HEAD binding;
+the pre-issued grant replaces only the later human-message requirement.
+
+Alpha.6 does not widen this allow-list. Delegated approval does not authorize:
+
+- `state adoption-apply`
+- `milestone scope-change-prepare`
+- `milestone scope-change-apply`
+- any replacement human gate for Milestone membership repair or scope decisions
+
+## Starting a delegate chat
+
+A grant does not start an agent and is not attached to a Codex chat automatically. Open a new
+Local chat in the same Codex Project and give it both the exact `delegate` value and `DGR-ID`.
+The chat must resolve the project-local package, run handshake/doctor/status/next, and read the
+grant before doing work. The earlier `DGA-*` code is not needed again; it authorized issuance,
+not use.
+
+Before the first mutation, the delegate verifies:
+
+- project identity matches the grant's project;
+- `status` is `active` and `expiresAt` is still in the future;
+- the exact chat actor equals `delegate`;
+- scope covers the requested Milestone or Task;
+- the needed transition is present;
+- `next.delegatedApprovalOptions` contains this grant at the approval point.
+
+The delegate must not create, renew, broaden, or replace its own grant. Product ambiguity and
+scope changes are not approval transitions: the delegate stops and asks the user. Worker and
+Independent Reviewer roles may implement or review work, but the coordinating delegate alone
+uses the grant and passes `--delegation-grant` to the Core transition.
+
+This matters more in alpha.6 because Milestone scope changes are explicitly journaled,
+human-only lifecycle actions. A delegate may continue ordinary Milestone execution only inside
+the already approved scope.
+
+### Milestone delegate prompt
+
+Use project scope when the Milestone does not exist yet. An existing Milestone and its linked
+Tasks may use Milestone scope.
+
+```text
+Работай как delegate-координатор Workflow V2 для одного Milestone.
+Delegate actor: agent:deputy
+Delegation grant: <DGR-ID>
+Milestone ID: <AUTO или MS-ID>
+Требования пользователя: <вставить требования без пересказа lifecycle>
+
+Все CLI-, Git-, test-команды и координацию Codex-чатов выполняешь ты.
+Начни с AGENTS.md, project-local gateway handshake, doctor, status и next.
+Выполни delegation show для указанного DGR-ID и до мутаций проверь:
+project, status active, delegate, scope, transitions и expiresAt. Не создавай,
+не продлевай и не расширяй grant.
+
+Для AUTO проведи Discovery и не materialize Milestone при blocking unknowns.
+Не принимай новые продуктовые решения и не расширяй scope: при смысловой
+неопределённости остановись и спроси меня. Подготовь Milestone и связанные
+тонкие Tasks. На approval-переходе используй grant только если текущий next
+вернул exact delegatedApprovalOptions для этого DGR-ID и transition; actor
+всегда agent:deputy, никогда user.
+
+Required Tasks выполняй последовательно. Для каждой Task обязательно создай
+отдельный пользовательский Codex-чат, передав ему Task delegate prompt, тот же actor и DGR-ID.
+Milestone-чат не реализует Steps и не накапливает fix-loop всех Tasks;
+не запускай два writer на одном checkout. Worker и Reviewer не используют
+grant: approval-команды выполняет только delegate-координатор после их evidence.
+
+После merge всех required Tasks выполни Milestone validation. Если next вернул
+milestone.final_accept для этого grant, проверь Result/evidence/HEAD и примени
+grant с текущим MSA-code в том же turn. Если exact option нет, остановись перед
+human gate. В конце покажи Milestone status, authorization event, использованный
+grant/transition и результаты проверок.
+```
+
+### Task delegate prompt
+
+Use Task scope for one existing Task. A new standalone Task with `AUTO` requires project
+scope; a Milestone-scoped grant covers Tasks linked to that Milestone.
+
+```text
+Выполни или возобнови одну Task через Workflow V2 как delegate.
+Delegate actor: agent:deputy
+Delegation grant: <DGR-ID>
+Milestone ID: <MS-ID или NONE>
+Task ID: <TASK-ID или AUTO>
+Цель standalone Task: <только если AUTO>
+
+Все CLI-, Git- и test-команды выполняешь ты. Начни с AGENTS.md,
+project-local gateway handshake, doctor, status и next. Выполни delegation
+show для DGR-ID и до мутаций проверь project, active status, delegate,
+scope, transitions и expiresAt. Не создавай и не меняй grant.
+
+Не меняй пользовательские требования и scope. Для AUTO сначала проведи
+Discovery; при blocking unknowns остановись. Подготовь проверяемый Plan.
+Authorization выполняй только когда текущий next содержит exact
+delegatedApprovalOptions для DGR-ID и task.execution_authorize; используй
+actor agent:deputy и --delegation-grant, не записывай actor user.
+
+Далее следуй штатному lifecycle: один Step - один writer lease. Worker меняет
+только разрешённые файлы и оставляет их uncommitted; затем координатор вызывает
+exact `task step-complete` из `next`, а core выполняет checks, создаёт commit и
+записывает evidence. Worker не использует grant. При изменении Knowledge Map
+выполни reconcile; approve разрешён только при exact project_memory.approve
+option этого project-scoped grant. Затем knowledge-rebind и новая authorization.
+Если next содержит exact `contextRefresh` для того же grant, можешь вместо четырёх
+команд выполнить `task context-refresh`; при любом изменении source set,
+category/authority, gaps или conflicts используй обычный видимый процесс.
+
+После submit запусти отдельный Independent Reviewer; Reviewer не использует
+grant и не исправляет код. После второго failed review не запускай очередной
+патч: получи отдельный corrective Plan audit, охватывающий все последние findings,
+и передай его через `--corrective-audit-file`. Продолжай только при
+`decision=continue-fix`; остальные решения верни пользователю/координатору.
+Final acceptance делай
+только при exact task.final_accept option для DGR-ID, затем штатный merge.
+Если option отсутствует, grant истёк, scope не совпал или требуется смысловое
+решение пользователя - остановись. В конце покажи Task status, commits, checks,
+review и delegated authorization event.
+```
+
+Milestone coordinator waits for the dedicated Task chat to return its terminal Task status
+and merge evidence before starting the next required Task. Internal subagents inside one
+oversized Milestone chat are not a substitute for this user-visible Task boundary.
+
+After autonomous work, inspect the recorded events and revoke a broad grant when it is no
+longer needed. Revocation does not erase completed approvals.
+
+## Revocation and limits
+
+`delegation revoke` requires the exact principal actor, current grant revision, and a reason.
+It blocks future uses and preserves past events. Expiry is checked at every use and does not
+need a state mutation.
+
+This mechanism is policy evidence, not cryptographic process identity. The local CLI cannot
+prove that a particular Codex process owns the delegate label. Keep project-wide grants
+short-lived and use narrower scopes once entity IDs exist. External side effects such as
+payments, secrets, production deployment, or live trading need their own provider-level
+authorization and must not rely on this grant alone.

package/docs/development-flow.md

@@ -21,10 +21,25 @@ Materialization requires an observable outcome, scope, acceptance criteria, and
 blocking unknowns. No Task identifier or branch exists before this gate. Task authorization
 is hash-bound to Brief and Plan. Later Plan changes supersede it.
 
+In alpha.6, execution authorization also requires a current Plan Risk Audit bound to the same
+Brief, Plan, Knowledge Map, and exact Step set. For existing schema 2 projects upgraded into
+alpha.6, execution additionally requires adoption posture first; remaining legacy scope then
+uses a bootstrap audit over the preserved non-`completed`, non-`skipped` Steps only.
+The audit names a Plan author and independent auditor, binds each guarded failure mode to
+exact executable evidence, and blocks authorization on `split-required` or `stop-escalate`.
+
 Local execution creates `codex/task-<id>-<slug>` from a clean base only after authorization.
 An externally owned checkout must already use a dedicated non-base branch. The core never
 creates or removes external worktrees. Each Step declares allowed writes, dependencies, and
-checks; unexpected paths or failed checks block its atomic commit.
+checks. `task run` dispatches exactly one Step and returns a writer lease. The Worker changes
+only allowed files and leaves them uncommitted. Repository-level `next` then returns the exact
+`task step-complete` transition for the active Step. That core transition runs checks, stages
+the allowed changes, creates the atomic Step commit, and records evidence. Unexpected paths,
+failed checks, or any manual/unrecorded Worker commit block completion.
+
+If the current Plan Risk Audit marks the Step for strict review, the atomic commit is still
+created by core, but the Step remains non-terminal and `next` routes to `task step-review`
+until commit-bound strict review and reviewer attestation pass.
 
 After a Step changes approved project knowledge, the Delivery Coordinator reconciles and
 reapproves the Project Knowledge Map, then runs `task knowledge-rebind` between Steps. The
@@ -35,12 +50,33 @@ active Worker Step, a no-op binding, an invalid knowledge target, or a modified
 artifact. After the user authorizes the rebound Plan, execution resumes in the existing
 workspace; if all Steps are complete, the next action is submission.
 
+When `next.contextRefresh` exposes an eligible project-scoped grant and content-only mode,
+`task context-refresh` may compose reconcile, delegated map approval, rebind, and delegated
+execution reauthorization. Core validates both approval transitions before writing and
+rejects any source-set, category, scope, authority, gap, or conflict change.
+
 Submission requires a clean, auditable Task history and records evidence for the exact
 Task head. `task review-launch` starts a separate read-only reviewer. A passing fresh review
 permits Result creation. Human final acceptance binds Brief, Plan, Result, evidence, and
 the accepted head. Base advancement forces synchronization, checks, review, and acceptance
 to be repeated before merge.
 
+The Technical Planner performs a risk review before authorization. Migration work includes a
+populated forward-upgrade check; concurrent state includes deterministic races; restart,
+replay, and crash claims include restart/crash-window evidence; provider work includes
+failure injection and hidden-default verification. After two failed independent reviews,
+another Plan requires a distinct corrective Auditor and `--corrective-audit-file`. Only a
+`continue-fix` audit may continue; replan, split, and stop decisions return to coordination.
+For guarded alpha.6 remediation, a third ordinary retry is blocked until a current
+`task corrective-decision` exists for the same Step and Plan binding. If that corrective
+attempt fails review, the third failure is a hard stop and no fourth run is permitted.
+
+Execution authorization and final acceptance use the human path by default. If the user has
+previously issued an active delegation grant for the exact transition and scope, the named
+delegate may perform that transition with `--delegation-grant`. The event keeps the delegate
+as actor and separately records the principal and policy hash. Expired, revoked, wrong-scope,
+wrong-transition, and wrong-actor grants are rejected before the lifecycle state changes.
+
 ## Milestone lifecycle
 
 ```text
@@ -57,6 +93,11 @@ and prevents new linked Tasks from starting. A Task that has started cannot be r
 it can be retained as waived/cancelled with history and reason. Tasks already in progress
 may finish while an amendment awaits authorization.
 
+After the initial empty planning posture, alpha.6 does not use ordinary `milestone plan-set`
+for scope changes. It uses human-only `milestone scope-change-prepare` and
+`milestone scope-change-apply`, with journaled recovery across `state.json`, `plan.json`, and
+`scope-change-events.jsonl`.
+
 A Milestone has no integration branch. Validation requires all required Tasks to be
 `merged`, checks the current clean base branch, and writes evidence plus Result. Final
 acceptance binds those artifacts to the unchanged base HEAD. Cancellation records a reason
@@ -76,11 +117,21 @@ explicit user response containing that code permits `milestone accept --actor ..
 that the recorded confirmation matches the displayed state; identity still depends on the
 trusted Codex/user interaction boundary rather than on the local npm package alone.
 
+With an eligible `milestone.final_accept` grant, `next` additionally returns
+`delegatedApprovalOptions`. The delegate may then use the current `MSA-*` code in the same
+turn because the earlier grant-issuance turn is the controlling user decision. Without such
+an option, the ordinary later-message human gate remains mandatory.
+
+The Milestone coordinator keeps implementation out of its long-lived context: every required
+Task runs in a dedicated user-visible Task chat. The Milestone chat owns ordering, exact
+delegated transitions, merge observation, cross-Task validation, and final acceptance.
+
 ## Responsibility boundaries
 
 | Participant | Responsible for | Cannot decide |
 | --- | --- | --- |
-| User | map classifications, execution authorization, final acceptance, scope changes | implementation evidence |
+| User / principal | map classifications, direct approvals, delegation policy and revocation, scope changes | implementation evidence |
+| Delegate | only transitions explicitly allowed by an active grant | grant creation, expansion, impersonating the principal |
 | Scope Lead | discovery, facts, unknowns, Task/Milestone recommendation | production edits |
 | Technical Planner | requirements mapping, Steps, checks, knowledge impact | authorization |
 | Delivery Coordinator | valid transitions, dispatch, evidence collection | scope expansion |