codex-workflow-v2 2.0.0-beta.10 → 2.0.0-beta.12

package/docs/autonomy-guardrails.md

@@ -55,39 +55,48 @@ into the mutation actor slot.
 Invalid or stale review sidecars fail closed. The workflow blocks downstream acceptance and
 normal continuation when review evidence is malformed, unverified, or commit-mismatched.
 
-## Repeated failed review and remediation breaker
-
-The first failed independent review returns the Task to `needs_fix` and requires a changed or
-new remediation Step. After two distinct failed-review attempts, `next` returns
-`task plan-set with independent corrective audit`. Another Plan requires a JSON audit:
-
-```json
-{
-  "auditor": "corrective-auditor",
-  "summary": "The corrective Step covers the latest findings without changing the Brief.",
-  "decision": "continue-fix",
-  "reviewedFindingIds": ["REV-001", "REV-002"]
-}
-```
-
-Apply it with `task plan-set --corrective-audit-file <file>` only for the `continue-fix`
-path. The Auditor must differ from the failed-review author and cover every latest finding.
-`replan-required`, `split-required`, and `stop-escalate` are stop decisions: Core does not
-start another implementation loop.
-
-For guarded Steps, remediation attempts are also tracked in
-`remediation-events.jsonl`. Two ordinary remediation attempts are allowed. A third ordinary
-retry is blocked until `task corrective-decision` records a current corrective decision in
-`corrective-decisions.jsonl`. The corrective gate is derived from the guarded Step, current
-Plan Risk Audit, remediation history, and corrective-decision history, so it remains visible
-after content-only context refresh, Task Knowledge rebind, and reauthorization. `continue-fix`
-allows bounded continuation; `replan-required` requires an actual new Plan posture before
-execution; the other decisions stop or redirect ordinary execution. If that third, corrective
-remediation review also fails, Core enters a hard stop: `next` must report the stop without
-throwing, a fourth run and another `continue-fix`/`replan-required` decision are rejected,
-and only `split-required` or `stop-escalate` may be recorded. At the corrective boundary,
-`next` derives a distinct `agent:corrective-auditor:<task-id>` actor; selecting that actor is
-not a human approval, while auditor independence remains mandatory.
+## Repeated failed review and continuable remediation
+
+A failed final Task review returns the same Task to `needs_fix` and requires a changed or new
+remediation Step. The failed-review count is diagnostic evidence, not a lifecycle limit: another
+Plan does not require a separate corrective Plan Auditor merely because two or more reviews failed.
+Every replacement Plan must preserve the Task objective, requirements, and acceptance; changing
+those commitments requires an explicit scope decision outside ordinary remediation.
+
+For guarded Steps, every failed review is recorded in `remediation-events.jsonl`. Attempts one and
+two retain mode `ordinary`; later attempts use mode `corrective`, but the mode does not impose a
+maximum attempt ordinal. `next` continues to return `task run` for the same failed Step, and every
+new completion still requires a fresh strict review bound to its exact commit. Therefore repeated
+fixes cannot create an approval, while a fourth, tenth, or later reviewed attempt remains possible.
+
+Each failed review finding may carry `route: fix` or `route: replan`. `fix` is the backward-compatible
+default. `replan` is accepted only with `planConflict.planClause`, `whyFixCannotFit`, and
+`minimalPlanChange`; Core retains that evidence in the hash-chained Step-review event and routes
+the failed Step to `task plan-set`. Replan may change implementation Steps only. Explicit historical
+`continue-fix`, `replan-required`, `split-required`, and `stop-escalate` decisions remain readable;
+an explicit split or stop still outranks ordinary execution.
+
+### First-failure Plan-integrity recovery
+
+A mechanically impossible Plan check must not consume the second ordinary remediation attempt
+only to unlock corrective replan. After the first guarded `checks-failed` event, Core performs a
+read-only bounded assessment. `next` advertises `task plan-integrity-recover` only when all of the
+following are true:
+
+- the failed Step contains an exact root `npm run <script>` or `npm run-script <script>` check;
+- the named script is absent from the current root `package.json`;
+- `package.json` is outside the failed Step's `allowedWrites`;
+- exactly one ordinary `checks-failed` remediation event exists for the Step;
+- no corrective decision exists for its second-attempt binding;
+- every dirty file remains inside the Step's current `allowedWrites` and outside its
+  `forbiddenScope`.
+
+The recovery appends one hash-bound `replan-required` decision for attempt ordinal 2. It preserves
+the worktree and does not edit the Plan. A claimed C1 Task must present its current writer token and
+then follow `task corrective-yield`; the replacement Plan still requires the existing independent
+validation, Risk Audit, Human confirmation, journaled execution, readback, and renewed execution
+authorization. Other check failures use the normal continuable remediation route; they do not
+receive the narrow Plan-integrity shortcut, but attempt count alone never stops them.
 
 ## Atomic context refresh
 

