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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (77) hide show
  1. package/README.md +114 -10
  2. package/dist/src/alpha6/adoption.d.ts +55 -0
  3. package/dist/src/alpha6/adoption.js +920 -0
  4. package/dist/src/alpha6/adoption.js.map +1 -0
  5. package/dist/src/alpha6/handoff.d.ts +39 -0
  6. package/dist/src/alpha6/handoff.js +975 -0
  7. package/dist/src/alpha6/handoff.js.map +1 -0
  8. package/dist/src/alpha6/journal.d.ts +30 -0
  9. package/dist/src/alpha6/journal.js +369 -0
  10. package/dist/src/alpha6/journal.js.map +1 -0
  11. package/dist/src/alpha6/milestone.d.ts +49 -0
  12. package/dist/src/alpha6/milestone.js +1049 -0
  13. package/dist/src/alpha6/milestone.js.map +1 -0
  14. package/dist/src/alpha6/plan-risk.d.ts +32 -0
  15. package/dist/src/alpha6/plan-risk.js +847 -0
  16. package/dist/src/alpha6/plan-risk.js.map +1 -0
  17. package/dist/src/alpha6/remediation.d.ts +20 -0
  18. package/dist/src/alpha6/remediation.js +748 -0
  19. package/dist/src/alpha6/remediation.js.map +1 -0
  20. package/dist/src/alpha6/review.d.ts +46 -0
  21. package/dist/src/alpha6/review.js +785 -0
  22. package/dist/src/alpha6/review.js.map +1 -0
  23. package/dist/src/alpha6/store-sidecars.d.ts +35 -0
  24. package/dist/src/alpha6/store-sidecars.js +281 -0
  25. package/dist/src/alpha6/store-sidecars.js.map +1 -0
  26. package/dist/src/cli.js +95 -19
  27. package/dist/src/cli.js.map +1 -1
  28. package/dist/src/contracts.d.ts +259 -0
  29. package/dist/src/git.js +2 -1
  30. package/dist/src/git.js.map +1 -1
  31. package/dist/src/index.d.ts +2 -0
  32. package/dist/src/reviewer.d.ts +6 -1
  33. package/dist/src/reviewer.js +145 -32
  34. package/dist/src/reviewer.js.map +1 -1
  35. package/dist/src/state/lock.d.ts +1 -0
  36. package/dist/src/state/lock.js +7 -1
  37. package/dist/src/state/lock.js.map +1 -1
  38. package/dist/src/state/store.d.ts +39 -1
  39. package/dist/src/state/store.js +127 -1
  40. package/dist/src/state/store.js.map +1 -1
  41. package/dist/src/version.d.ts +1 -1
  42. package/dist/src/version.js +1 -1
  43. package/dist/src/version.js.map +1 -1
  44. package/dist/src/workflow.d.ts +123 -9
  45. package/dist/src/workflow.js +1497 -76
  46. package/dist/src/workflow.js.map +1 -1
  47. package/docs/autonomy-guardrails.md +143 -0
  48. package/docs/decisions.md +27 -0
  49. package/docs/delegated-approval.md +30 -5
  50. package/docs/development-flow.md +40 -1
  51. package/docs/pdf/codex-workflow-v2-architecture-ru.pdf +155 -136
  52. package/docs/pdf/codex-workflow-v2-chat-only-guide-ru.pdf +236 -223
  53. package/docs/pdf/codex-workflow-v2-technical-reference-ru.pdf +225 -206
  54. package/docs/project-memory.md +7 -0
  55. package/docs/release.md +7 -0
  56. package/docs/updating-existing-project.md +75 -5
  57. package/docs/validation-report.md +56 -34
  58. package/package.json +2 -2
  59. package/plugins/codex-workflow-gateway/references/protocol.md +155 -6
  60. package/plugins/codex-workflow-gateway/skills/codex-workflow-gateway/SKILL.md +23 -1
  61. package/references/git-policy.md +5 -2
  62. package/references/state-machine.md +36 -0
  63. package/references/validation-and-review.md +28 -1
  64. package/roles/delivery-coordinator.md +11 -0
  65. package/roles/independent-reviewer.md +3 -0
  66. package/roles/technical-planner.md +7 -0
  67. package/roles/worker.md +4 -0
  68. package/schemas/adoption-posture-event.schema.json +129 -0
  69. package/schemas/corrective-decision-event.schema.json +55 -0
  70. package/schemas/corrective-plan-audit.schema.json +20 -0
  71. package/schemas/milestone-scope-change-event.schema.json +68 -0
  72. package/schemas/milestone-transaction-journal.schema.json +95 -0
  73. package/schemas/plan-risk-audit-event.schema.json +90 -0
  74. package/schemas/remediation-event.schema.json +53 -0
  75. package/schemas/reviewer-attestation-event.schema.json +49 -0
  76. package/schemas/step-review-event.schema.json +74 -0
  77. package/schemas/task-handoff-event.schema.json +116 -0
@@ -30,6 +30,13 @@ definition, status, and evidence record, records the old/new binding, supersedes
30
30
  authorization, and cannot run while a Step is in progress. If local state is lost, the map
31
31
  is rebuilt from repository files.
32
32
 
33
+ For delegated autonomy, repository `next` may expose `contextRefresh` when the stored map was
34
+ active and inspection proves content-hash-only drift. `task context-refresh` then performs
35
+ reconcile, delegated map approval, Task rebind, and delegated execution authorization while
36
+ preserving the ordinary audit events. The command rejects new/removed sources, category,
37
+ scope or authority changes, changed gaps, and conflicts. Those changes always remain visible
38
+ for normal classification and approval.
39
+
33
40
  ## Codebase graph
