Skip to content

Commit c8e5a4f

Browse files
Cipher-85Cipher-85
committed
Bump Codex package to 0.4.6
1 parent 99481e8 commit c8e5a4f

5 files changed

Lines changed: 250 additions & 27 deletions

File tree

‎.agents/skills/handoff/SKILL.md‎

Lines changed: 88 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -33,25 +33,94 @@ pair for `$resume-from-handoff`.
3333

3434
## Phase 0: Review Gate
3535

36-
Before writing the final handoff or committing, review all files created or
37-
materially changed in this session.
38-
39-
1. Self-review each touched file for project rules, design gates, naming, test
40-
standards, and reporting integrity.
41-
2. Run an appropriate Codex review when available for substantial code,
42-
executable specs, cross-cutting docs, or milestone work. Use an
43-
adversarial/focused review only for major milestone deliverables or explicit
44-
user challenge language.
45-
3. Triage findings:
46-
- Agree and confident to fix: fix now, then verify.
47-
- Agree but out of scope: record in the handoff Deferred section with the
48-
finding quoted.
49-
- Disagree, uncertain, or scope-changing: stop and surface to the user.
50-
4. If fixes were applied, self-review the fix set. Run a second Codex review
51-
only for high-severity findings or cross-cutting executable changes.
52-
5. Cap review invocations at 3 unless the user explicitly approves more.
53-
54-
Proceed only when no finding is blocking on user input.
36+
Before rotating continuity files or committing, run this mandatory two-round
37+
gate over every file created or materially changed in this session. The gate can
38+
halt the skill: if triage requires user direction, stop before Phase 1 and do
39+
not rotate, commit, or push.
40+
41+
The review stays inside the current Codex session. A native cross-check is a
42+
distinct native Codex review pass performed by this session after setting aside
43+
its authoring conclusions and re-reading the deliverables with a reviewer lens.
44+
Never invoke `codex review`, `codex exec`, `codex-companion`, the Claude
45+
companion plugin, a subprocess reviewer, a subagent reviewer, or another model
46+
service. Do not create an external data-egress approval path for this gate.
47+
48+
### Pure Design/Process-Document Exemption
49+
50+
If the entire session changed only pure design/process-document content,
51+
self-review is sufficient and the native cross-check is skipped. This exemption
52+
covers instruction/rule files, skills, `AGENTS.md`, ADRs with no runtime impact,
53+
`design/gdd/**`, and memory files. Mixed code-and-document changes are not
54+
exempt. Executable specifications, CI configuration, tools, tests, public API
55+
contracts, and ADRs with runtime-behavioral requirements are not pure documents.
56+
57+
### Round 1
58+
59+
1. Self-review every touched file end-to-end, not just the diff. Check the
60+
applicable ADRs, GDDs, project rules, naming, test standards, design gates,
61+
verification claims, and recorded caveats.
62+
2. Unless the pure-document exemption applies, select exactly one native tier:
63+
- `STANDARD` is the default for routine session work: individual ADR
64+
amendments, tool / lint additions, tests, GDD system authoring, doc edits,
65+
and CI tweaks.
66+
- `ADVERSARIAL` is reserved for this exact major-deliverable trigger list:
67+
Foundation ADR cluster closure, master architecture doc, control-manifest
68+
v1.0+ promotion, batch ADR Proposed→Accepted events, stage-gate advances,
69+
release candidates / gold masters, or explicit user `red-team / challenge`
70+
language.
71+
- If uncertain whether the work meets a major trigger, use `STANDARD`.
72+
3. Perform the selected cross-check as a fresh reasoning pass by the current
73+
Codex session. Inspect the complete touched files and their relevant
74+
contracts. Report each finding as `HIGH`, `MEDIUM`, or `LOW` with an exact
75+
`path:line` reference, the violated contract or risk, and a concrete
76+
recommendation. If there are no findings, report `CLEAN`.
77+
4. Triage every finding:
78+
- Agree and confident that the fix preserves approved intent: apply it only
79+
within files already created or materially modified during this session,
80+
then run the narrowest meaningful verification.
81+
- Agree but out of scope: do not apply it; record it in the handoff Deferred
82+
section with the native finding quoted verbatim.
83+
- Disagree, uncertain, disputed, design-changing, architectural,
84+
game-feel/balance-changing, or scope-changing: halt and surface the finding
85+
plus analysis to the user. Do not proceed to rotation or commit.
86+
87+
### Round 2
88+
89+
Run Round 2 only when Round 1 caused a fix.
90+
91+
1. Always self-review the complete Round 1 fix set against the original
92+
finding, surrounding behavior, and verification evidence.
93+
2. Run a second native cross-check only when Round 1 included at least one
94+
`HIGH` finding or the fix changed cross-cutting executable behavior. This
95+
includes shared helpers, CI configuration, determinism-critical paths such
96+
as `src/core/sim/**`, public APIs, or ADR executable specifications. Use the
97+
same `STANDARD` or `ADVERSARIAL` tier selected in Round 1. Pure
98+
design/process-document fixes remain exempt from the second native
99+
cross-check.
100+
3. Triage Round 2 with a stop bias because a new finding means the first fix was
101+
incomplete:
102+
- Trivial and confidently intent-preserving only: fix a typo, document-text
103+
error, off-by-one in a named constant, or one-line obvious syntax error;
104+
inline-self-review that exact edit, verify it, and record it in the
105+
handoff. Do not run a third pass for this trivial fix.
106+
- Any non-trivial fix, ambiguity, disagreement, scope change, design or
107+
architecture decision, balance/game-feel decision, or finding outside the
108+
Round 1 fix set: halt and surface it to the user before Phase 1.
109+
110+
### Pass Cap And Audit Trail
111+
112+
- Cap the gate at three native review passes total, counting Round 1, a
113+
conditional Round 2 cross-check, and any user-directed rerun after a scope
114+
extension. A fourth native review pass requires explicit user approval. When
115+
asking, report the active reported context percentage and the estimated
116+
additional percentage cost; never substitute fixed token-window or time
117+
estimates. If the active percentage is unavailable, say so explicitly.
118+
- Record the review audit trail in `production/session-handoff.md`: exemption or
119+
tier, `CLEAN` or findings, fixes applied and verified, findings deferred with
120+
quotations, user-cleared findings, and any stopped pass.
121+
- The gate passes only when every finding is fixed and verified, explicitly
122+
deferred as out of scope, or cleared by the user, with nothing blocking on
123+
user input. Only then proceed to Phase 1.
55124

