codex-workflow-v2 2.0.0-beta.13.8 → 2.0.0-beta.14

package/docs/change-model.md

@@ -1,118 +0,0 @@
-# Execution context and change explanation
-
-A change is explained before it is attempted. The explanation is not an approval, a new grant,
-or a replacement lifecycle. Existing Core `next` remains authoritative.
-
-## One execution context
-
-App dispatch defaults to a worktree. An explicitly requested `executionMode: "local"` creates
-in the saved project instead. Use local only when the user requested that execution environment.
-The dispatch prompt separates repository identity from the child's actual write destination.
-Correlated App readback records the real checkout root. A second readback cannot silently move
-that bound Worker into another checkout, even when both share a Git common directory.
-
-Before the first write and after a branch/cwd change, call the packaged registry action
-`dispatch-context-check --reservation-id ... --file ... --project-id ...` with:
-
-```json
-{
-  "observation": { "thread": {
-    "id": "actual-bound-thread-uuid", "kind": "codex", "hostId": "local",
-    "cwd": "/absolute/actual/worker/checkout"
-  } },
-  "writeRoot": "/absolute/actual/worker/checkout",
-  "expectedBranch": "exact-branch-from-fresh-Task"
-}
-```
-
-Use a fresh App `read_thread` observation, never a fabricated cwd. This read-only check detects
-repository, checkout, write-root and branch mismatch. It does not replace Task revision, actor,
-lease/credential or external permission checks. Do not send another create request, change the
-target directory, or hand off an active writer merely to clear a mismatch. Reconcile the existing
-Worker and Workflow context. Tracked dispatch without recorded executionContext needs a correlated `dispatch-observe` before
-this check can match; it does not invent an existing checkout binding.
-
-## One change card
-
-`change explain --task TASK-ID --file proposal.json --repo /actual/checkout --json` reads the
-current Task and `next` from one observation. It changes no workflow state or product file.
-
-```json
-{
-  "reason": "The current check requires one additional support file.",
-  "paths": ["tools/check-support.ts"],
-  "intent": "implementation",
-  "expectedRevision": 12,
-  "executionContext": {
-    "cwd": "/absolute/actual/worker/checkout",
-    "writeRoot": "/absolute/actual/worker/checkout",
-    "expectedBranch": "exact-task-branch"
-  },
-  "externalDecision": "unknown"
-}
-```
-
-`paths` are exact normalized relative file paths, not globs. `expectedPlanHash` is also accepted.
-Inputs are closed; an agent cannot add a `supportProven` or `approved` flag. `externalDecision:
-"denied"` preserves an external denial as a separate blocker. It does not call or emulate the
-external permission service. `intent` may instead be `membership` or `semantic-scope`; declaring
-intent never proves semantic safety. Omitted context is reported as not supplied, not verified.
-
-The card binds Task revision/Plan, HEAD, request and bytes of proposed plus observed dirty paths.
-Undeclared dirty files are included; escaping symlinks block byte inspection. The output contains
-no confirmation/claim/writer values and no proposed file contents. A proposal hash is a diagnostic
-binding, not an apply token; always refresh `next` and ordinary mutation preconditions.
-
-## Adaptation routes
-
-- Implementation fixes continue within the same Task when the current Core route permits it.
-  Review count alone does not select corrective planning.
-- `bounded-plan-amendment` appears only when Core advertises the exact eligible check-support
-  scope extension and every out-of-Step file is covered by that evidence. Execute the existing
-  `task plan-integrity-recover` route and fresh `next`; its existing atomic evidence and authority
-  rules apply. The card never edits `allowedWrites`, enlarges a grant, or supplies an arbitrary
-  new Plan. This release reuses the proven bounded amendment mechanism rather than adding a
-  competing mutation protocol.
-- An unproved additional file requires Plan review. No broad glob or diff-size rule grants
-  automatic extension. Runtime changes and component-owner recovery retain their current audits.
-- Corrective planning and downstream recovery retain existing Task/Worker identity and historical
-  evidence. A Knowledge context refresh does not resolve a Plan conflict.
-- Membership is distinct from implementation. Existing audited remediation and full-contract
-  membership evolution remain the only corresponding machine routes. A reported membership
-  intent does not authorize deletion of a required Task or weakened acceptance.
-- Semantic scope requires an explicit user decision. External denial remains independent of
-  Workflow grants and file scope.
-
-`requiresUser: null` means the card has not established a specific human gate, not that all
-checks passed. The card is advisory and cannot intercept arbitrary editor/tool writes. Gateway
-agents must invoke the context check and fresh Core route before writing. No claim is made that
-an external approval system will accept the resulting operation.
-
-For a legacy Worker already bound before dispatch markers existed, the read-only context check
-uses its existing thread/host plus a freshly supplied Task repository root. It explicitly reports
-that historical checkout provenance is unavailable, preserves the legacy registry bytes and
-never creates or adopts another Worker. A tracked Worker whose checkout changes still reports a
-mismatch; no automatic App handoff or silent registry migration is performed.
-
-## Later independent corrective evidence after a fix review
-
-A failed guarded Step can reveal a Plan obstruction after its immutable strict review recorded
-`fix` without a Plan conflict. On a clean current Task checkout, after at least two real remediation
-failures and with no decision already bound to the current ordinal, `next` can expose the optional
-`correctiveDecisionOption`. The ordinary fix action remains the default. No failure, repeated run,
-review rewrite or arbitrary scope extension is required to obtain an independent corrective audit.
-The option is absent while a Step runs, a pending handoff exists, or an earlier navigation gate
-blocks ordinary continuation. Existing writer/C1 actor and token requirements still apply; a
-legitimate claimed Worker credential does not disable this independent audit route.
-
-Only a genuine independent audit justifies using the existing `task corrective-decision` command.
-Its resulting append-only decision preserves the original review and completed Steps. A decision
-requiring replan leads to the existing corrective yield/prepare/confirmation route, including its
-separate Human gate; the option supplies no replacement authority, grant or permission to write
-additional files. A conflicting existing decision cannot be overwritten.
-
-The option's revision, Brief/Plan/HEAD and remediation event hashes describe the observation used
-for the audit. They are not a new apply token or additional executor-enforced hash contract: the
-existing executor checks its revision, current decision ordinal, audit independence and actor/token
-preconditions. Refresh `next` and audit evidence before recording, including after a HEAD change
-that does not change the Task revision. Never treat stale option output as authorization.