34
41
 
35
42
  The graph is an optional derived index, never the durable memory authority. The gateway asks
package/docs/release.md CHANGED
@@ -20,6 +20,13 @@ The downstream smoke packs the actual tarball, installs it into an empty tempora
20
20
  runs the packaged CLI handshake, and proves installation created none of `.codex`, `.tasks`,
21
21
  `.increments`, or `.memory-bank` in that project.
22
22
 
23
+ For alpha.6, the release gate also relies on `npm run release:check` to fail if:
24
+
25
+ - canonical entity schema 2 shapes drift;
26
+ - protocol 1 compatibility is no longer additive;
27
+ - the delegated transition allow-list expands;
28
+ - alpha.6 adoption is presented as `state migrate` instead of posture sidecars.
29
+
23
30
  Tag releases as `v<package-version>`. The tag workflow verifies the tag/package match and
24
31
  uses npm trusted publishing with public access. For a public GitHub repository and public
25
32
  package, npm trusted publishing generates provenance automatically. Publishing is never
@@ -19,7 +19,30 @@ gateway, но не удаляет и не пересоздаёт это сост
19
19
  Никогда не разрешайте агенту вручную редактировать, переносить или удалять внешний state.
20
20
  Команда миграции нужна только тогда, когда документация новой версии прямо сообщает о новой
21
21
  state schema. Совпадение `stateSchemaVersion` до и после обновления означает, что миграция не
22
- нужна.
22
+ нужна. Для alpha.6 при `stateSchemaVersion: 2` применяется не migration, а sidecar-only
23
+ adoption posture.
24
+
25
+ ## Исключение: claimed C1 strict-review deadlock в alpha.6
26
+
27
+ Не обновляйте dependency, если alpha.6 Task уже имеет `in_progress` Step с completion evidence,
28
+ pending strict review и stale Knowledge binding. Для такого состояния используйте внешний
29
+ точный runner `2.0.0-alpha.6.1`; сам проект до завершения recovery остаётся закреплён на
30
+ `2.0.0-alpha.6`.
31
+
32
+ Сначала выполните только `update rescue-preflight`. Продолжать разрешено исключительно при
33
+ `eligible=true` и одной exact action `update rescue-review`. Передайте returned Task ID, Step
34
+ ID, revision, claimant actor и исходный bound writer token. Не выводите token в чат и не
35
+ передавайте другому actor.
36
+
37
+ Recovery не требует и не допускает предварительный `locks repair`: alpha.6.1 проверяет token
38
+ сразу против существующего lease и C1 hash, затем сохраняет и heartbeat'ит тот же lease в
39
+ единственной guarded review-команде. Active и stale lease допустимы только при exact binding.
40
+ Неверный actor/token, dirty checkout, advanced HEAD, второй pending review
41
+ или посторонний lease блокируют переход без изменения Task state.
42
+
43
+ После successful review следуйте обычному `next`: reconcile/approve Knowledge Map, выполните
44
+ knowledge rebind, свежую authorization и завершите Task. Только на безопасной lifecycle-границе
45
+ запускайте обычное обновление dependency и gateway.
23
46
 
24
47
  ## 1. Подготовьте отдельный чат обновления
25
48
 
@@ -33,10 +56,12 @@ Codex и откройте в нужном проекте отдельный ча
33
56
  из npm: https://www.npmjs.com/package/codex-workflow-v2.
34
57
 
35
58
  Все команды выполняешь ты. Сначала прочитай AGENTS.md и определи Git root.
36
- До изменений запусти project-local gateway handshake, doctor, status и next;
59
+ До изменений запусти project-local gateway handshake, doctor, status, next и
60
+ read-only `update preflight`;
37
61
  зафиксируй текущую версию, protocolVersion, stateSchemaVersion, projectId,
38
- активные сущности и наличие writer lease. Если Worker сейчас выполняется,
39
- остановись без обновления.
62
+ активные сущности и наличие writer lease. Продолжай только если preflight
63
+ вернул safe=true: checkout чистый, running Step и active writer lease отсутствуют.
64
+ Иначе остановись без обновления и покажи blockers.
40
65
 
41
66
  Обнови только точную npm-зависимость и lock-файл, без диапазона версий.
42
67
  Не удаляй и не редактируй вручную $CODEX_HOME/workflow-state/v2.
@@ -62,6 +87,9 @@ plugin за пределами workspace. Это ожидаемая границ
62
87
  5. `projectId` совпадает со значением до обновления.
63
88
  6. Существующие Task/Milestone ID, revisions и terminal statuses сохранились.
64
89
  7. Персональный gateway обновлён из установленного пакета.
90
+ 8. `update preflight` до изменения подтвердил чистую lifecycle-границу.
91
+ 9. Для alpha.6 существующий schema 2 проект либо уже имеет `adoption-posture.jsonl`,
92
+ либо `next`/`status` требуют `state adoption-prepare` и затем `state adoption-apply`.
65
93
 
66
94
  Изменение `projectId`, исчезновение сущностей или ошибка unsupported state schema — причина
67
95
  остановиться. Не соглашайтесь на «починку» удалением state. Агент должен вернуть dependency к
@@ -92,6 +120,42 @@ handshake, doctor, status и next. Подтверди точную declared/inst
92
120
  нужно выполнить `scan/reconcile`, показать пользователю изменения классификации и получить
93
121
  approval, если он требуется.
94
122
 