56125
## Phase 1: Choose The Label
57126

‎.codex/VERSION‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
0.4.5
1+
0.4.6

‎.codex/lib/validate_runtime.py‎

Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -295,6 +295,111 @@
295295
),
296296
)
297297

298+
HANDOFF_REVIEW_REQUIRED_PHRASES = {
299+
".agents/skills/handoff/SKILL.md": (
300+
"## Round 1",
301+
"## Round 2",
302+
"`STANDARD`",
303+
"`ADVERSARIAL`",
304+
"Foundation ADR cluster closure",
305+
"pure design/process-document",
306+
"self-review is sufficient and the native cross-check is skipped",
307+
"Mixed code-and-document changes are not exempt",
308+
"distinct native Codex review pass",
309+
"current Codex session",
310+
"`HIGH`, `MEDIUM`, or `LOW`",
311+
"`CLEAN`",
312+
"`path:line`",
313+
"If uncertain whether the work meets a major trigger, use `STANDARD`",
314+
"quoted verbatim",
315+
"stop before Phase 1",
316+
"second native cross-check",
317+
"`HIGH` finding",
318+
"cross-cutting executable behavior",
319+
"Trivial and confidently intent-preserving only",
320+
"Any non-trivial fix",
321+
"Do not run a third pass",
322+
"three native review passes",
323+
"fourth native review pass",
324+
"active reported context percentage",
325+
"review audit trail",
326+
"every finding",
327+
"Only then proceed to Phase 1",
328+
),
329+
"AGENTS.md": (
330+
"files already created or materially modified during the session",
331+
"intent-preserving review fixes",
332+
"active Codex session",
333+
"Round-two non-trivial findings",
334+
"external data-egress approval",
335+
"new intent, architecture, game-feel, balance, or scope decisions",
336+
),
337+
}
338+
339+
HANDOFF_REVIEW_FORBIDDEN_PATTERNS = (
340+
(
341+
re.compile(r"(?im)^\s*(?:\$\s*)?codex\s+(?:review|exec)\b"),
342+
"executable nested Codex CLI review command",
343+
),
344+
(
345+
re.compile(r"(?im)^\s*(?:\$\s*)?node\s+[^\n]*codex-companion(?:\.mjs)?\b"),
346+
"executable codex-companion command",
347+
),
348+
(
349+
re.compile(
350+
r"(?im)^\s*(?:export\s+)?[A-Z_][A-Z0-9_]*\s*=\s*[^\n]*"
351+
r"codex-companion(?:\.mjs)?\b"
352+
),
353+
"executable codex-companion path assignment",
354+
),
355+
(
356+
re.compile(
357+
r"(?i)(?<!never )(?<!do not )(?<!must not )"
358+
r"\b(?:call|run|use|invoke|launch|execute)\s+`?codex\s+(?:review|exec)\b"
359+
),
360+
"instruction to launch a nested Codex CLI reviewer",
361+
),
362+
(
363+
re.compile(
364+
r"(?i)(?<!never )(?<!do not )(?<!must not )"
365+
r"\b(?:call|run|use|invoke|launch|execute)\b[^.\n]{0,100}"
366+
r"\bcodex-companion(?:\.mjs)?\b"
367+
),
368+
"instruction to launch codex-companion",
369+
),
370+
(
371+
re.compile(
372+
r"(?i)(?<!never )(?<!do not )(?<!must not )"
373+
r"\b(?:call|run|use|invoke|launch|execute)\b[^.\n]{0,100}"
374+
r"\bClaude companion plugin\b"
375+
),
376+
"instruction to launch the Claude companion plugin",
377+
),
378+
(
379+
re.compile(
380+
r"(?i)(?<!never )(?<!do not )(?<!must not )"
381+
r"\b(?:call|use|invoke|launch)\b[^.\n]{0,120}"
382+
r"\banother model service\b"
383+
),
384+
"instruction to launch another model service",
385+
),
386+
(
387+
re.compile(r"(?i)\b(?:sandbox_permissions|require_escalated)\b"),
388+
"external-review escalation token",
389+
),
390+
(
391+
re.compile(
392+
r"(?i)\b(?:request|seek)\s+(?:user\s+)?approval\b"
393+
r"[^.\n]{0,120}\bexternal review\b"
394+
),
395+
"external-review approval instruction",
396+
),
397+
(
398+
re.compile(r"(?i)\bescalat(?:e|ed|ion)\b[^.\n]{0,120}\bexternal review\b"),
399+
"escalated external-review instruction",
400+
),
401+
)
402+
298403
INTERNAL_READONLY_CLOSEOUT_PATTERNS = (
299404
(re.compile(r"\bself[- ]check\b", re.IGNORECASE), "Self-Check"),
300405
(re.compile(r"\bregistry (?:candidate )?scan\b", re.IGNORECASE), "registry scan"),
@@ -539,6 +644,30 @@ def validate_bug_lifecycle_contract(root: Path) -> list[str]:
539644
return errors
540645

541646

647+
def validate_handoff_review_contract(root: Path) -> list[str]:
648+
errors: list[str] = []
649+
for rel, required_phrases in HANDOFF_REVIEW_REQUIRED_PHRASES.items():
650+
path = root / rel
651+
if not path.exists():
652+
errors.append(f"{rel}: missing handoff review contract surface")
653+
continue
654+
text = path.read_text(encoding="utf-8")
655+
missing = [phrase for phrase in required_phrases if not contains_phrase(text, phrase)]
656+
if missing:
657+
errors.append(f"{rel}: missing handoff review contract phrase(s): {', '.join(missing)}")
658+
659+
skill_rel = ".agents/skills/handoff/SKILL.md"
660+
skill_path = root / skill_rel
661+
if skill_path.exists():
662+
skill_text = skill_path.read_text(encoding="utf-8")
663+
for pattern, message in HANDOFF_REVIEW_FORBIDDEN_PATTERNS:
664+
match = pattern.search(skill_text)
665+
if match:
666+
line_number = skill_text.count("\n", 0, match.start()) + 1
667+
errors.append(f"{skill_rel}:{line_number}: {message}")
668+
return errors
669+
670+
542671
def validate_active_state_checkpoint_text(rel: Path, text: str, exempt: bool = False) -> list[str]:
543672
if exempt or ACTIVE_STATE_PATH not in text:
544673
return []
@@ -750,6 +879,8 @@ def main() -> int:
750879
errors.extend(budget_errors)
751880
warnings.extend(budget_warnings)
752881
errors.extend(validate_playtest_focus_contract(root))
882+
if args.kind in {"runtime", "skills"}:
883+
errors.extend(validate_handoff_review_contract(root))
753884
if args.kind == "skills":
754885
errors.extend(validate_skills(root, args.require_present))
755886
if args.kind == "agents":

‎AGENTS.md‎

Lines changed: 18 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -100,13 +100,24 @@ Question -> Options -> Decision -> Draft -> Approval.
100100
mutating `gh`, or writes to any path other than
101101
`production/session-state/active.md`.
102102
- `$handoff` exception: explicit invocation of the Codex-native `$handoff` skill
103-
counts as user approval for that skill's declared handoff workflow only:
104-
update `production/session-handoff.md`, `production/session-archive.md`, and
105-
`production/session-state/active.md`; stage relevant uncommitted changes by
106-
path; create the standard handoff commit; and push the current branch.
107-
- The `$handoff` exception does not authorize design/game-feel/balance
108-
decisions, new source edits outside the continuity files, writes to undeclared
109-
files, branch switching, force-pushes, or `--no-verify` / amend workarounds.
103+
counts as user approval for that skill's declared review gate and handoff
104+
workflow only. The review must stay inside the active Codex session; it must
105+
not launch a subprocess reviewer, subagent reviewer, companion plugin, or
106+
another model service, and must not create an external data-egress approval.
107+
- The exception authorizes confident, intent-preserving review fixes only in
108+
files already created or materially modified during the session. Those fixes
109+
may not introduce new intent, architecture, game-feel, balance, or scope
110+
decisions. Unrelated files and new work remain unauthorized.
111+
- Round-two non-trivial findings, uncertain or disputed findings, and findings
112+
that require design, architecture, game-feel, balance, or scope decisions must
113+
stop for user direction before continuity rotation, commit, or push.
114+
- Once the review gate passes, the exception authorizes updating
115+
`production/session-handoff.md`, `production/session-archive.md`, and
116+
`production/session-state/active.md`; staging relevant uncommitted changes by
117+
path; creating the standard handoff commit; and pushing the current branch.
118+
- The `$handoff` exception does not authorize unrelated source edits, writes to
119+
undeclared files, branch switching, force-pushes, or `--no-verify` / amend
120+
workarounds.
110121
- `$resume-from-handoff` exception: explicit invocation of the Codex-native
111122
`$resume-from-handoff` skill counts as user approval to write or overwrite
112123
only `production/session-state/active.md` with the current session routing

‎CHANGELOG.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,17 @@
11
# Changelog
22

3+
## v0.4.6 - 2026-07-10
4+
5+
- Restored `$handoff`'s mandatory two-round review gate, including
6+
standard/adversarial tier selection, pure-document exemptions, finding
7+
triage, conditional second review, pass caps, and an auditable handoff record.
8+
- Kept the cross-check inside the active Codex session and explicitly removed
9+
nested Codex CLI, Claude companion, subprocess, subagent, and external model
10+
review paths.
11+
- Expanded the `$handoff` authorization boundary for narrow intent-preserving
12+
fixes and added runtime validation to prevent the review contract or its
13+
no-egress safeguards from regressing.
14+
315
## v0.4.5 - 2026-07-09
416

517
- Updated `$bug-report verify` so a VERIFIED FIXED result can complete

0 commit comments

Comments
 (0)