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

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 (76) hide show
  1. package/README.md +86 -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 +88 -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/workflow.d.ts +78 -8
  44. package/dist/src/workflow.js +1312 -74
  45. package/dist/src/workflow.js.map +1 -1
  46. package/docs/autonomy-guardrails.md +143 -0
  47. package/docs/decisions.md +23 -0
  48. package/docs/delegated-approval.md +30 -5
  49. package/docs/development-flow.md +40 -1
  50. package/docs/pdf/codex-workflow-v2-architecture-ru.pdf +155 -136
  51. package/docs/pdf/codex-workflow-v2-chat-only-guide-ru.pdf +236 -223
  52. package/docs/pdf/codex-workflow-v2-technical-reference-ru.pdf +225 -206
  53. package/docs/project-memory.md +7 -0
  54. package/docs/release.md +7 -0
  55. package/docs/updating-existing-project.md +53 -5
  56. package/docs/validation-report.md +47 -34
  57. package/package.json +1 -1
  58. package/plugins/codex-workflow-gateway/references/protocol.md +150 -6
  59. package/plugins/codex-workflow-gateway/skills/codex-workflow-gateway/SKILL.md +16 -1
  60. package/references/git-policy.md +5 -2
  61. package/references/state-machine.md +36 -0
  62. package/references/validation-and-review.md +28 -1
  63. package/roles/delivery-coordinator.md +11 -0
  64. package/roles/independent-reviewer.md +3 -0
  65. package/roles/technical-planner.md +7 -0
  66. package/roles/worker.md +4 -0
  67. package/schemas/adoption-posture-event.schema.json +129 -0
  68. package/schemas/corrective-decision-event.schema.json +55 -0
  69. package/schemas/corrective-plan-audit.schema.json +20 -0
  70. package/schemas/milestone-scope-change-event.schema.json +68 -0
  71. package/schemas/milestone-transaction-journal.schema.json +95 -0
  72. package/schemas/plan-risk-audit-event.schema.json +90 -0
  73. package/schemas/remediation-event.schema.json +53 -0
  74. package/schemas/reviewer-attestation-event.schema.json +49 -0
  75. package/schemas/step-review-event.schema.json +74 -0
  76. 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,8 @@ gateway, но не удаляет и не пересоздаёт это сост
19
19
  Никогда не разрешайте агенту вручную редактировать, переносить или удалять внешний state.
20
20
  Команда миграции нужна только тогда, когда документация новой версии прямо сообщает о новой
21
21
  state schema. Совпадение `stateSchemaVersion` до и после обновления означает, что миграция не
22
- нужна.
22
+ нужна. Для alpha.6 при `stateSchemaVersion: 2` применяется не migration, а sidecar-only
23
+ adoption posture.
23
24
 
24
25
  ## 1. Подготовьте отдельный чат обновления
25
26
 
@@ -33,10 +34,12 @@ Codex и откройте в нужном проекте отдельный ча
33
34
  из npm: https://www.npmjs.com/package/codex-workflow-v2.
34
35
 
35
36
  Все команды выполняешь ты. Сначала прочитай AGENTS.md и определи Git root.
36
- До изменений запусти project-local gateway handshake, doctor, status и next;
37
+ До изменений запусти project-local gateway handshake, doctor, status, next и
38
+ read-only `update preflight`;
37
39
  зафиксируй текущую версию, protocolVersion, stateSchemaVersion, projectId,
38
- активные сущности и наличие writer lease. Если Worker сейчас выполняется,
39
- остановись без обновления.
40
+ активные сущности и наличие writer lease. Продолжай только если preflight
41
+ вернул safe=true: checkout чистый, running Step и active writer lease отсутствуют.
42
+ Иначе остановись без обновления и покажи blockers.
40
43
 
41
44
  Обнови только точную npm-зависимость и lock-файл, без диапазона версий.
42
45
  Не удаляй и не редактируй вручную $CODEX_HOME/workflow-state/v2.
@@ -62,6 +65,9 @@ plugin за пределами workspace. Это ожидаемая границ
62
65
  5. `projectId` совпадает со значением до обновления.
63
66
  6. Существующие Task/Milestone ID, revisions и terminal statuses сохранились.
64
67
  7. Персональный gateway обновлён из установленного пакета.