123
+ ## 3.0. Alpha.6 adoption для существующего schema 2 проекта
124
+
125
+ Если проект уже вёлся на alpha.5 или другой schema 2 версии без alpha.6 posture, новый runtime
126
+ не разрешит execution-переходы, пока не будет записан adoption sidecar. Это нормальное
127
+ fail-closed поведение, а не повреждение state.
128
+
129
+ Порядок:
130
+
131
+ 1. `update preflight --repo .`
132
+ 2. `state adoption-prepare --repo .`
133
+ 3. Проверить returned baseline и `ADA-*` confirmation code
134
+ 4. `state adoption-apply --repo . --actor <human-actor> --confirmation-code <ADA-CODE>`
135
+
136
+ Граница должна быть безопасной:
137
+
138
+ - checkout чистый;
139
+ - нет `in_progress` Step;
140
+ - нет active writer lease;
141
+ - stale writer lease сначала чинится обычным repair-путём.
142
+
143
+ Alpha.6 adoption сохраняет:
144
+
145
+ - terminal Milestones со статусом `accepted` или `cancelled`;
146
+ - terminal Tasks со статусом `merged` или `cancelled`;
147
+ - completed и skipped Steps в активных Tasks вместе с их evidence.
148
+
149
+ Alpha.6 adoption не делает:
150
+
151
+ - не переписывает canonical entity JSON;
152
+ - не переоткрывает terminal-сущности;
153
+ - не прогоняет заново уже completed legacy Steps;
154
+ - не использует `state migrate`.
155
+
156
+ После adoption remaining legacy scope должен получить bootstrap Plan Risk Audit только для
157
+ оставшихся non-`completed` и non-`skipped` Step.
158
+
95
159
  ## 3.1. При необходимости включите delegated approval
96
160
 
97
161
  Delegated approval не включается автоматически после обновления. Существующие авторизации и
@@ -147,7 +211,9 @@ Revocation запрещает будущие использования, но н
147
211
  Codex-процесса. Любой процесс с доступом к локальному state и CLI может заявить строку
148
212
  delegate. Поэтому project-wide grant должен быть короткоживущим, а секреты, платежи, реальные
149
213
  торговые операции и иные необратимые действия требуют отдельных технических ограничений и не
150
- должны полагаться только на delegated approval.
214
+ должны полагаться только на delegated approval. Alpha.6 не расширяет allow-list transitions:
215
+ grant не даёт authority на adoption apply, Milestone scope change или другие новые
216
+ human-only guardrails.
151
217
 
152
218
  ## 3.2. Запустите delegate в новом чате
153
219
 
@@ -181,6 +247,10 @@ NN - Standalone delegated task
181
247
  После завершения автономного окна попросите отдельный контрольный чат показать
182
248
  `delegation list`, использованные authorization events и отозвать ненужный широкий grant.
183
249
 
250
+ Для Milestone delegate отдельный Task-чат обязателен для каждой required Task. Это сохраняет
251
+ пользовательский audit trail и не позволяет одному длинному Milestone-чату накапливать
252
+ реализацию, compaction и review всех Tasks.
253
+
184
254
  ## 4. Продолжите начатый Milestone или создайте следующий
185
255
 
186
256
  Terminal Milestone со статусом `accepted` остаётся закрытым. Для следующего результата нужно
@@ -1,38 +1,60 @@
1
1
  # V2 Alpha Validation Report
2
2
 
3
- Release candidate `2.0.0-alpha.4` was validated on 2026-08-12 with Node.js 24.17.0.
3
+ Release candidate `2.0.0-alpha.6.1` was validated on 2026-08-14 with Node.js 24.17.0 as a
4
+ narrow backport from the published `2.0.0-alpha.6` baseline.
4
5
 