package/docs/beta11-plan-integrity-recovery-brief.md

@@ -0,0 +1,38 @@
+# V2 beta.11 bounded Plan-integrity recovery
+
+## Problem
+
+A guarded Step may fail its first Core-owned completion because the approved Plan requires an
+exact root `npm run <script>` command, the script is absent, and the same Step cannot modify
+`package.json`. Re-advertising `task run` cannot succeed and consumes a second ordinary remediation
+attempt only to reach corrective replan.
+
+P01-A now rejects this contradiction before a fresh execution authorization when it is already
+provable at the selected evaluation HEAD. The beta.11 route remains necessary for pre-P01-A
+authorizations and contradictions that genuinely become observable only after execution starts.
+
+## Decision
+
+Add `task plan-integrity-recover` as a narrow explicit repair. Its read-side assessment proves one
+first `checks-failed` event, an absent root npm script, a manifest outside `allowedWrites`, and a
+worktree confined to the guarded Step. The mutation appends a hash-bound `replan-required`
+corrective decision for attempt ordinal 2. Existing C1 yield, corrective-replan Human gate,
+journal, recovery, readback, Plan validation, Risk Audit, and authorization supersession remain
+the only way to publish the replacement Plan.
+
+## Non-goals
+
+- No generic shell-command diagnosis.
+- No automatic Plan editing or inferred replacement command.
+- No `allowedWrites` expansion.
+- No second synthetic failure.
+- No bypass of C1 ownership, writer credentials, Human confirmation, independent validation, or
+  Risk Audit.
+- No recovery when dirty files escape the current Step boundary.
+
+## Required evidence
+
+The recovery event binds Task revision, Plan hash, failed remediation ID/hash, Step-definition
+hash, Git HEAD, root manifest hash, missing scripts, exact check commands, complete changed-file
+set, and a canonical conflict hash. Legacy corrective-decision events remain valid and retain the
+ordinary minimum of two failed attempts.

package/docs/decisions.md

@@ -64,10 +64,11 @@ This document closes the requirement gaps identified during the V2 design review
     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.
+    concurrency, restart/replay, crash-window, and provider risks visible. Repeated failed reviews
+    do not impose an attempt-count stop: findings default to a same-Task fix and may request replan
+    only with exact Plan-conflict evidence. Attempts after the second are marked corrective for
+    diagnosis, remain executable, and require another strict review. Explicit split/stop decisions
+    remain append-only authority and are never inferred from the counter.
 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

package/docs/delegated-approval.md

@@ -191,10 +191,11 @@ Plan-declared supporting additions допустимы только когда и
 изменении source set, category/authority, gaps или conflicts используй обычный видимый процесс.
 
 После submit запусти отдельный Independent Reviewer; Reviewer не использует
-grant и не исправляет код. После второго failed review не запускай очередной
-патч: получи отдельный corrective Plan audit, охватывающий все последние findings,
-и передай его через `--corrective-audit-file`. Продолжай только при
-`decision=continue-fix`; остальные решения верни пользователю/координатору.
+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 не совпал или требуется смысловое

package/docs/development-flow.md

