AGENTS.md gets a new Architecture section with boundary
invariants. DESIGN.md §12 explains the residue problem, the
Agent-tool split, and why Haiku is sufficient for the runner.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- Зачем:
- round-5 adversarial review (claude-team-review) нашёл 2 HIGH и 3 MEDIUM, которых не увидел round-4 self-review. Основное — регрессия в b213678, где при рефакторе primary-path silently дропнуло malformed-JSON-first-line handling, и противоречие в Step 7 step 4 между «same approach as Step 4 check 4» и «keep previous id».
- Что:
- SKILL.md Step 4 check 4: primary-path с явными ветками — valid UUID → save; любой другой случай (empty / malformed / missing thread_id / partial output) → fallthrough на secondary. Secondary описан как двухпричинный (sandbox suppression + format drift), не только «0 bytes».
- SKILL.md Step 7 step 4: явно разведено с Step 4 check 4 — zero-find в resume НЕ абортит round, а keep previous CODEX_SESSION_ID (§2.4.4 гарантирует что thread id не ротируется). Добавлен warning-сообщение.
- SKILL.md Step 2/4/7/Rules: убран `echo $(($(date +%s) - 1))` Bash-вызов, timestamp считается Opus'ом в reasoning и подставляется литералом. Убирает compound-command permission-матч проблему (`$()` + `- 1` арифметика) и один Bash-круг на раунд.
- SKILL.md Step 7 fresh-exec fallback: архивирует failed-resume артефакты через `mv` в `*-failed-resume.{jsonl,txt}` ПЕРЕД fresh exec. Step 9 cleanup glob расширен.
- DESIGN.md §9.5: cross-ref «Step 4 check 3» → «Step 4 check 4».
- DESIGN.md §4.1 trade-offs: описание CODEX_SESSIONS_BEFORE переписано под in-reasoning capture.
- README.md: убрана `Bash(date +%s)` permission, добавлены `Bash(mv ...)` для архивации.
- Проверка:
- Повторно прогнать self-review с фокусом на: (а) понятен ли novice reader malformed-case fallthrough, (б) не противоречит ли Step 7 step 4 Step 4 check 4 после правки.
- Зачем:
- `-newermt "@<epoch>"` и `-printf` в secondary session-id capture — GNU-специфичные; на macOS BSD find они не работают, а тестировать на маке негде.
- Что:
- SKILL.md: добавлена one-paragraph platform note рядом с `find` — формулирует цель шага ("найти свежие rollout-файлы, выбрать последний, извлечь UUID") и приглашает Opus/пользователя подставить BSD-эквивалент.
- docs/DESIGN.md §9.5: новое known-limitation с обоснованием template+understanding подхода вместо platform-detection.
- README.md Known limitations: user-facing note, что end-to-end на macOS не тестировался.
- Проверка:
- Ничего не ломается на Linux (команды без изменений).
- На macOS оператор читает note и адаптирует.
- Зачем:
- остатки документации ссылались на `- < file` и старый одноуровневый session-id, расходились с SKILL.md после основной правки.
- Что:
- §3.2 теперь рекомендует `cat file | cmd -` со ссылкой на §4.13.
- §7.2 smoke-test resume переведён на pipe-форму и включает secondary filesystem session-id capture.
- §7.3 (bad-UUID) тоже на pipe-форме для изоляции от §6.6.
- §2.5 разделяет success-row на reference и affected окружения, добавлен row для `- < file` exit-1-empty-stderr.
- Проверка:
- `grep -n '\- < ' docs/DESIGN.md` остаются только контекстные упоминания (§2.1 описание обеих форм, §4.13 decision, §6.6 lesson, §8 log).
- Зачем:
- форма `codex exec ... - < file` exit=1 с пустым stderr, а `--json` stdout оказывается пустым в части Claude Code песочниц; без обхода скилл не может захватить session ID и теряет resume на раундах 2-5.
- Что:
- SKILL.md Step 4/7 переведены на `cat file | codex exec ... -` как canonical; добавлен two-tier захват session ID (primary = first JSONL line, secondary = UUID из имени `~/.codex/sessions/**/rollout-*.jsonl` с mtime > CODEX_SESSIONS_BEFORE).
- README.md обновлены permissions (pipe-форма, `find rollout-*`, `date +%s`) и добавлен troubleshooting про env-specific пустой JSONL.
- docs/DESIGN.md: §2.1 описывает обе формы, §2.2 фиксирует env-specific suppression, §2.3 добавляет filesystem-recovery путь, §4.1 переделан на two-tier decision, добавлены §4.13 (canonical pipe) и §6.6 (lesson от 2026-04-17), в §8 новая строка с окружением yantar-k8s.
- Проверка:
- DESIGN.md §7.1 smoke test (обновлён на pipe-форму + проверка filesystem secondary path).
- Оба окружения (reference WSL2 + containerized sandbox) должны давать валидный session ID и успешный resume.
1082-line design note covering:
- Empirical facts about Codex CLI 0.121.0 (invocation, streams,
resume semantics, known failure modes) with copy-pasteable
verification commands.
- Claude Code harness facts (Bash truncation, cwd drift, Opus
literal-interpretation tendencies).
- 12 design decisions in a uniform format: what, where in SKILL.md,
alternatives considered, why chosen, trade-offs accepted.
- Rejected ideas (marker files, per-round naming, $(pwd), etc.) with
reasons, so future contributors don't re-propose them.
- Prior diagnostic errors from a previous agent-auditor's dump that
turned out to be wrong when verified, kept as a methodological
lesson.
- Smoke-test protocol (§7) with concrete commands and expected
outputs so any maintainer can verify the Codex contract still holds
in minutes.
- Update protocol: when and how to revise this file, with a pointer
that future Opus generations interpret instructions more literally
and SKILL.md hardening must track that.
- Mermaid flow diagram of the round-trip.
Intended audiences: future Claude sessions resuming work on the skill,
human developers, and new contributors. The file is self-contained —
does not rely on conversation history that produced the current design.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
ddadminandClaude Opus 4.7