5
- - TypeScript typecheck and build passed.
6
- - All 47 unit and integration tests passed. Coverage includes the complete Task lifecycle,
7
- a Project Knowledge Map change between Steps, preservation of completed Step evidence,
8
- mandatory reauthorization, the public `task knowledge-rebind` CLI route, no-op and active
9
- Worker rejection, current gateway capability negotiation, and rejection of deprecated
10
- state schema instead of migration.
11
- - Delegated approval coverage includes DGA-bound grant issuance, project/Milestone/Task
12
- scopes, Knowledge Map approval, all Task/Milestone execution and final transitions,
13
- `next.delegatedApprovalOptions`, explicit principal/delegate audit metadata, actor,
14
- transition and scope rejection, expiry, revocation, duplicate issuance, and policy-hash
15
- tamper rejection.
16
- - Milestone scheduling now ignores unstarted Tasks with cancelled/waived or terminal
17
- membership paths. Final Milestone acceptance exposes a revision/hash/HEAD-bound human gate,
18
- rejects a wrong code, and regenerates its code after base advancement and revalidation.
19
- - Milestone amendments, graph binding, deterministic V1 snapshot, symlink rejection, writer
20
- leases, and strict reviewer fail-closed behavior also passed.
21
- - npm dry-run packaging produced `codex-workflow-v2-2.0.0-alpha.4.tgz` with runtime, schemas,
22
- roles, references, docs, and plugin source.
23
- - Downstream installation from that tarball and the packaged CLI handshake passed; the
24
- installation created none of the forbidden repository workflow directories.
25
- - Plugin validation and the repository release check passed for `2.0.0-alpha.4`.
26
- - The alpha.4 CLI read the existing Signal schema 2 project state without migration:
27
- project ID `b06d0f18f790f4521a23c770`, accepted Milestone 1 revision 10, historical
28
- authorization events, and all entity IDs were preserved; `delegations` was an empty
29
- additive collection and repository-level `next` remained `idle`.
30
- - The three Russian PDFs were regenerated and all 40 pages were rendered to PNG for visual
31
- inspection; delegated approval, compatibility, grant issuance, audit, revocation, and
32
- chat-only grant issuance and Milestone/Task delegate launch prompts are present without
33
- layout defects.
6
+ - `npm run typecheck`, `npm run build`, `npm test`, `npm run validate`, `npm run plugin:check`,
7
+ `npm run smoke:downstream`, `npm run release:check`, and `npm run pack:check` passed in the
8
+ sequential backport validation.
9
+ - The final sequential full suite passed `83/83` on 2026-08-14.
10
+ - The package test script runs test files sequentially and uses Node's `--test-force-exit`
11
+ after all test cases finish because concurrent isolated runners retain IPC/stdio handles in
12
+ this environment; the same 83 cases also passed when executed per file.
13
+ - Plan Risk Audit coverage includes the combined `plan-set --risk-audit-file` path, atomic
14
+ rejection before Task/Plan acceptance, distinct planner/auditor identities, exact current
15
+ Step-set equality, concrete failure modes, executable evidence binding, coupled
16
+ migration/recovery rationale, blocking split/stop decisions, and adoption-aware
17
+ remaining-scope bootstrap handling.
18
+ - Strict high-risk Step Review coverage includes workflow-owned completion commits,
19
+ `task step-review` routing, commit-bound reviewer attestation, and fail-closed rejection of
20
+ stale, malformed, unverified, and wrong-commit review evidence.
21
+ - Alpha.6.1 rescue coverage reproduces the production deadlock with an exact alpha.6
22
+ dependency, stale Knowledge binding, pending strict review, claimed C1 posture, and both
23
+ active and stale bound leases. The single rescue action preserves the original lease,
24
+ exposes no plaintext token, completes review with the exact claimant/token, and fails closed
25
+ for a wrong actor or token. Ordinary `task step-review` remains blocked by stale Knowledge.
26
+ - Guarded remediation coverage includes the per-Step circuit breaker: two ordinary retries
27
+ allowed, third gated by bounded `continue-fix`, a hard stop after a third failed corrective
28
+ review, and stop/redirection handling for `split-required` and `stop-escalate`.
29
+ - Milestone coverage includes human-only scope-change prepare/apply, journaled recovery of
30
+ `state.json`, `plan.json`, and `scope-change-events.jsonl`, plus membership-integrity
31
+ blocking for stale or contradictory Milestone/Task state, including reverse detection of a
32
+ live linked Task missing from required/waived/cancelled membership.
33
+ - `C1` coordination coverage includes the full prepared bundle, one-time and expiring claim
34
+ token, Task/Plan/Knowledge/Milestone bindings, exact expected-next prompt, optional grant,
35
+ target-only claim, claimant-only mutation, mandatory claim before Milestone Task start,
36
+ lease-token binding, and terminal evidence-bound handback.
37
+ - Adoption coverage includes sidecar-only `state adoption-prepare` and `state adoption-apply`,
38
+ automatic posture initialization for fresh alpha.6 projects, preservation of terminal
39
+ Milestones and Tasks, preservation of completed and skipped legacy Steps, and execution
40
+ blocking until posture is present.
41
+ - Compatibility checks passed for `protocolVersion: 1`, `STATE_SCHEMA_VERSION: 2`, unchanged
42
+ canonical Task and Milestone shapes, and unchanged delegated transition allow-list.
43
+ - Gateway handshake coverage includes the alpha.6 capabilities:
44
+ `plan-risk-audit-sidecar-v1`, `step-strict-review-sidecar-v1`,
45
+ `step-remediation-circuit-breaker-sidecar-v1`, `milestone-scope-change-sidecar-v1`,
46
+ `milestone-membership-integrity-v1`, `task-c1-handoff-sidecar-v1`, and
47
+ `alpha6-adoption-posture-v1`, plus strengthened contracts advertised as
48
+ `semantic-plan-risk-audit-v2`, `guarded-remediation-hard-stop-v1`,
49
+ `milestone-reverse-membership-integrity-v1`, and `task-c1-handoff-bundle-v2`.
50
+ - npm dry-run packaging produced `codex-workflow-v2-2.0.0-alpha.6.1.tgz` with runtime, schemas,
51
+ references, docs, and plugin source. Downstream installation and the packaged CLI handshake
52
+ passed, and the install created none of `.codex`, `.tasks`, `.increments`, or
53
+ `.memory-bank` in the temporary project.
34
54
 
35
- The strict reviewer implementation did not change in this release candidate. Its original
36
- 2026-07-16 real Codex CLI isolation probe denied a repository write and returned
37
- `isolationProbe: "denied"`. The reviewer remains fail-closed: inability to prove isolation
38
- records `unverified` and blocks acceptance.
55
+ Not claimed here:
56
+
57
+ - no final release publish;
58
+ - no final task audit beyond the recorded subtask evidence;
59
+ - no new real-Codex isolation probe beyond the existing fail-closed strict-reviewer
60
+ implementation and its automated coverage.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "codex-workflow-v2",
3
- "version": "2.0.0-alpha.4",
3
+ "version": "2.0.0-alpha.6.1",
4
4
  "description": "Requirements-first Codex development workflow with local state and explicit Git ownership.",