@@ -28,6 +28,16 @@ uses a bootstrap audit over the preserved non-`completed`, non-`skipped` Steps o
 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`.
 
+P01-A adds a second, bounded admission check without adding a lifecycle stage. Before
+`task authorize`, Core reads the selected committed source and recognizes only three versioned
+mechanical forms: an exact root `npm run <literal-script>`, an exact structured
+`path:<repository-relative POSIX path>` output, and that same path supplied by an exact transitive
+Step predecessor with write authority. A proved contradiction returns to `task plan-set` without
+writing an approval. Unsupported commands, prose, or ambiguous future creation remain
+`unverified`, not pass or failure. A clear payload is stored inside the execution authorization,
+bound to the Brief, Plan, analyzer inputs/set, selected HEAD, and phase-aware base/Task branch.
+Freshness is checked before claim lease acquisition, Task start, and direct execution entry.
+
 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
@@ -73,12 +83,21 @@ 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 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.
+failure injection and hidden-default verification. Repeated failed reviews remain on the same
+Task. They require a new remediation Step for final Task review, or another implementation and
+fresh strict review for a failed guarded Step; they do not require a separate corrective Auditor
+based only on attempt count. Guarded attempts above two are recorded as `corrective` and remain
+executable. A reviewer routes to `replan` only with an exact Plan obstruction and minimal Plan
+change; ordinary findings default to `fix`. Remediation cannot change the Task objective,
+requirements, or acceptance.
+
+One bounded exception avoids a deliberately repeated failure for an older authorization without
+P01-A evidence or a contradiction that becomes observable only after execution starts. If the first guarded check failure
+is caused by an absent root npm script that the Step cannot add because `package.json` is outside
+its `allowedWrites`, fresh `next` advertises `task plan-integrity-recover`. The command records only
+the exact evidence-bound early `replan-required` posture; it never edits source, Plan, or Git.
+Continue through the advertised corrective yield and corrective replan rather than calling
+`task run` again.
 
 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
@@ -95,7 +114,10 @@ Discovery -> Milestone planning -> execution authorization -> active
   -> final acceptance -> accepted
 ```
 
-A Milestone Plan records outcome, success signal, acceptance, checks, and Task membership.
+A Milestone Plan records outcome, success signal, acceptance, checks, Task membership, and the
+canonical Task dependency DAG. Every membership explicitly supplies `dependsOnTaskIds`, including
+`[]`. A required consumer may depend only on required members of the same Milestone; duplicate,
+self, dangling, external, non-required-provider, and cyclic edges are rejected before commit.
 Membership is `required`, `waived`, or `cancelled`; non-required entries require a reason.
 Changing the Plan increments the membership revision, supersedes execution authorization,
 and prevents new linked Tasks from starting. A Task that has started cannot be removed;
@@ -115,18 +137,22 @@ Milestone Autonomy Contract may instead use `milestone autonomy-evolve` for memb
 changes while the outcome, success signal, acceptance, checks, discovery, and base branch
 remain unchanged. The same contract may complete an atomic content-only Task context refresh
 without a new human gate, but cannot approve Project Memory independently. Both paths retain
-journaled recovery across `state.json`, `plan.json`, and `scope-change-events.jsonl`.
+journaled recovery across `state.json`, `plan.json`, and `scope-change-events.jsonl`. The initial
+Plan uses the same recovery machinery for its exact two-file `state.json` + `plan.json` commit and
+does not manufacture a scope-change event.
 
 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
 and never changes Task state or reverts merged commits.
 
-Repository-level `next` considers Milestone membership before it dispatches a Task. An
-unstarted linked Task is actionable only while its Milestone is `active` and its current
-membership is `required`. Unstarted `waived`/`cancelled` memberships and Tasks belonging to
+Repository-level `next` considers Milestone membership and dependencies before it dispatches a
+Task. A linked Task is actionable only while its Milestone is `active`, its current membership is
+`required`, and every declared required predecessor is `merged`. Handoff prepare, claim before
+lease acquisition, and Task start use the same predicate. Unstarted `waived`/`cancelled`
+memberships and Tasks belonging to
 an accepted/cancelled Milestone are historical records, not work. A Task that already owns
-a workspace remains actionable while its non-terminal Milestone permits it to finish.
+a workspace does not bypass an unsatisfied Milestone predecessor.
 
 After successful Milestone validation, `next` emits `requiredHumanGate` containing the
 Milestone revision, Plan/Result/evidence hashes, validated base HEAD, and a deterministic

package/docs/lifecycle/state-machine-stabilization.md

