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.
- package/README.md +86 -10
- package/dist/src/alpha6/adoption.d.ts +55 -0
- package/dist/src/alpha6/adoption.js +920 -0
- package/dist/src/alpha6/adoption.js.map +1 -0
- package/dist/src/alpha6/handoff.d.ts +39 -0
- package/dist/src/alpha6/handoff.js +975 -0
- package/dist/src/alpha6/handoff.js.map +1 -0
- package/dist/src/alpha6/journal.d.ts +30 -0
- package/dist/src/alpha6/journal.js +369 -0
- package/dist/src/alpha6/journal.js.map +1 -0
- package/dist/src/alpha6/milestone.d.ts +49 -0
- package/dist/src/alpha6/milestone.js +1049 -0
- package/dist/src/alpha6/milestone.js.map +1 -0
- package/dist/src/alpha6/plan-risk.d.ts +32 -0
- package/dist/src/alpha6/plan-risk.js +847 -0
- package/dist/src/alpha6/plan-risk.js.map +1 -0
- package/dist/src/alpha6/remediation.d.ts +20 -0
- package/dist/src/alpha6/remediation.js +748 -0
- package/dist/src/alpha6/remediation.js.map +1 -0
- package/dist/src/alpha6/review.d.ts +46 -0
- package/dist/src/alpha6/review.js +785 -0
- package/dist/src/alpha6/review.js.map +1 -0
- package/dist/src/alpha6/store-sidecars.d.ts +35 -0
- package/dist/src/alpha6/store-sidecars.js +281 -0
- package/dist/src/alpha6/store-sidecars.js.map +1 -0
- package/dist/src/cli.js +88 -19
- package/dist/src/cli.js.map +1 -1
- package/dist/src/contracts.d.ts +259 -0
- package/dist/src/git.js +2 -1
- package/dist/src/git.js.map +1 -1
- package/dist/src/index.d.ts +2 -0
- package/dist/src/reviewer.d.ts +6 -1
- package/dist/src/reviewer.js +145 -32
- package/dist/src/reviewer.js.map +1 -1
- package/dist/src/state/lock.d.ts +1 -0
- package/dist/src/state/lock.js +7 -1
- package/dist/src/state/lock.js.map +1 -1
- package/dist/src/state/store.d.ts +39 -1
- package/dist/src/state/store.js +127 -1
- package/dist/src/state/store.js.map +1 -1
- package/dist/src/version.d.ts +1 -1
- package/dist/src/version.js +1 -1
- package/dist/src/workflow.d.ts +78 -8
- package/dist/src/workflow.js +1312 -74
- package/dist/src/workflow.js.map +1 -1
- package/docs/autonomy-guardrails.md +143 -0
- package/docs/decisions.md +23 -0
- package/docs/delegated-approval.md +30 -5
- package/docs/development-flow.md +40 -1
- package/docs/pdf/codex-workflow-v2-architecture-ru.pdf +155 -136
- package/docs/pdf/codex-workflow-v2-chat-only-guide-ru.pdf +236 -223
- package/docs/pdf/codex-workflow-v2-technical-reference-ru.pdf +225 -206
- package/docs/project-memory.md +7 -0
- package/docs/release.md +7 -0
- package/docs/updating-existing-project.md +53 -5
- package/docs/validation-report.md +47 -34
- package/package.json +1 -1
- package/plugins/codex-workflow-gateway/references/protocol.md +150 -6
- package/plugins/codex-workflow-gateway/skills/codex-workflow-gateway/SKILL.md +16 -1
- package/references/git-policy.md +5 -2
- package/references/state-machine.md +36 -0
- package/references/validation-and-review.md +28 -1
- package/roles/delivery-coordinator.md +11 -0
- package/roles/independent-reviewer.md +3 -0
- package/roles/technical-planner.md +7 -0
- package/roles/worker.md +4 -0
- package/schemas/adoption-posture-event.schema.json +129 -0
- package/schemas/corrective-decision-event.schema.json +55 -0
- package/schemas/corrective-plan-audit.schema.json +20 -0
- package/schemas/milestone-scope-change-event.schema.json +68 -0
- package/schemas/milestone-transaction-journal.schema.json +95 -0
- package/schemas/plan-risk-audit-event.schema.json +90 -0
- package/schemas/remediation-event.schema.json +53 -0
- package/schemas/reviewer-attestation-event.schema.json +49 -0
- package/schemas/step-review-event.schema.json +74 -0
- package/schemas/task-handoff-event.schema.json +116 -0
package/docs/project-memory.md
CHANGED
|
@@ -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 и
|
|
37
|
+
До изменений запусти project-local gateway handshake, doctor, status, next и
|
|
38
|
+
read-only `update preflight`;
|
|
37
39
|
зафиксируй текущую версию, protocolVersion, stateSchemaVersion, projectId,
|
|
38
|
-
активные сущности и наличие writer lease.
|
|
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.
|
|
3
|
+
Release candidate `2.0.0-alpha.6` was validated through 2026-08-14 with Node.js 24.17.0.
|
|
4
4
|
|
|
5
|
-
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
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
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
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
|
@@ -8,13 +8,154 @@ Run:
|
|
|
8
8
|
codex-workflow gateway handshake --repo <git-root>
|
|
9
9
|
```
|
|
10
10
|
|
|
11
|
-
Require
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
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
|
-
|
|
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.
|
package/references/git-policy.md
CHANGED
|
@@ -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.
|
|
7
|
-
|
|
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
|
-
|
|
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.
|