package/docs/delegated-approval.md

@@ -1,254 +0,0 @@
-# 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.7 does not widen the generic delegation allow-list. Generic delegated approval does not authorize:
-
-- `state adoption-apply`
-- `milestone scope-change-prepare`
-- `milestone scope-change-apply`
-- semantic Milestone scope changes
-
-A separate `milestone autonomy-prepare` / `milestone autonomy-grant` contract issues one
-milestone-scoped grant over the existing Task/Milestone approval transitions, adds
-membership-only evolution authority, and permits Project Memory approval only as the guarded
-half of an atomic content-only Task context refresh in that Milestone. Standalone Project Memory
-approval remains project-scoped. The contract does not add a generic delegation transition:
-outcome, success signal, acceptance, checks, discovery, and base branch remain immutable.
-
-## Full contract during an active Milestone
-
-The human may request `milestone autonomy-prepare` / `milestone autonomy-grant` while a
-Milestone is `active`, as well as before its initial execution. This supports first full
-issuance or replacement after expiry/revocation without resetting the Milestone, altering
-its Plan or completed Task evidence, or recreating its Worker. Planning, blocked, validating,
-final-acceptance and terminal Milestones are not eligible for this route.
-
-Preparation is read-only. It requires a coherent registered repository, a complete current
-Plan and active Knowledge Map. Its MAC binds the status, revision, Plan, semantic scope,
-principal, delegate, exact expiry (at most 72 hours), policy and previous authority state.
-Show this complete contract and obtain a separate exact human confirmation. Never renew a
-contract automatically or treat general delegated execution as permission to issue authority.
-
-A still-valid full contract cannot be replaced. An explicitly revoked or expired contract
-may be replaced using a freshly prepared MAC. The previous confirmed code cannot undo a
-revocation. Exact retries retain the same contract/grant; an interrupted event-first write
-can be completed only with its original matching confirmation. Issuance and milestone grant
-revocation share a Milestone lock. History remains append-only.
-
-`next` exposes optional `activeMilestoneAutonomyOptions` even when a linked Task is selected;
-this does not change the immediate Task action or waive its credential/review/recovery gates.
-A coexisting generic grant remains unchanged and does not gain membership evolution or atomic
-context-refresh authority. The new full contract carries those existing bounded capabilities;
-it never grants standalone Project Knowledge approval or a semantic scope change.
-
-## 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.
-
-Ordinary semantic Milestone scope changes remain journaled, human-only lifecycle actions. A
-contract delegate may evolve only the membership graph inside the cryptographically bound
-semantic scope. The separate beta.12.11 `milestone remediation-materialize` route is not delegation
-and does not widen this allow-list: Core derives it only from a current blocking Plan Risk Audit and
-a previously authorized active Milestone. Its topology effect is fixed to one new required upstream
-Task plus one dependency edge, with all Milestone semantics preserved. The resulting
-`corrective-derived` Task approvals remain valid only while that exact derived Milestone authority
-is current; final Milestone acceptance is unaffected.
-
-### 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 обязательно создай
-новую standalone Codex task через create_thread, а не fork/handoff/продолжение этого чата.
-Передай только TaskContextPacket из свежего Workflow state: repository, exact Milestone/Task ID,
-membership ordinal, Task revision/title, Brief/Plan bindings, requirements/acceptance, Task-local
-scope/checks/stop conditions, маршрут status -> next --task <exact Task ID> и тот же actor/DGR-ID
-только когда они требуются. Не передавай transcript этого чата, sibling Tasks, recovery narrative,
-reasoning, confirmation codes, handoff credentials или writer tokens.
-Title обязателен и выделяется проектным registry:
-#NNN · M<NN>/T<NN> · Task · <Task title> · <TASK-ID>. До dispatch проверь уникальность
-Task-ID-to-thread mapping, выполни exact registry readback и проверь Task-only input. Служебный
-codex_delegation envelope с source_thread_id допустим, parent turns/transcript запрещены. Если
-title отсутствует или изменён, явно переименуй и перепроверь. Ошибка create_thread не разрешает
-fallback на fork_thread.
-Если readback изменён, применяй только deterministic fallback registry; полный `#NNN`, ordinal и
-entity ID сохраняются. В
-TaskContextPacket потребуй закрытый secret-free CoordinatorReport на terminal/attention boundary:
-Task ID, observed revision/status, outcome, next action, requiresUser, blocker class,
-commits/checks/review evidence; никаких confirmation/handoff/writer bearer values.
-После dispatch не завершай coordinator turn. Жди текущий Task-чат через bounded wait_threads,
-сохраняй cursor, а при completed/attention прочитай чат и выполни свежий status -> общий next.
-Если та же Task остаётся nonterminal и точный next допускает non-human continuation, продолжи тот
-же чат через send_message_to_thread. Пользователя привлекай только для mandatory human/semantic
-gate, external permission, unrecoverable integrity conflict или исчерпанного infrastructure retry.
-Следующий Task-чат создавай только после подтверждённого Core terminal+merged результата текущей
-Task. Завершать Milestone-чат при работающей nonterminal Task можно лишь по явной команде
-checkpoint либо при таком блокере; обязательно сохрани Task/thread/host/title/cursor mapping и
-fresh next для возобновления без duplicate dispatch.
-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 возвращает top-level `action: task context-refresh` и exact `contextRefresh` для того же
-grant, выполни только `task context-refresh`; не запускай перед ним standalone reconcile. Exact
-Plan-declared supporting additions допустимы только когда их признал Core. При любом другом
-изменении source set, category/authority, gaps или conflicts используй обычный видимый процесс.
-
-После submit запусти отдельный Independent Reviewer; Reviewer не использует
-grant и не исправляет код. Failed review возвращает ту же Task в remediation: добавь или измени
-remediation Step и снова проведи review. Количество failed reviews не требует отдельного
-corrective Plan audit. Для каждого finding Reviewer использует `route=fix` по умолчанию;
-`route=replan` допустим только с точным Plan clause, доказательством невозможности обычного fix и
-минимальным изменением Plan. Objective, requirements и acceptance через remediation не меняются.
-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.