@@ -266,7 +266,7 @@ The explorer must be exhaustive over semantic classes, bounded over cardinality,
 | Actor | human, valid delegate, claimant, other |
 | Lease | none, valid-owned, valid-other, stale |
 | Attempts | 0, 1, 2, 3+ |
-| Corrective posture | none, decision-needed, continue-fix, replan, split, stop, hard-stop, recovery-needed |
+| Corrective posture | none, automatic-continue, explicit continue-fix, replan, split, stop, recovery-needed |
 | Knowledge binding | active, stale, awaiting approval, conflicting |
 | Git | clean-bound, clean-diverged, dirty, malformed |
 | Authorization | absent, current, stale, superseded |
@@ -434,7 +434,7 @@ Production-file ownership is assigned before each implementation iteration. The
 | I07-CD1 round 4a | completed after fresh changed-evidence review | secret-free indexed closure extras; exact missing/duplicate/substituted closure diagnostics; all round-4 owned-input, generation, totality and budget corrections retained; private kernel remains `available-unwired` with execution linkage `pending-cd2` | Orchestrator typecheck/build/test compile, 56/56 focused, built-root 4-required/26-forbidden probe, genuine Core smoke and final full 262/262; independent typecheck/build/test compile, 56/56, root/Core/credential no-echo probes; fresh review `0 material / 0 major / 0 minor` | final credential Model SHA-256 `469c85247b497926b52a7e736202dcdb417494309a2f282f3affc87536ecf35d`; scoped 150-file candidate SHA-256 `4e120b7ded6d0fecae8d02906b9dda594e523303dab115e03a0e7193f99c835a`; manifest `edab7ee7ac4018e759f5fc702a11a0fd113ef4f2cf8ed8fa823a59fde3012a1a`; closure `3cbf139bc017d0fc87338a6c67dc04617de9ae2e1aafde5c712d8c9b3f7cf0b4` | accept CD-1 private credential kernel only; release readiness and public execution remain false; proceed next only to CD-2 storage/mutex/journal packet |
 | I07-CD2 | implementation and validation complete; fresh independent changed-evidence review pending | private same-slot Core Task mutex with opaque inode-bound handle; exact five-target preimage/postimage ownership; durable intent/phase hash chains; apply-or-confirm Task CAS; completed-target readback; pending/corrupt/orphan observation and central Task store gate; execution linkage advances to `pending-cd3` | pinned Node 24.17 typecheck/build/test compile; CD-2 oracle 4/4; combined focused 100/100 then final affected 61/61; built-root private-boundary/Core smoke; full regression 266/266; diff-check | live serialized/runtime/catalog/readiness pins unchanged; no public executor, recovery command, protocol/epoch/catalog activation or readiness reduction | retain runtime exclusivity, stale-lock recovery, target application, receipt-handle linkage, replay and dual terminal readback as CD-3/CD-4 blockers; do not call the transition executable |
 | I07-CD3 | implementation and validation complete; fresh independent changed-evidence review pending | private receipt-bound five-target corrective-replan executor/recovery/replay; exact state-before-publish roll-forward and dual readback; separate fixed-target corrective-yield journal with Writer-to-Core same-slot transfer; central pending-yield observation gate; no public activation | pinned Node 24.17 typecheck/build/test compile; replan/storage/yield focused 13/13; expanded affected 91/91 before final hardening; final full regression 275/275; built-root private-boundary/Core smoke; diff-check | live serialized SHA `626035488c83bb12091d1b5af959635c9af473f5a2d9e47817c70be4c5f58311`, runtime fingerprint `c8de50fcfd869327156afc1a676e87cd8684b25ce95c307f876b119ad3f082a8`, runtime catalog `3491e5d21c5d71385aefa62a62561b694e3ba41debfd31132cb26c05f7e4938b`, readiness report `742f40c20b81f34761fc3ec1c839aa81770e07f1deda33a4b2439297a195ad91`; static readiness and exact 11 blockers unchanged | keep both executors private and `pending-cd4`; CD-4 must atomically add protocol-v2 navigation/CLI, lifecycle epoch/catalog v4 activation, public repair, complete differential evidence and removal of the legacy corrective mutation bypass |
