codex-workflow-v2 2.0.0-beta.1 → 2.0.0-beta.11

package/docs/pdf/sources/codex-workflow-v2-technical-reference-ru.md

@@ -0,0 +1,413 @@
+---
+title: Codex Workflow V2: технический справочник beta.11
+subtitle: Protocol 2, state schema 2, transactions, credentials, dependency authority, review и recovery
+part: Часть 3 из 3 | Technical reference
+document_version: 2.0
+date: 24 августа 2026
+subject: Технический контракт Codex Workflow V2 beta.11
+---
+
+# 1. Runtime contract
+
+Workflow V2 предоставляет локальные revisioned transitions. Публичный CLI возвращает JSON с `ok=true`
+и `value` либо структурированную ошибку с `code`, `message` и `details`. Chat, PDF и gateway не создают
+authority сами: mutating permission определяется runtime state и свежим `next`.
+
+| Параметр beta.11 | Значение |
+|---|---|
+| npm package | `codex-workflow-v2@2.0.0-beta.11` |
+| protocolVersion | 2 |
+| stateSchemaVersion | 2 |
+| lifecycle epoch | 2 |
+| transition definition format | 4 |
+| execution topology | Один пользователь, одна машина, local/external workspace contract |
+
+Schema 2 не означает, что все optional legacy fields дают execution authority. Например отсутствие
+Milestone dependency arrays разрешено decoder только для чтения historical state и блокирует новое
+execution до explicit Plan amendment.
+
+# 2. Package resolution и handshake
+
+Gateway выполняет:
+
+1. `git rev-parse --show-toplevel`;
+2. чтение exact `codex-workflow-v2` version из `devDependencies`;
+3. resolution `node_modules/codex-workflow-v2/package.json`;
+4. equality check declared/installed versions;
+5. вызов только package-local `dist/src/cli.js --repo <root>`;
+6. `gateway handshake` до lifecycle действий.
+
+Ключевые beta.11 capabilities:
+
+| Группа | Capabilities |
+|---|---|
+| Knowledge и graph | `project-memory-v1`, `graph-binding-v1`, `task-context-refresh-v1` |
+| Milestone | lifecycle, initial assembly navigation, autonomy, progress, dependency DAG, initial Plan transaction |
+| Task planning | Plan Risk Audit, proof obligations, mechanical feasibility |
+| C1 | handoff sidecar, handoff bundle, derived Worker actor, credential replacement |
+| Reviews | strict reviewer, Step strict review, corrective audit and hard stop |
+| Recovery | dependency provenance, plan integrity, remediation mode, corrective yield/replan journals |
+| Replacement | `structural-task-replacement-disabled-v1` |
+
+Handshake incompatibility прекращает работу. Запуск global package, `latest`, mutable range или соседней
+source checkout запрещён.
+
+# 3. State, artifacts и sidecars
+
+Project identity выводится из Git common directory. Сущности содержат `schemaVersion`, `revision`, ID,
+projectId и timestamps. Mutations используют compare-and-swap по `expectedRevision`.
+
+```text
+$CODEX_HOME/workflow-state/v2/projects/<project-id>/
+  project.json
+  knowledge-map.json
+  discoveries/<DISC-ID>/state.json
+  tasks/<TASK-ID>/
+    brief.md, plan.md, result.md, evidence.json, state.json
+    .versions/
+    authorization/review/remediation/corrective/handoff sidecars
+  milestones/<MS-ID>/
+    plan.json, result.md, evidence.json, state.json
+    .versions/ и scope/autonomy sidecars
+  delegations/<DGR-ID>/state.json
+  locks/<TASK-ID>.json
+  graph-bindings/
+  composite transaction journals
+```
+
+Artifacts публикуются через staged version, CAS state write, active publication и hash readback.
+Composite mutations добавляют journal с exact targets, before/after hashes и recovery posture.
+
+Local state никогда не копируется в product repository и не редактируется вручную.
+
+# 4. Project Knowledge Map
+
+Map хранит metadata долговременных repository files: normalized path, category, scope, authority,
+contentHash, gaps, conflicts и approval. Содержимое документов остаётся в Git.
+
+| Transition | Mutation |
+|---|---|
+| `project-memory scan` | Нет, read-only filesystem classification |
+| `show/status` | Нет, current projection |
+| `reconcile` | Новая map revision из current files |
+| `approve` | mapHash и human/delegated approval evidence |
+| `task knowledge-rebind` | Только Plan map binding, supersede authorization |
+| `task context-refresh` | Atomic reconcile/approve/rebind/reauthorize при exact eligibility |
+
+Top-level `next.action=task context-refresh` является exact composite route. Standalone reconcile перед
+ним запрещён. Milestone Autonomy Contract может покрывать content-only drift и exact Plan-bounded
+supporting-source addition, но не standalone Project Memory approval.
+
+PDF-файлы в `docs/pdf` являются human-facing binary artifacts. Reviewable Markdown sources находятся в
+`docs/pdf/sources`; runtime Project Knowledge authority остаётся в обычных project files и scanner rules.
+
+# 5. Discovery и materialization
+
+Discovery фиксирует kind, goal/outcome, success signal, scope, out-of-scope, acceptance, constraints,
+unknowns и readiness. Blocking unknown запрещает materialization.
+
+Milestone materialization создаёт initial planning posture. Пока Plan отсутствует, `next` возвращает
+`milestone initial-assembly` и exact linked Task assembly commands. Coordinator materializes intended
+linked Tasks, затем публикует один complete Plan. Reverse membership integrity запрещает закрыть Plan с
+unclassified live linked Task.
+
+# 6. Milestone Plan и dependency DAG
+
+```text
+MilestonePlanInput
+  outcome
+  successSignal
+  acceptance[]
+  checks[]
+  memberships[]
+    taskId
+    disposition
+    reason
+    dependsOnTaskIds[]
+```
+
+Normalization trim-ит строки и сортирует каждый dependency array по exact Task ID. Duplicate edges
+отклоняются до normalization и hashing. Graph validation запрещает:
+
+- missing dependency array на новом Plan;
+- dangling, external и missing Task targets;
+- duplicate membership и duplicate edge;
+- self edge и cycle;
+- required consumer с waived/cancelled provider;
+- dependency inference из ordinal, title, filename или chat order.
+
+Initial `milestone plan-set` атомарно связывает state.json и plan.json. Scope change использует
+journaled transaction для membership state, plan artifact, revision/hash и authorization supersession.
+
+## 6.1. Runnable predicate
+
+```text
+runnable =
+  milestone.status == active
+  AND membership.disposition == required
+  AND every dependsOnTaskId is a required member with Task status merged
+```
+
+Predicate вызывается из repository `next`, scoped `next --task`, progress projection, handoff preparation,
+claim до lock acquisition и Task start. Scheduler выбирает из полного runnable set и не изменяет graph.
+
+Legacy nonterminal Milestone без arrays имеет `dependencyState=legacy-unknown` и не может handoff, claim
+или start unstarted required Tasks до explicit Plan amendment.
+
+# 7. Milestone autonomy и delegated approval
+
+Generic delegation allow-list закрыт:
+
+```text
+project_memory.approve
+task.execution_authorize
+task.final_accept
+milestone.execution_authorize
+milestone.final_accept
+```
+
+Issuance: `delegation prepare` возвращает exact policyHash и DGA-code; только отдельный later human turn
+разрешает `delegation grant`. Event сохраняет principal и delegate раздельно.
+
+Milestone autonomy используется после complete initial Plan:
+
+```text
+milestone autonomy-prepare
+-> human confirms exact MAC-code in later turn
+-> milestone autonomy-grant
+-> bounded approvals/context refresh/membership-only evolve
+```
+
+Contract связывает principal, delegate, Milestone, expiry, semantic scope hash и policy hash. Outcome,
+success signal, acceptance, checks, Discovery и base branch неизменны. `autonomy-evolve` допускает только
+membership changes и supersedes execution authorization.
+
+Grant никогда не является C1 writer credential и не наследуется handoff, claim, run, step-complete,
+reviews, sync-base или merge.
+
+# 8. Task Plan authority и P01-A
+
+Task Plan обязан копировать exact requirement/acceptance identifiers из `next.taskPlanContract`. Step
+содержит objective, requirements, dependencies, expectedOutputs, allowedWrites, forbiddenScope и checks.
+Plan binding включает Brief/Plan hashes и approved Knowledge Map revision/hash.
+
+Plan Risk Audit до execution фиксирует guarded Step categories и proof obligations. Fresh execution
+authorization запускает три versioned analyzers:
+
+| Analyzer | Поддерживаемая точная проверка |
+|---|---|
+| `wf2.root-npm-script@1` | Exact `npm run <script>` в root package.json либо responsible manifest writer |
+| `wf2.exact-output-path@1` | Exact `path:<repository-relative POSIX path>` существует или writable |
+| `wf2.exact-predecessor-path@1` | Exact transitive predecessor declares и may write consumer path |
+
+Findings имеют `pass`, `blocked` или `unverified`. Любой blocked finding запрещает authorization без
+event write. Clear evidence записывается внутрь AuthorizationEvent вместе с analyzer set/input hashes,
+Brief/Plan hashes, evaluated HEAD, source branch/kind и evidence hash.
+
+Freshness повторно проверяется перед claim/start/run и recovery. Pre-start evidence связывается с exact
+base branch HEAD; corrective evidence связывается с current Task workspace и baseCommit. Git ancestry,
+branch, analyzer inputs и evidence hash должны оставаться current.
+
+Legacy approved AuthorizationEvent без mechanical payload остаётся readable для compatibility, но не
+создаёт новую P01 evidence claim.
+
+# 9. C1 handoff и writer lease
+
+## 9.1. Dependency binding
+
+Milestone-linked handoff event включает:
+
+```text
+dependencyBinding
+  milestoneRevision
+  membershipRevision
+  milestonePlanHash
+```
+
+Standalone Task использует null. Handoff preparation проверяет runnable predicate и current authorization.
+Claim сверяет stored binding с current Milestone authority до lock acquisition. Dependency-blocked claim
+не получает и не сохраняет lease.
+
+## 9.2. Credential sequence
+
+1. `task handoff-prepare` возвращает first-field `credentialHandoff` и safe bundle.
+2. Plaintext claim token существует только в response и working memory; state хранит hash.
+3. Exact target actor вызывает `task claim` с one-time token.
+4. Claim выдаёт first-field `writerLeaseReceipt`.
+5. `task run` принимает token по `next.writerTokenContract`, heartbeats lease и возвращает refreshed receipt.
+6. Terminal handback/release уничтожает active bearer material.
+
+Credential нельзя логировать, сохранять в chat packet или включать в evidence. `handoff-show` возвращает
+только safe persisted binding. Recovery использует отдельные advertised replacement actions.
+
+# 10. Git и Step evidence
+
+| Boundary | Проверки Core |
+|---|---|
+| Task start | Clean checkout, fresh base/auth/dependency binding, correct workspace policy |
+| Step run | Planned/failed eligible Step, dependencies, branch, C1 actor, lease |
+| Worker return | Изменения uncommitted и только в allowedWrites |
+| Step complete | History, scope, checks, review gate, exact writer token |
+| Commit | Один Core-owned commit с Task/Step metadata |
+| Submit | Clean tree, Steps completed/skipped, recorded commits and evidence |
+| Merge | Fresh review/acceptance, base conditions, accepted HEAD |
+
+Local start повторно сравнивает authorized base внутри Git branch creation, закрывая TOCTOU между
+freshness check и mutation. External workspace обязан быть non-base branch от exact recorded commit.
+
+# 11. Task state и review
+
+Основной путь:
+
+```text
+planning -> awaiting_execution_authorization -> ready
+-> C1 claimed -> in_progress -> validating
+-> awaiting_final_acceptance -> merging -> merged
+```
+
+Return states включают `needs_fix` и `blocked`. `cancelled` terminal. Rebind/replan supersedes old
+authorization; sync-base invalidates review/Result/acceptance bindings.
+
+В Codex App recommended strict mode external-sealed:
+
+- `task step-review-packet` -> separate Step Reviewer -> `task step-review-record`;
+- `task review-packet` -> separate Final Reviewer -> `task review-sealed-record`;
+- packetHash и repositorySealHash обязаны совпасть до записи;
+- Reviewer thread ID и lifecycle actor фиксируются, bearer token не передаётся Reviewer;
+- seal drift уничтожает result и требует fresh packet.
+
+`review-launch` сохраняется в public CLI для совместимых environments, но не применяется как nested
+local reviewer внутри Codex App sandbox.
+
+# 12. Remediation и corrective decisions
+
+Guarded Step имеет bounded remediation circuit:
+
+| Boundary | Разрешение |
+|---|---|
+| Первый failed review/check cycle | Ordinary scoped retry |
+| Два failed review cycles | Independent Corrective Auditor |
+| `continue-fix` | Один corrective attempt |
+| Corrective attempt failed | Hard stop, fourth run запрещён |
+| `replan-required` | Corrective yield и Human-confirmed journaled replan |
+| `split-required` | Structural replacement stop |
+| `stop-escalate` | Terminal user attention |
+
+Corrective replan разделён на prepare, Human confirmation, execute и recover. Candidate/receipt связывают
+Task revision, Plan/Brief/evidence, corrective decision, writer posture и repository state. Execution
+transaction supersedes old authority и публикует replacement Plan атомарно.
+
+# 13. beta.11 Plan-integrity recovery
+
+`task plan-integrity-recover` применим только после одного first ordinary `checks-failed` remediation:
+
+- check соответствует bounded root npm-script grammar;
+- script отсутствует;
+- package.json вне current Step allowedWrites;
+- dirty files полностью внутри Step scope;
+- current Task/Plan/remediation/Step/manifest/HEAD bindings точны.
+
+Recovery записывает schema-valid `replan-required` decision с synthetic ordinal 2 и canonical conflict
+hash. Он не запускает checks повторно, не меняет worktree, Plan или allowedWrites. Затем C1 owner следует
+fresh `next` через corrective yield и обычный Human-confirmed replan.
+
+P01-A предотвращает поддерживаемые contradictions до fresh authorization. beta.11 path остаётся для
+pre-P01 authorizations и late/unsupported exact recovery cases.
+
+# 14. P04-A structural replacement boundary
+
+Command shape `task replacement-materialize` retained только для compatibility diagnostics. Любая попытка
+возвращает `TRANSITION_BLOCKED`, diagnostic `STRUCTURAL_REPLACEMENT_REQUIRED` и incident dependency edges
+до Task/Discovery/Milestone/Knowledge/lock writes.
+
+`next` при terminal split возвращает:
+
+```text
+action: doctor
+blockedAction: task replacement-materialize
+replacementGate.structuralReplacementAvailable: false
+replacementGate.transaction: disabled
+```
+
+Нельзя rebind, refresh, replan, authorize, resume, cancel historical Task, consume replacement Discovery
+или manually rewire graph. P04-B/P05 должен определить arbitrary cardinality, scope redistribution,
+dependency rewiring, completed-work adoption и crash-safe transaction.
+
+# 15. Milestone progress и Codex task supervision
+
+`milestone progress` является read-only projection: ordinals, membership disposition/reason, dependency
+state, predecessors/statuses, runnable/block reason, replacement links и Step statuses.
+
+Coordinator создаёт отдельный standalone Codex task just-in-time. TaskContextPacket не содержит parent
+transcript или secrets. Project registry выдаёт monotonic #NNN и exact title; readback/fallback обязательны.
+
+Coordinator ждёт one routed Task, читает closed CoordinatorReport, затем выполняет repository
+`status -> next` и новый progress projection. Recoverable non-human continuation возвращается в тот же
+Task chat. Следующий Task dispatch разрешён только после terminal merged confirmation.
+
+# 16. codebase-memory graph
+
+`codebase-memory-mcp` используется только после `graph refresh-request`. Gateway сверяет project/root,
+index status и request fingerprint, получает derived evidence и вызывает `graph bind` с current revision.
+
+Graph является навигационным индексом, не Project Knowledge authority. При provider unavailable Core
+записывает explicit `graph fallback`; агент продолжает Git search, прямое чтение файлов и tests, если
+другой independent gate не блокирует работу.
+
+# 17. Error codes и recovery discipline
+
+| Code | Значение | Реакция |
+|---|---|---|
+| `INVALID_ARGUMENT` | Closed input contract нарушен | Исправить exact syntax/field, не менять semantics |
+| `NOT_FOUND` | Entity/artifact/lock отсутствует | Проверить project и ID через fresh observations |
+| `STATE_CONFLICT` | expected revision устарела | Новый status/show/next, без blind retry |
+| `STATE_CORRUPT` | Schema/hash/chain несовместимы | Stop и owning recovery/diagnostics |
+| `LOCKED` | Active writer lease существует | Не создавать второго writer |
+| `LOCK_TOKEN_INVALID` | Bearer не владеет lease | Credential recovery для exact owner |
+| `TRANSITION_BLOCKED` | Lifecycle/authority gate не выполнен | Следовать action/details из fresh next |
+| `GIT_PRECONDITION_FAILED` | Branch/base/clean/history mismatch | Штатная Git recovery/sync route |
+| `COMMAND_FAILED` | Git/check/provider process failed | Сохранить evidence и устранить concrete cause |
+
+После каждой successful mutation обязателен sequential `status`, затем fresh `next`. Failed status/next
+не разрешает direct mutation. Syntax help read-only и не заменяет navigation authority.
+
+# 18. Public command surface beta.11
+
+| Область | Actions |
+|---|---|
+| System | `doctor`, `status`, `next`, `gateway handshake`, `locks` |
+| Update | `preflight`, `rescue-preflight`, `dependency-provenance-preflight/recover` |
+| Project memory | `scan`, `show`, `status`, `approve`, `reconcile` |
+| Delegation | `prepare`, `grant`, `list`, `show`, `revoke` |
+| Graph | `prepare`, `status`, `refresh-request`, `bind`, `fallback` |
+| Discovery | `start`, `update`, `show`, `materialize` |
+| Milestone | `recover`, `show`, `progress`, `plan-set`, scope-change, autonomy, `authorize`, `validate`, `accept`, `cancel` |
+| Task planning | `show`, `plan-set`, `knowledge-rebind`, `context-refresh`, `authorize`, `plan-risk-audit` |
+| Task execution | `start`, `run`, `step-complete`, `submit`, `result-set`, `accept`, `sync-base`, `merge`, `merge-confirm` |
+| C1 | `handoff[-prepare/-replace/-show]`, `claim`, `writer-credential-replace`, `handback[-create]` |
+| Review | review/step-review packet, launch, sealed record и record actions |
+| Corrective | decision/recovery, plan-integrity, remediation-mode, yield и corrective-replan actions |
+| Replacement | `replacement-materialize` retained, но всегда disabled в P04-A |
+
+Exact options берутся из fresh `next`; command help используется только когда
+`exactOptionContractAvailable=false` или syntax действительно неизвестен.
+
+# 19. Release и package update gates
+
+Перед package update project-local `update preflight` должен вернуть `safe=true`: clean checkout, нет
+running Step и active/stale writer lease. External runner допустим только в документированной rescue
+compatibility форме.
+
+Перед beta.11 tag release repository выполняет:
+
+1. `npm ci`;
+2. `npm run validate`;
+3. `npm run pack:check`;
+4. `npm run smoke:downstream`;
+5. `npm run plugin:check` и official plugin/skill validators;
+6. `npm run docs:pdf:check`;
+7. `npm run release:check` с exact release tag binding;
+8. validation append-only real-agent lifecycle log.
+
+PDF source и binaries должны совпасть детерминированно. Tag имеет форму `v<package-version>`.
+Publication не выполняется локальными validation commands.