5
5
  "repository": {
6
6
  "type": "git",
@@ -40,7 +40,7 @@
40
40
  "clean": "node --eval \"import('node:fs').then(({rmSync}) => { rmSync('dist', {recursive:true, force:true}); rmSync('.test-dist', {recursive:true, force:true}); })\"",
41
41
  "build": "npm run clean && tsc -p tsconfig.build.json && node scripts/mark-cli-executable.mjs",
42
42
  "typecheck": "tsc -p tsconfig.json --noEmit",
43
- "test": "npm run build && tsc -p tsconfig.test.json && node --test .test-dist/tests/*.test.js",
43
+ "test": "npm run build && tsc -p tsconfig.test.json && node --test --test-concurrency=1 --test-force-exit .test-dist/tests/*.test.js",
44
44
  "validate": "npm run typecheck && npm test",
45
45
  "pack:check": "npm run build && npm pack --dry-run",
46
46
  "smoke:downstream": "npm run build && node scripts/downstream-smoke.mjs",
@@ -8,13 +8,159 @@ Run:
8
8
  codex-workflow gateway handshake --repo <git-root>
9
9
  ```
10
10
 
11
- Require package name `codex-workflow-v2`, protocol version `1`, state
12
- schema version `2`, and the capabilities needed for the requested operation. Task execution
13
- that may cross a Project Knowledge Map revision requires `task-knowledge-rebind-v1`.
14
- Milestone final acceptance requires `milestone-human-final-gate-v1`.
15
- Autonomous approval requires `delegated-approval-v1`.
11
+ Require:
12
+
13
+ - package name `codex-workflow-v2`
14
+ - protocol version `1`
15
+ - state schema version `2`
16
+ - the capabilities needed for the requested operation
17
+
18
+ Current capability set:
19
+
20
+ - `project-memory-v1`
21
+ - `graph-binding-v1`
22
+ - `local-state-v1`
23
+ - `milestone-lifecycle-v1`
24
+ - `milestone-human-final-gate-v1`
25
+ - `delegated-approval-v1`
26
+ - `task-knowledge-rebind-v1`
27
+ - `task-context-refresh-v1`
28
+ - `corrective-plan-audit-v1`
29
+ - `safe-update-preflight-v1`
30
+ - `strict-reviewer-v1`
31
+ - `legacy-snapshot-v1`
32
+ - `plan-risk-audit-sidecar-v1`
33
+ - `step-strict-review-sidecar-v1`
34
+ - `step-remediation-circuit-breaker-sidecar-v1`
35
+ - `milestone-scope-change-sidecar-v1`
36
+ - `milestone-membership-integrity-v1`
37
+ - `task-c1-handoff-sidecar-v1`
38
+ - `semantic-plan-risk-audit-v2`
39
+ - `guarded-remediation-hard-stop-v1`
40
+ - `milestone-reverse-membership-integrity-v1`
41
+ - `task-c1-handoff-bundle-v2`
42
+ - `alpha6-adoption-posture-v1`
43
+
44
+ Protocol `1` and schema `2` remain valid only because alpha.6 is additive. The gateway must
45
+ not claim compatibility if canonical entity shapes or non-additive command semantics change.
46
+
47
+ ## Alpha.6 adoption posture
48
+
49
+ For an existing schema 2 project without alpha.6 posture, repository-level `next` blocks
50
+ execution behind adoption:
51
+
52
+ - `action: "state adoption-apply"` when the repository is already at a safe boundary
53
+ - `action: "restore safe boundary, then state adoption-prepare"` otherwise
54
+
55
+ Use:
16
56
 
17
- ## Milestone Human Gate
57
+ ```text
58
+ codex-workflow state adoption-prepare --repo <git-root>
59
+ codex-workflow state adoption-apply --repo <git-root> \
60
+ --actor <HUMAN-ACTOR> --confirmation-code <ADA-CODE>
61
+ ```
62
+
63
+ The confirmation is bound to project identity, package version, protocol version, schema
64
+ version, canonical entity summaries, and the current sidecar baseline hash. Adoption is not
65
+ `state migrate`.
66
+
67
+ ## Worker Step completion and strict Step Review
68
+
69
+ `task run` dispatches one Step and returns its writer token and Worker envelope. The Worker
70
+ must leave all changes uncommitted and must not stage, commit, amend, reset, rebase, or
71
+ modify Git history.
72
+
73
+ While that Step is `in_progress`, repository-level `next` normally returns
74
+ `action: "task step-complete"`, the exact `stepId`, and a `commitPolicy` declaring
75
+ `workflow-core` ownership. The coordinator invokes that transition with the current revision
76
+ and writer token. Core then runs configured checks, validates `allowedWrites`, stages the
77
+ changes, creates the atomic commit, and records evidence.
78
+
79
+ If the current Plan Risk Audit marks that Step for strict review, the commit is still
80
+ workflow-owned, but `next` then returns `action: "task step-review"` with the same `stepId`
81
+ and the exact `completionCommit`. Canonical Step completion remains blocked until the strict
82
+ review and reviewer attestation sidecars verify against that exact commit.
83
+
84
+ An unrecorded commit is Git history drift. Stop instead of adding another commit or editing
85
+ workflow state manually; recovery remains coordinator-controlled.
86
+
87
+ ## Plan Risk Audit and remediation breaker
88
+
89
+ Before `task authorize`, every new alpha.6 Task requires:
90
+
91
+ ```text
92
+ codex-workflow task plan-risk-audit --repo <git-root> \
93
+ --id <TASK-ID> --expected-revision <REVISION> --file <audit.json>
94
+ ```
95
+
96
+ The audit must classify every current Step exactly once, name distinct planner/auditor
97
+ actors, and bind guarded failure modes to exact Step checks. Use `decision=approved` for an
98
+ unguarded Plan. Missing, stale, `split-required`, or `stop-escalate` evidence blocks
99
+ authorization.
100
+
101
+ For guarded remediation, `next.correctivePlanGate` or the runtime gate blocks a third
102
+ ordinary retry on the same guarded Step until a current corrective decision exists. Record it
103
+ with:
104
+
105
+ ```text
106
+ codex-workflow task corrective-decision --repo <git-root> \
107
+ --id <TASK-ID> --step <STEP-ID> --expected-revision <REVISION> --file <decision.json>
108
+ ```
109
+
110
+ Only `continue-fix` permits bounded continuation. `replan-required`, `split-required`, and
111
+ `stop-escalate` are stop or redirection decisions. If the third corrective review fails, a
112
+ fourth run is prohibited; only split or stop may be recorded.
113
+
114
+ ## Context refresh
115
+
116
+ Use `task context-refresh` only when the same `next` response exposes `contextRefresh` for the
117
+ exact grant. Pass Task revision, map revision, delegate actor, and grant ID. The composite
118
+ operation is restricted to content-hash-only drift and records the ordinary delegated map and
119
+ Task authorization evidence. Any semantic map change remains on the normal visible path.
120
+
121
+ Before updating the installed package, run `update preflight`. Continue only for `safe=true`.
122
+
123
+ Alpha.6.1 adds one compatibility exception before package update: an exact alpha.6 claimed-C1
124
+ pending strict review with stale Knowledge may use external `update rescue-preflight` followed
125
+ by its single `update rescue-review` action. The action must preserve the original lease and
126
+ prove its bound actor/token; `locks repair` is forbidden before this review.
127
+
128
+ ## C1 handoff
129
+
130
+ `C1` coordination is machine-bound and local. Use:
131
+
132
+ ```text
133
+ codex-workflow task handoff-prepare --repo <git-root> --id <TASK-ID> \
134
+ --expected-revision <REVISION> --actor <CURRENT-ACTOR> \
135
+ --target-actor <TARGET-ACTOR> --reason <TEXT> [--writer-token <TOKEN>] \
136
+ [--delegation-grant <GRANT>] [--expires-at <ISO-TIMESTAMP>]
137
+ codex-workflow task handoff-show --repo <git-root> --id <TASK-ID>
138
+ codex-workflow task claim --repo <git-root> --id <TASK-ID> \
139
+ --expected-revision <REVISION> --actor <TARGET-ACTOR> --claim-token <TOKEN> \
140
+ [--writer-token <WRITER-TOKEN>]
141
+ codex-workflow task handback-create --repo <git-root> --id <TASK-ID> \
142
+ --expected-revision <REVISION> --actor <CLAIMANT> --reason <TEXT> \
143
+ --recommended-next <TEXT> [--limitation <TEXT>] [--writer-token <TOKEN>]
144
+ ```
145
+
146
+ While a handoff is pending, `next` blocks the previous action behind `task claim`. While
147
+ claimed, only the claimant may mutate the Task, and lease-bound mutations must present the
148
+ bound writer token. Milestone-linked Tasks must be claimed before start, and handback is
149
+ terminal and evidence-bound. No thread id is required or accepted as authority.
150
+
151
+ ## Milestone scope change and human gate
152
+
153
+ After the initial empty planning posture, Milestone scope updates use:
154
+
155
+ ```text
156
+ codex-workflow milestone scope-change-prepare --repo <git-root> \
157
+ --id <MS-ID> --expected-revision <REVISION> --actor <HUMAN-ACTOR> --file <plan.json>
158
+ codex-workflow milestone scope-change-apply --repo <git-root> \
159
+ --id <MS-ID> --expected-revision <REVISION> --actor <HUMAN-ACTOR> \
160
+ --confirmation-code <MSC-CODE> --file <plan.json>
161
+ ```
162
+
163
+ This path is human-only. Delegated approval never authorizes it.
18
164
 
19
165
  At `awaiting_final_acceptance`, `next` returns `requiredHumanGate` with kind
20
166
  `milestone_final_acceptance`, Milestone ID, revision, Plan/Result/evidence hashes, validated
@@ -42,6 +188,9 @@ as `--delegation-grant`. The resulting authorization event records the grant and
42
188
  For `milestone.final_accept`, also pass the current `MSA-*` code; the existing grant replaces
43
189
  the later-message requirement, not the state binding.
44
190
 
191
+ Delegated approval does not cover adoption apply, Milestone scope change, or any other new
192
+ human-only alpha.6 action.
193
+
45
194
  ## Graph Refresh Request
46
195
 
47
196
  The package returns:
@@ -38,6 +38,10 @@ classifications, hashes, gaps, conflicts, and approval evidence.
38
38
 
39
39
  Do not create a memory directory or write project files during scan.
40
40
 
41
+ When `next` exposes an exact delegated `contextRefresh`, use `task context-refresh` only for
42
+ the returned Task/map revisions, actor, and grant. Never use it when the source set,
43
+ classification, authority, gaps, or conflicts changed.
44
+
41
45
  ## Product Or Workflow Graph Refresh
42
46
 
43
47
  1. Run `graph refresh-request --kind product|workflow --mode moderate`.
@@ -57,8 +61,12 @@ independently blocks the workflow.
57
61
 
58
62
  - Scope Lead: architecture and broad search only.
59
63
  - Technical Planner: architecture, search, and trace evidence.
60
- - Worker: targeted search, trace, and snippets for its Step.
64
+ - Worker: targeted search, trace, and snippets for its Step. It leaves all file changes
65
+ uncommitted and never stages or mutates Git history; the coordinator invokes the exact
66
+ `task step-complete` returned by `next`, and core owns checks, commit creation, and evidence.
61
67
  - Delivery Coordinator: list, status, index, detect, and bind lifecycle.
68
+ - A Milestone Delivery Coordinator creates a dedicated user-visible Task chat for every
69
+ required Task and keeps implementation out of the Milestone chat.
62
70
  - Independent Reviewer: receives recorded evidence and confirms critical
63
71
  claims against files, Git, and tests.
64
72
 
@@ -95,6 +103,20 @@ option is returned, follow the ordinary human-gate rule above. Knowledge Map app
95
103
  delegable only through an explicit project-scoped `project_memory.approve` permission. Scope
96
104
  changes, grant issuance, and grant expansion are never delegated by `delegated-approval-v1`.
97
105
 
106
+ After two failed Task reviews, follow `next.correctivePlanGate`: obtain a distinct read-only
107
+ corrective Auditor result and pass it through `--corrective-audit-file`. Do not continue for
108
+ replan, split, or stop decisions.
109
+
110
+ Before an npm package update, run the project-local `update preflight` and stop unless it
111
+ returns `safe=true` with a clean checkout, no running Step, and no active writer lease.
112
+
113
+ For a project still pinned exactly to `2.0.0-alpha.6` with one claimed-C1 pending strict review
114
+ blocked by stale Project Knowledge, do not update the dependency and do not repair the lease.
115
+ Resolve the exact external `2.0.0-alpha.6.1` runner, run its read-only `update rescue-preflight`,
116
+ and continue only for `eligible=true` with the single returned `update rescue-review` action.
117
+ Use the exact claimant and original bound writer token without printing the token. Stop on any
118
+ binding mismatch or additional blocker.
119
+
98
120
  ## Stop Conditions
99
121
 
100
122
  - Dependency version is missing, ranged, or differs from the installed package.
@@ -3,5 +3,8 @@
3
3
  The default mode uses a dedicated task branch in the current clean checkout. The core
4
4
  does not create or remove worktrees. An externally supplied worktree or clone must already
5
5
  be on a dedicated non-base branch; its provider owns merge and cleanup. Every completed
6
- Step becomes one commit with Task and Step trailers. Unexpected changed paths block the
7
- commit. Base advancement invalidates validation and final acceptance before merge.
6
+ Step becomes one commit with Task and Step trailers. The Worker leaves its changes
7
+ uncommitted; `task step-complete` owns configured checks, staging, commit creation, and Step
8
+ evidence. A Worker must not run `git add`, `git commit`, amend, reset, rebase, or otherwise
9
+ change Git history. Unexpected changed paths or unrecorded commits block Step completion.
10
+ Base advancement invalidates validation and final acceptance before merge.
@@ -6,6 +6,21 @@ to the task commit and Brief, Plan, and evidence hashes. Final acceptance is a s
6
6
  human event bound to Result, evidence, and commit. Locks expire only diagnostically;
7
7
  removing a stale lock is always an explicit repair operation.
8
8
 
9
+ Alpha.6 keeps canonical entity JSON unchanged at `stateSchemaVersion: 2` and adds lifecycle
10
+ evidence through sidecars. `protocolVersion: 1` remains valid only because the alpha.6
11
+ surface is additive and capability-advertised.
12
+
13
+ Before execution authorization, every alpha.6 Task must have a current Plan Risk Audit bound
14
+ to the current Brief, Plan, Knowledge Map, and exact Step set. The audit is required even when
15
+ all Steps are unguarded, must name distinct planner/auditor actors, and must bind guarded
16
+ failure modes to exact Step checks. Missing, stale, inconsistent, `split-required`, or
17
+ `stop-escalate` evidence blocks authorization.
18
+
19
+ If the current Plan Risk Audit marks a Step for strict review, `task step-complete` still
20
+ creates the workflow-owned commit but keeps the Step non-terminal. Repository `next` routes to
21
+ `task step-review` until a valid strict review and reviewer attestation bind to that exact
22
+ commit.
23
+
9
24
  Human approval remains the default. A user may instead issue a time-bound delegation grant
10
25
  after confirming a deterministic `DGA-*` code bound to the project and exact policy hash.
11
26
  The policy names a distinct principal and delegate, a project/Milestone/Task scope, and an
@@ -21,6 +36,12 @@ bindings, supersedes execution authorization, and returns the Task to
21
36
  `awaiting_execution_authorization`. It cannot run while a Step is `in_progress` or while the
22
37
  Task is `blocked`; unrelated blocks must be resolved through their owning transition.
23
38
 
39
+ For alpha.6 guarded remediation, two ordinary remediation attempts are allowed. A third
40
+ ordinary retry is blocked until a current corrective decision exists for the same Step and
41
+ Plan binding. `continue-fix` allows bounded continuation; `replan-required`,
42
+ `split-required`, and `stop-escalate` stop ordinary execution. A failed third corrective
43
+ attempt is a hard stop: no fourth run or new continue/replan decision is accepted.
44
+
24
45
  Milestone authorization is bound to its Plan and membership revision. Plan amendments
25
46
  supersede authorization. Milestone validation and acceptance are bound to the current base
26
47
  HEAD. In `awaiting_final_acceptance`, `next` returns a state-bound human gate. The agent must
@@ -34,6 +55,21 @@ but the acceptance command still requires the current `MSA-*` code so the use re
34
55
  to the validated revision, hashes, and HEAD. Grant issuance itself always remains a prior
35
56
  human turn boundary.
36
57
 
58
+ After the initial empty planning posture, Milestone scope updates no longer use ordinary
59
+ `milestone plan-set`. They must go through `milestone scope-change-prepare` and
60
+ `milestone scope-change-apply`, which journal `state.json`, `plan.json`, and
61
+ `scope-change-events.jsonl` together and remain human-only. Membership integrity is validated
62
+ before scheduling, Task start, Milestone validation, scope change, and repository `next`.
63
+ The same guard scans in reverse and blocks every live Task whose `milestoneId` is absent from
64
+ the Milestone's required/waived/cancelled classification.
65
+
66
+ `C1` coordination is machine-bound but local: `task handoff-prepare` returns a one-time claim
67
+ token and prompt bound to a stable handoff ID, revision, context hashes, Milestone positions,
68
+ delegate/grant, expected next action, and expiry. `task claim` validates those bindings and
69
+ activates claimant-only mutation; terminal `task handback-create` returns result, evidence,
70
+ review, knowledge, limitation, and recommended-next bindings. Milestone Tasks must be claimed
71
+ before start. No part of this contract requires or proves a physically separate Codex thread.
72
+
37
73
  Repository-level scheduling respects current Milestone membership. An unstarted linked Task
38
74
  is eligible only for an `active` Milestone with `required` disposition. Historical unstarted
39
75
  Tasks from `waived`, `cancelled`, accepted, or cancelled Milestone paths cannot shadow the
@@ -1,18 +1,45 @@
1
1
  # Validation and Review
2
2
 
3
- Configured Step checks must pass before the Step commit is recorded. Submission produces
3
+ The Worker leaves Step changes uncommitted. `task step-complete` runs the configured checks,
4
+ creates the atomic Step commit, and records its evidence. Manual Worker commits are rejected
5
+ as unrecorded history. Submission produces
4
6
  evidence for the exact task-branch head. Independent review is read-only and produces a
5
7
  version-bound result. Any later commit or change to Brief, Plan, or evidence makes that
6
8
  review stale. The user grants final acceptance only after a passing fresh review and a
7
9
  human-readable Result.
8
10
 
11
+ High-risk evidence is failure-oriented. Migration acceptance includes a populated forward
12
+ upgrade, concurrent state includes deterministic races, restart/replay claims include crash
13
+ windows, and provider integrations include failure injection plus hidden-default checks.
14
+ Happy-path green tests do not replace this evidence.
15
+
16
+ After two failed independent reviews, another corrective Plan requires a distinct Auditor.
17
+ The Auditor covers every latest finding and records `continue-fix`, `replan-required`,
18
+ `split-required`, or `stop-escalate`. Only `continue-fix` may be passed to `task plan-set`
19
+ through `--corrective-audit-file`; the other decisions stop implementation.
20
+
9
21
  The strict path is `task review-launch`. It starts an ephemeral Codex process with user
10
22
  configuration and rules ignored, a read-only sandbox, structured output, and an attempted
11
23
  write probe. The core seals repository HEAD, status, and content before/after the process.
12
24
  Any process error, malformed output, successful write, or changed seal records an
13
25
  `unverified` review and blocks Result creation and final acceptance.
14
26
 
27
+ Alpha.6 adds a Step-level strict path for high-risk work. If the current Plan Risk Audit marks
28
+ the completed Step for strict review, `next` routes to `task step-review` instead of
29
+ advancing ordinary execution. The workflow validates:
30
+
31
+ - the exact completion commit
32
+ - the current Plan hash
33
+ - the Step definition hash
34
+ - the review sidecar chain in `step-review-events.jsonl`
35
+ - the reviewer attestation chain in `reviewer-attestations.jsonl`
36
+
37
+ Any stale, malformed, unverified, or wrong-commit evidence fails closed and keeps the Step out
38
+ of canonical `completed` status.
39
+
15
40
  Milestone validation similarly binds Result and evidence to the clean base HEAD. Its final
16
41
  acceptance is a separate turn: `next` emits a confirmation code bound to the current
17
42
  revision, Plan, Result, evidence, and HEAD; the coordinator shows it and stops. A later user
18
43
  response must explicitly approve that exact code before the CLI transition is invoked.
44
+ With a matching delegated option, the exact delegate may use the current code in the same
45
+ turn, but the authorization event must keep the delegate actor and principal/grant evidence.
@@ -14,4 +14,15 @@ Own state transitions, dispatch envelopes, evidence collection, and recovery gui
14
14
  - Accept a Milestone only after a later user message explicitly approves that exact
15
15
  confirmation code. Do not infer approval from a request to validate, finish, or continue.
16
16
  - Dispatch one Worker at a time for a concrete Step.
17
+ - A Milestone coordinator creates one dedicated user-visible Codex Task chat for each required
18
+ Task. The Milestone chat owns ordering, exact delegated approvals, merge observation,
19
+ validation, and final acceptance; it does not accumulate implementation for every Task.
20
+ - Before authorizing a high-risk Plan, require the Technical Planner's migration/concurrency/
21
+ restart/crash/provider risk review and failure-specific checks.
22
+ - After a second failed independent Task review, require a separate corrective Plan Auditor
23
+ and pass its evidence through `--corrective-audit-file`. Continue only for
24
+ `decision=continue-fix`; replan/split/stop decisions return to the coordinator or user.
25
+ - Use `task context-refresh` only when `next.contextRefresh` offers the exact delegated,
26
+ content-only option. Classification, authority, source-set, gap, or conflict changes still
27
+ require the ordinary visible Knowledge Map flow.
17
28
  - Do not make product-scope decisions or implement production changes.
@@ -7,4 +7,7 @@ Compare requirements, acceptance, Plan, task-branch diff, checks, and generated
7
7
  - Operate read-only and do not fix findings.
8
8
  - Mark the review `unverified` when read-only isolation or required evidence is unavailable.
9
9
  - A failed review must contain actionable findings; a passed review contains none.
10
+ - For migrations, concurrency, restart/replay, crash recovery, and external providers, reject
11
+ green happy-path evidence that omits populated upgrades, deterministic races, restart/crash
12
+ windows, or provider failure/default behavior required by the approved Plan.
10
13
  - Do not grant final acceptance on behalf of the user.