-| I07-CD4 | implementation and local changed-evidence hardening complete; independent external sign-off pending | protocol-v2 public yield/prepare/confirm/execute/repair; epoch 2 and definition/catalog format 4; active exact callable linkage; legacy corrective `task plan-set` disabled; protocol-v1 adoption evidence has a bounded read-only compatibility window; public candidate/input budgets, pending-journal admission and non-C1 writer-lease navigation now fail closed | pinned Node 24.17 affected 111/111 and full regression 279/279; built-root 4-required/26-forbidden; genuine Core `staticReady=true`; package dry-run, downstream smoke, plugin and release checks green; unchanged-candidate public CLI yield→prepare→confirm→execute→replay repeated green; legacy bypass, wrong confirmation, pending journal, oversized input and known active non-C1 lease are non-mutating | serialized SHA `6070765ab24dd24641a35ee3b3ed64a9dc9e89d705425f80918ad4500bd57800`; runtime fingerprint `bd4e7a0ddfcb6abc0c5eb107775e6aea7e08c4606dda4d945d77af8a4520710d`; runtime catalog `fa1d11860d4f07978c3b8e85d1f91cd3d15b17284b05f41e05d462d3bb092aed`; readiness report `c7fa9e19a453ee27915cfca298c65f548e992f22c01fec99460daa36cc12948d`; no static blockers | keep the candidate frozen for independent external changed-evidence sign-off; do not claim broad catalog completeness or stable release before that sign-off |
+| I07-CD4 | implementation and local changed-evidence hardening complete; independent external sign-off pending | protocol-v2 public yield/prepare/confirm/execute/repair; epoch 2 and definition/catalog format 4; active exact callable linkage; legacy corrective `task plan-set` disabled; protocol-v1 adoption evidence has a bounded read-only compatibility window; public candidate/input budgets, pending-journal admission and non-C1 writer-lease navigation now fail closed | pinned Node 24.17 affected 111/111 and full regression 279/279; built-root 4-required/26-forbidden; genuine Core `staticReady=true`; package dry-run, downstream smoke, plugin and release checks green; unchanged-candidate public CLI yield→prepare→confirm→execute→replay repeated green; legacy bypass, wrong confirmation, pending journal, oversized input and known active non-C1 lease are non-mutating | serialized SHA `c601cc100790a19e6ece2a1d60fb46d1e1d52e6922e6104d84f4b6ffe7ba0225`; runtime fingerprint `bd4e7a0ddfcb6abc0c5eb107775e6aea7e08c4606dda4d945d77af8a4520710d`; runtime catalog `fa1d11860d4f07978c3b8e85d1f91cd3d15b17284b05f41e05d462d3bb092aed`; readiness report `c7fa9e19a453ee27915cfca298c65f548e992f22c01fec99460daa36cc12948d`; no static blockers | keep the candidate frozen for independent external changed-evidence sign-off; do not claim broad catalog completeness or stable release before that sign-off |
 
 No new implementation round starts until every finding from the prior round has a disposition.
 

package/docs/pdf/README.md

@@ -0,0 +1,24 @@
+# Russian PDF documentation
+
+The three tracked PDFs in this directory are deterministic release artifacts generated from the
+reviewable Markdown files in [`sources`](sources/).
+
+Generate them with:
+
+```bash
+npm run docs:pdf
+```
+
+Verify that the tracked binaries match the current sources and package version with:
+
+```bash
+npm run docs:pdf:check
+```
+
+The generator reads the exact version from the root `package.json`, uses embedded TrueType font
+subsets, and writes deterministic PDF bytes. A release must update source and PDF together. The
+PDFs are human-facing artifacts; runtime code, schemas, the bundled gateway and ordinary Markdown
+documents remain the technical authority.
+
+The runner uses `CODEX_WORKFLOW_PDF_PYTHON` when supplied, then the bundled Codex App Python, then
+`python3`. Non-Codex environments can install the pinned dependency from `requirements.txt`.

package/docs/pdf/requirements.txt

@@ -0,0 +1 @@
+reportlab==4.4.9

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