68
+ 8. `update preflight` до изменения подтвердил чистую lifecycle-границу.
69
+ 9. Для alpha.6 существующий schema 2 проект либо уже имеет `adoption-posture.jsonl`,
70
+ либо `next`/`status` требуют `state adoption-prepare` и затем `state adoption-apply`.
65
71
 
66
72
  Изменение `projectId`, исчезновение сущностей или ошибка unsupported state schema — причина
67
73
  остановиться. Не соглашайтесь на «починку» удалением state. Агент должен вернуть dependency к
@@ -92,6 +98,42 @@ handshake, doctor, status и next. Подтверди точную declared/inst
92
98
  нужно выполнить `scan/reconcile`, показать пользователю изменения классификации и получить
93
99
  approval, если он требуется.
94
100
 
101
+ ## 3.0. Alpha.6 adoption для существующего schema 2 проекта
102
+
103
+ Если проект уже вёлся на alpha.5 или другой schema 2 версии без alpha.6 posture, новый runtime
104
+ не разрешит execution-переходы, пока не будет записан adoption sidecar. Это нормальное
105
+ fail-closed поведение, а не повреждение state.
106
+
107
+ Порядок:
108
+
109
+ 1. `update preflight --repo .`
110
+ 2. `state adoption-prepare --repo .`
111
+ 3. Проверить returned baseline и `ADA-*` confirmation code
112
+ 4. `state adoption-apply --repo . --actor <human-actor> --confirmation-code <ADA-CODE>`
113
+
114
+ Граница должна быть безопасной:
115
+
116
+ - checkout чистый;
117
+ - нет `in_progress` Step;
118
+ - нет active writer lease;
119
+ - stale writer lease сначала чинится обычным repair-путём.
120
+
121
+ Alpha.6 adoption сохраняет:
122
+
123
+ - terminal Milestones со статусом `accepted` или `cancelled`;
124
+ - terminal Tasks со статусом `merged` или `cancelled`;
125
+ - completed и skipped Steps в активных Tasks вместе с их evidence.
126
+
127
+ Alpha.6 adoption не делает:
128
+
129
+ - не переписывает canonical entity JSON;
130
+ - не переоткрывает terminal-сущности;
131
+ - не прогоняет заново уже completed legacy Steps;
132
+ - не использует `state migrate`.
133
+
134
+ После adoption remaining legacy scope должен получить bootstrap Plan Risk Audit только для
135
+ оставшихся non-`completed` и non-`skipped` Step.
136
+
95
137
  ## 3.1. При необходимости включите delegated approval
96
138
 
97
139
  Delegated approval не включается автоматически после обновления. Существующие авторизации и
@@ -147,7 +189,9 @@ Revocation запрещает будущие использования, но н
147
189
  Codex-процесса. Любой процесс с доступом к локальному state и CLI может заявить строку
148
190
  delegate. Поэтому project-wide grant должен быть короткоживущим, а секреты, платежи, реальные
149
191
  торговые операции и иные необратимые действия требуют отдельных технических ограничений и не
150
- должны полагаться только на delegated approval.
192
+ должны полагаться только на delegated approval. Alpha.6 не расширяет allow-list transitions:
193
+ grant не даёт authority на adoption apply, Milestone scope change или другие новые
194
+ human-only guardrails.
151
195
 
152
196
  ## 3.2. Запустите delegate в новом чате
153
197
 
@@ -181,6 +225,10 @@ NN - Standalone delegated task
181
225
  После завершения автономного окна попросите отдельный контрольный чат показать
182
226
  `delegation list`, использованные authorization events и отозвать ненужный широкий grant.
183
227
 
228
+ Для Milestone delegate отдельный Task-чат обязателен для каждой required Task. Это сохраняет
229
+ пользовательский audit trail и не позволяет одному длинному Milestone-чату накапливать
230
+ реализацию, compaction и review всех Tasks.
231
+
184
232
  ## 4. Продолжите начатый Milestone или создайте следующий
185
233
 
186
234
  Terminal Milestone со статусом `accepted` остаётся закрытым. Для следующего результата нужно