@@ -0,0 +1,235 @@
+---
+title: Codex Workflow V2: архитектура beta.12
+subtitle: Источники истины, lifecycle, роли, delegation, зависимости Tasks и границы доверия
+part: Часть 1 из 3 | Архитектура
+document_version: 2.0
+date: 27 августа 2026
+subject: Архитектура и границы Codex Workflow V2 beta.12
+---
+
+# 1. Назначение и граница системы
+
+Codex Workflow V2 - локальный state machine поверх Codex App, Git и файлов проекта. Codex выполняет
+исследование и реализацию. Workflow Core решает, разрешена ли конкретная мутация, связывает её с
+актуальными revisions и hashes, управляет writer credentials и создаёт проверяемые Git evidence.
+
+> **Главная граница:** файлы проекта и Git history являются долговременной продуктовой памятью. Локальный Workflow state хранит производный lifecycle и не может заменять repository knowledge.
+
+Система рассчитана на одного пользователя и одну машину. Она не предоставляет distributed locking,
+криптографическую идентификацию actor string или безопасную синхронизацию state между компьютерами.
+
+## 1.1. Что beta.12 гарантирует
+
+- exact project-local npm package и совместимый handshake до lifecycle действий;
+- Discovery до materialization Task или Milestone;
+- утверждённую Project Knowledge Map и Plan, связанный с её точной revision/hash;
+- mechanical-feasibility проверку поддерживаемых форм Plan до новой Task authorization;
+- явный Milestone dependency DAG и один общий runnable predicate для routing, handoff, claim и start;
+- один C1 writer lease, секретные one-time credentials и Core-owned Step commits;
+- external-sealed Step/Task review в отдельных Codex tasks;
+- state-bound human gates либо ранее выданные bounded delegation contracts;
+- journaled recovery для составных переходов и fail-closed поведение при drift/corruption.
+
+## 1.2. Что beta.12 не гарантирует
+
+- правильность продуктовой идеи или автоматически выбранного provider Task;
+- semantic sufficiency Plan, если точные факты нельзя доказать поддерживаемым analyzer;
+- параллельную работу нескольких writers в одном checkout;
+- автоматический structural replacement после `split-required`;
+- восстановление вручную повреждённого state без штатной recovery transition.
+
+# 2. Шесть уровней и источники истины
+
+| Уровень | Источник истины | Ответственность |
+|---|---|---|
+| Пользователь / principal | Явные ответы и подтверждённые policies | Scope, semantic unknowns, grant issuance, human gates |
+| Codex App | Project folders, tasks, permissions | User-visible execution contexts и bounded tool access |
+| Роли агентов | Fresh ContextPacket и Workflow projection | Discovery, planning, execution, review, coordination |
+| Project-local gateway | Exact installed package и protocol | Handshake, routing discipline, app chat boundary |
+| Workflow Core | Runtime transitions и schemas | Revisions, hashes, locks, Git ownership, evidence |
+| Repository и local state | Git/files и revisioned state | Durable product facts и производный lifecycle |
+
+При расхождении приоритет имеют runtime Core и обычные файлы текущего repository. PDF объясняет
+контракт человеку, но не заменяет `status`, свежий `next`, schemas или package-local help.
+
+## 2.1. Exact package boundary
+
+Продуктовый repository обязан объявить `codex-workflow-v2` точной версией в `devDependencies`.
+Gateway разрешает только `node_modules/codex-workflow-v2/dist/src/cli.js` этого repository,
+сравнивает installed и declared versions, затем выполняет `gateway handshake`.
+
+```text
+AGENTS.md
+-> project-local gateway
+-> gateway handshake
+-> status
+-> next [--task <exact TASK-ID>]
+-> только рекламируемая transition
+```
+
+`doctor` является диагностикой, но не заменяет успешные `status` и `next`. Help разрешён только для
+уточнения syntax после свежего routing response.
+
+# 3. Долговременные и производные артефакты
+
+| Артефакт | Где находится | Кто владеет записью |
+|---|---|---|
+| Product code, tests, Markdown docs | Git repository | Worker в Plan scope; Git commit создаёт Core |
+| AGENTS.md и Project Knowledge | Git repository | Пользователь и обычный reviewable change |
+| Knowledge Map | Local Workflow state | Project-memory transitions |
+| Discovery state | Local Workflow state | Discovery transitions |
+| Brief, Plan, Result, evidence | Local Workflow state с versioned artifacts | Core transitions |
+| Task/Milestone state и sidecars | Local Workflow state | Core, CAS и schema validation |
+| Writer locks и private credentials | Local Workflow state | Lock manager и C1 transitions |
+| Transaction journals | Local Workflow state | Composite transition recovery |
+| codebase graph binding | Local Workflow state | Derived evidence, не product authority |
+
+Ручное редактирование state, locks, sidecars или `.versions` запрещено. Оно ломает hash chain,
+expected revision и восстановимость составных операций.
+
+# 4. Discovery, Task и Milestone
+
+| Сущность | Назначение | Terminal success |
+|---|---|---|
+| Discovery | Уточнить outcome, scope, acceptance, constraints и unknowns | Готова к materialization |
+| Task | Один самостоятельный проверяемый результат | Reviewed, accepted и merged |
+| Step | Атомарный инкремент внутри Task | Checks, один Core commit и evidence |
+| Milestone | Сквозной outcome из связанных Tasks | Required Tasks merged, validation и acceptance |
+
+## 4.1. Task lifecycle
+
+```text
+Discovery -> materialize -> Plan -> Plan Risk Audit
+-> mechanical feasibility -> execution authorization
+-> C1 handoff -> claim -> start -> Steps
+-> submit -> external-sealed review -> Result
+-> final acceptance -> merge
+```
+
+Fresh Task authorization записывает versioned mechanical-feasibility evidence. Analyzer может
+выдать `blocked`, `pass` или `unverified`. `unverified` не означает semantic approval; он означает,
+что поддерживаемая точная грамматика не доказала противоречие.
+
+## 4.2. Milestone initial assembly
+
+После materialization Milestone Core возвращает `milestone initial-assembly`. Coordinator создаёт
+linked Task Discoveries и materializes Tasks только через команды, рекламируемые `next`. После
+появления полного intended membership один `milestone plan-set` атомарно публикует state и plan.json.
+До этого execution недоступно.
+
+Каждая membership содержит:
+
+```text
+taskId
+disposition: required | waived | cancelled
+reason
+dependsOnTaskIds: [exact predecessor Task IDs]
+```
+
+Даже независимая Task обязана объявить `dependsOnTaskIds: []`. Отсутствующее поле в legacy state
+означает unknown dependency authority, а не пустой граф.
+
+## 4.3. Runnable predicate P04-A
+
+Task runnable только когда Milestone active, membership required и все canonical predecessors имеют
+status `merged`. Ordinal, название, время создания и порядок в чате не создают dependency.
+
+Один predicate применяется к repository routing, Task-specific routing, handoff preparation,
+claim до lease acquisition и direct start. Authorization не обходит dependency block.
+
+# 5. Delegated approval и Milestone autonomy
+
+Delegation не превращает agent в human actor. Event отдельно хранит principal, delegate, grant,
+policy hash, transition, scope и expiry.
+
+| Механизм | Когда применять | Что не разрешает |
+|---|---|---|
+| Direct human gate | Default path | Никакой последующей автономии |
+| DGA/DGR delegated approval | Exact allow-listed approval transition | Scope expansion, grant issuance, обычные execution transitions |
+| Milestone Autonomy Contract | После полного initial Milestone Plan | Outcome/check/base/discovery changes и standalone map approval |
+
+Для нового `AUTO` Discovery допустим короткий project-scoped DGR, если нужен exact
+`project_memory.approve` или будущий approval transition. Blocking semantic unknown всегда возвращается
+пользователю. После полного initial Milestone Plan предпочтителен один bounded
+`milestone autonomy-prepare` gate и отдельное подтверждение `MAC-*`, затем `autonomy-grant`.
+
+Milestone Autonomy Contract покрывает разрешённые Task/Milestone approvals, membership-only evolve и
+Project Memory approval только внутри atomic Task context refresh этого Milestone. Grant не применяется
+к handoff, claim, run, step-complete, reviews, sync-base или merge.
+
+# 6. Codex App chat topology
+
+Milestone coordinator и Task chats являются отдельными user-visible Codex tasks, не fork одного
+conversation. Coordinator создаёт Task chat just-in-time, передаёт закрытый TaskContextPacket и
+остаётся активным supervisor до terminal Milestone либо настоящего user gate.
+
+```text
+Coordinator
+  -> Task T01 chat
+       -> Step Review chat при external-sealed gate
+       -> Final Review chat
+       -> Corrective/Plan Audit chat при необходимости
+  -> status -> next -> milestone progress
+  -> следующий runnable Task chat
+```
+
+Project chat registry атомарно выдаёт monotonic `#NNN`. Название всегда содержит membership ordinal и
+полный entity ID. Sidebar count, creation order и ручное `01/02` не являются authority.
+
+Coordinator ждёт routed Task через bounded waits, читает закрытый CoordinatorReport, затем проверяет
+repository `status -> next`. Завершение дочернего чата само по себе не доказывает terminal Task.
+
+# 7. C1 handoff, lease и Git ownership
+
+`task handoff-prepare` возвращает одноразовый `credentialHandoff`. Он используется ровно один раз
+целевым actor в `task claim`. Claim проверяет Task/Milestone dependency binding и только затем выдаёт
+`writerLeaseReceipt`. `task run` обновляет активный lease и возвращает Step context.
+
+Bearer credentials нельзя печатать, сохранять в файлы, передавать Reviewer или включать в evidence.
+Если token утерян, используется только рекламируемая credential recovery transition.
+
+Worker меняет только `allowedWrites` и оставляет изменения uncommitted. Coordinator вызывает точный
+`task step-complete`; Core запускает checks, проверяет scope/history, создаёт один commit и evidence.
+
+# 8. Knowledge Map и context refresh
+
+Project Knowledge Map хранит paths, categories, scope, authority, hashes, gaps и conflicts, но не
+копирует содержимое файлов. Scan является read-only. Reconcile и approve выполняются только через Core.
+
+Если top-level `next` возвращает `task context-refresh`, Coordinator вызывает только эту atomic
+transition с указанными revisions, actor и grant. Standalone reconcile перед ней создаёт human-approval
+gap и блокируется.
+
+Кроме content-only drift, Core может допустить exact supporting-source addition, заранее объявленное
+execution-authorized Plan и покрытое тем же Milestone Autonomy Contract. Unsafe differences возвращают
+обычный видимый reconcile/approve/rebind/reauthorize flow.
+
+# 9. Review и corrective recovery
+
+В Codex App strict review выполняется external-sealed:
+
+1. Core формирует read-only review packet и repository seal.
+2. Task chat создаёт отдельный Reviewer chat.
+3. Reviewer возвращает закрытый schema-valid result без mutations.
+4. Core записывает его только если packet и seals не изменились.
+
+Failed review не ограничивает число попыток. Попытки 1-2 имеют mode `ordinary`, последующие —
+`corrective`; все исполнимы и требуют нового strict review. `route=fix` продолжает Task, а
+`route=replan` допустим только с точным Plan conflict и меняет лишь implementation Steps, не objective,
+requirements или acceptance. Explicit `split-required` и `stop-escalate` остаются stop/redirect decisions.
+
+beta.11 `task plan-integrity-recover` существует для одного первого checks-failed legacy/late case:
+отсутствует exact root npm script и текущий Step не может изменить package.json. Recovery не меняет
+worktree или Plan и не создаёт synthetic second failure; он записывает bound `replan-required`.
+
+> **Стоп P04-A:** `split-required` возвращает `STRUCTURAL_REPLACEMENT_REQUIRED` и `structuralReplacementAvailable=false`. Нельзя вызывать retained replacement command, потреблять replacement Discovery или вручную менять topology. Продолжение возможно только после P04-B/P05.
+
+# 10. Operational checklist
+
+- exact package version установлен, bundled gateway соответствует release и переустановлен;
+- handshake подтверждает protocol 2, state schema 2 и beta.12 capabilities;
+- каждый mutation следует свежему `status -> next` и exact option contract;
+- semantic unknowns и human gates не маскируются delegation;
+- Task chats создаёт coordinator, credentials остаются только в памяти;
+- dependencies, progress и review posture берутся из Core projections;
+- local state не редактируется вручную; release и package update выполняются только после safe preflight и обязательных checks.