@@ -1,38 +1,51 @@
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` was validated through 2026-08-14 with Node.js 24.17.0.
4
4
 
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.
5
+ - `npm run typecheck`, `npm run build`, `npm test`, `npm run validate`, `npm run plugin:check`,
6
+ `npm run smoke:downstream`, `npm run release:check`, and `npm run pack:check` passed in the
7
+ task evidence recorded for TASK-002.
8
+ - The final sequential full suite passed `81/81` on 2026-08-14.
9
+ - Plan Risk Audit coverage includes the combined `plan-set --risk-audit-file` path, atomic
10
+ rejection before Task/Plan acceptance, distinct planner/auditor identities, exact current
11
+ Step-set equality, concrete failure modes, executable evidence binding, coupled
12
+ migration/recovery rationale, blocking split/stop decisions, and adoption-aware
13
+ remaining-scope bootstrap handling.
14
+ - Strict high-risk Step Review coverage includes workflow-owned completion commits,
15
+ `task step-review` routing, commit-bound reviewer attestation, and fail-closed rejection of
16
+ stale, malformed, unverified, and wrong-commit review evidence.
17
+ - Guarded remediation coverage includes the per-Step circuit breaker: two ordinary retries
18
+ allowed, third gated by bounded `continue-fix`, a hard stop after a third failed corrective
19
+ review, and stop/redirection handling for `split-required` and `stop-escalate`.
20
+ - Milestone coverage includes human-only scope-change prepare/apply, journaled recovery of
21
+ `state.json`, `plan.json`, and `scope-change-events.jsonl`, plus membership-integrity
22
+ blocking for stale or contradictory Milestone/Task state, including reverse detection of a
23
+ live linked Task missing from required/waived/cancelled membership.
24
+ - `C1` coordination coverage includes the full prepared bundle, one-time and expiring claim
25
+ token, Task/Plan/Knowledge/Milestone bindings, exact expected-next prompt, optional grant,
26
+ target-only claim, claimant-only mutation, mandatory claim before Milestone Task start,
27
+ lease-token binding, and terminal evidence-bound handback.
28
+ - Adoption coverage includes sidecar-only `state adoption-prepare` and `state adoption-apply`,
29
+ automatic posture initialization for fresh alpha.6 projects, preservation of terminal
30
+ Milestones and Tasks, preservation of completed and skipped legacy Steps, and execution
31
+ blocking until posture is present.
32
+ - Compatibility checks passed for `protocolVersion: 1`, `STATE_SCHEMA_VERSION: 2`, unchanged
33
+ canonical Task and Milestone shapes, and unchanged delegated transition allow-list.
34
+ - Gateway handshake coverage includes the alpha.6 capabilities:
35
+ `plan-risk-audit-sidecar-v1`, `step-strict-review-sidecar-v1`,
36
+ `step-remediation-circuit-breaker-sidecar-v1`, `milestone-scope-change-sidecar-v1`,
37
+ `milestone-membership-integrity-v1`, `task-c1-handoff-sidecar-v1`, and
38
+ `alpha6-adoption-posture-v1`, plus strengthened contracts advertised as
39
+ `semantic-plan-risk-audit-v2`, `guarded-remediation-hard-stop-v1`,
40
+ `milestone-reverse-membership-integrity-v1`, and `task-c1-handoff-bundle-v2`.
41
+ - npm dry-run packaging produced `codex-workflow-v2-2.0.0-alpha.6.tgz` with runtime, schemas,
42
+ references, docs, and plugin source. Downstream installation and the packaged CLI handshake
43
+ passed, and the install created none of `.codex`, `.tasks`, `.increments`, or
44
+ `.memory-bank` in the temporary project.
34
45
 
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.
46
+ Not claimed here:
47
+
48
+ - no final release publish;
49
+ - no final task audit beyond the recorded subtask evidence;
50
+ - no new real-Codex isolation probe beyond the existing fail-closed strict-reviewer
51
+ 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",
4
4
  "description": "Requirements-first Codex development workflow with local state and explicit Git ownership.",
5
5
  "repository": {
6
6
  "type": "git",
@@ -8,13 +8,154 @@ 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
+ ## C1 handoff
124
+
125
+ `C1` coordination is machine-bound and local. Use:
126
+
127
+ ```text
128
+ codex-workflow task handoff-prepare --repo <git-root> --id <TASK-ID> \
129
+ --expected-revision <REVISION> --actor <CURRENT-ACTOR> \
130
+ --target-actor <TARGET-ACTOR> --reason <TEXT> [--writer-token <TOKEN>] \
131
+ [--delegation-grant <GRANT>] [--expires-at <ISO-TIMESTAMP>]
132
+ codex-workflow task handoff-show --repo <git-root> --id <TASK-ID>
133
+ codex-workflow task claim --repo <git-root> --id <TASK-ID> \
134
+ --expected-revision <REVISION> --actor <TARGET-ACTOR> --claim-token <TOKEN> \
135
+ [--writer-token <WRITER-TOKEN>]
136
+ codex-workflow task handback-create --repo <git-root> --id <TASK-ID> \
137
+ --expected-revision <REVISION> --actor <CLAIMANT> --reason <TEXT> \
138
+ --recommended-next <TEXT> [--limitation <TEXT>] [--writer-token <TOKEN>]
139
+ ```
140
+
141
+ While a handoff is pending, `next` blocks the previous action behind `task claim`. While
142
+ claimed, only the claimant may mutate the Task, and lease-bound mutations must present the
143
+ bound writer token. Milestone-linked Tasks must be claimed before start, and handback is
144
+ terminal and evidence-bound. No thread id is required or accepted as authority.
145
+
146
+ ## Milestone scope change and human gate
147
+
148
+ After the initial empty planning posture, Milestone scope updates use:
149
+
150
+ ```text
151
+ codex-workflow milestone scope-change-prepare --repo <git-root> \
152
+ --id <MS-ID> --expected-revision <REVISION> --actor <HUMAN-ACTOR> --file <plan.json>
153
+ codex-workflow milestone scope-change-apply --repo <git-root> \
154
+ --id <MS-ID> --expected-revision <REVISION> --actor <HUMAN-ACTOR> \
155
+ --confirmation-code <MSC-CODE> --file <plan.json>
156
+ ```
157
+
158
+ This path is human-only. Delegated approval never authorizes it.
18
159
 
19
160
  At `awaiting_final_acceptance`, `next` returns `requiredHumanGate` with kind
20
161
  `milestone_final_acceptance`, Milestone ID, revision, Plan/Result/evidence hashes, validated
@@ -42,6 +183,9 @@ as `--delegation-grant`. The resulting authorization event records the grant and
42
183
  For `milestone.final_accept`, also pass the current `MSA-*` code; the existing grant replaces
43
184
  the later-message requirement, not the state binding.
44
185
 
186
+ Delegated approval does not cover adoption apply, Milestone scope change, or any other new
187
+ human-only alpha.6 action.
188
+
45
189
  ## Graph Refresh Request
46
190
 
47
191
  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,13 @@ 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
+
98
113
  ## Stop Conditions
99
114
 
100
115
  - 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.
@@ -6,5 +6,12 @@ Translate an approved Brief into an execution-ready Plan.
6
6
  - Declare `knowledgeImpact`, its reason, targets, and `graphUse`; do not hide missing knowledge as an implementation choice.
7
7
  - Every requirement must be covered by at least one `STEP-*`.
8
8
  - Each Step declares dependencies, outputs, allowed writes, forbidden scope, and checks.
9
+ - Perform a risk review before `plan-set`. A Plan that touches migrations, concurrent state,
10
+ restart/replay, crash recovery, or an external provider must include failure-specific checks
11
+ in the original Steps: populated forward upgrades, deterministic races, restart/crash
12
+ windows, and provider failure/default behavior as applicable.
13
+ - Split a Task when one acceptance slice would otherwise combine persistence migration,
14
+ recovery orchestration, and executable composition. Do not use arbitrary line/file limits;
15
+ split on independently verifiable failure boundaries.
9
16
  - Do not edit production files or silently expand the Brief.
10
17
  - Return unresolved semantic choices to the user through the Delivery Coordinator.
package/roles/worker.md CHANGED
@@ -7,4 +7,8 @@ Implement exactly one dispatched Step under its context envelope.
7
7
  - Read only declared inputs and repository context needed for the Step.
8
8
  - Write only `allowedWrites`; stop on required scope expansion.
9
9
  - Run the declared checks and report limitations honestly.
10
+ - Leave all Step changes uncommitted. Do not run `git add`, `git commit`, `git amend`,
11
+ reset, rebase, or another Git-history mutation. The coordinator invokes
12
+ `task step-complete`; Workflow core then runs the configured checks, creates the atomic
13
+ Step commit, and records its evidence.
10
14
  - Do not edit the Brief, Plan, acceptance, other Steps, workflow state, or Git history manually.