spec: add Codex reasoning continuity to native compaction

[matdev83]

What changed

Revises the existing openai-codex-native-compaction Kiro specification so the feature covers the complete native context workflow rather than context reduction alone:

• request exact encrypted reasoning on every eligible Codex attempt
• retain and restore reasoning across requests and client-executed tool steps
• preserve reasoning → action → observation ordering
• compact only reasoning-complete exact native history
• keep previous_response_id as an optional WebSocket optimization rather than durable history authority
• require coding-oriented quality evidence in addition to token, request-size, and latency measurements

The PR updates all seven existing artifacts:

• spec.json
• requirements.md
• gap-analysis.md
• research.md
• design.md
• design-review.md
• tasks.md

Key architectural decisions

• Exact encrypted item replay is the durable correctness baseline. This matches current Codex CLI source, which persists native response items across turns; response IDs are primarily a turn-scoped WebSocket optimization.
• reasoning-output-preservation owns automatic cross-request reasoning state. Its final-stream observer sees only the surfaced winner, avoiding retention of swallowed retries or parallel-race losers.
• The direct Codex connector owns provider-specific compaction. It builds a reasoning-complete exact history after restoration, executes Responses Compaction V2, and stores account/model/session-bound checkpoints.
• A bounded internal continuity marker connects the two components. Required mode skips compaction when eligible reasoning restoration has not been established, and the marker is never sent upstream.
• Compaction uses a separate exact-history view. Existing no-tools text projection remains available for normal generation but cannot degrade structured call/output history used by compaction.
• Compaction remains disabled by default. Reasoning-only, compaction-only, both, and neither modes are defined for controlled evaluation.

Brownfield updates

The revised artifacts account for merged PR #235, which already provides exact Codex reasoning/compaction item transport and backend-plugin replay capability. Those behaviors are now characterized as prerequisites instead of being planned for duplicate implementation.

The design also integrates the existing surfaced-winner reasoning-preservation feature rather than introducing an unsafe connector-local reasoning store.

Review and polish

Three full design-review rounds were performed:

1. NO-GO — corrected reasoning-state ownership, response-ID scope, and reasoning-complete compaction ordering.
2. NO-GO — corrected unconditional encrypted-reasoning request behavior, exact history before no-tools projection, and Codex-aligned retained-item policy.
3. GO — architecture, traceability, security, transport, failure handling, and quality-evaluation checks passed.

Final consistency results:

• 113 acceptance criteria
• 113/113 criteria mapped to implementation tasks
• no unknown or orphan task references
• design remains below the repository's 1,000-line complexity warning
• spec.json remains tasks-generated; approvals remain false and implementation readiness remains false pending maintainer approval

Validation

• GitHub diff contains only the seven files under .kiro/specs/openai-codex-native-compaction/
• branch is based on current main and contains no runtime or configuration-default changes
• generated artifact contents were checked against their GitHub blob hashes
• no executable tests were run because this is a spec-only PR

The implementation plan defines contract-first unit, integration, race, fuzz, architecture, live Codex, and four-mode quality-evaluation gates.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: f009347f-7ee0-4edc-bc1f-480cf3878178

📥 Commits

Reviewing files that changed from the base of the PR and between 7ebce3e and 8011344.

📒 Files selected for processing (7)

• .kiro/specs/openai-codex-native-compaction/design-review.md
• .kiro/specs/openai-codex-native-compaction/design.md
• .kiro/specs/openai-codex-native-compaction/gap-analysis.md
• .kiro/specs/openai-codex-native-compaction/requirements.md
• .kiro/specs/openai-codex-native-compaction/research.md
• .kiro/specs/openai-codex-native-compaction/spec.json
• .kiro/specs/openai-codex-native-compaction/tasks.md

---

📝 Walkthrough

Summary by CodeRabbit

• New Features

  • Added a design for opt-in Codex context continuity with encrypted reasoning preservation.
  • Added support for native history replay and Responses Compaction V2 checkpoints.
  • Defined model-aware compaction, WebSocket continuation, retention, privacy, and fallback behavior.
  • Native compaction remains disabled by default and preserves full-history fallback.

• Documentation

  • Updated requirements, research, design review, gap analysis, and implementation plans.
  • Added quality, safety, traceability, and compatibility validation criteria.

Walkthrough

The specification replaces connector-only compaction with opt-in Codex context continuity. It defines encrypted reasoning replay, native history, Responses Compaction V2, checkpoint reuse, transport behavior, fallback rules, privacy controls, validation modes, and implementation gates.

Changes

Codex native continuity

Layer / File(s)	Summary
Brownfield evidence and design selection .kiro/specs/openai-codex-native-compaction/research.md, .kiro/specs/openai-codex-native-compaction/gap-analysis.md	Research and gap analysis compare existing reasoning preservation, Codex behavior, transport constraints, and implementation options.
Continuity requirements and data contracts .kiro/specs/openai-codex-native-compaction/requirements.md, .kiro/specs/openai-codex-native-compaction/design.md, .kiro/specs/openai-codex-native-compaction/spec.json	Requirements and design contracts define encrypted reasoning, exact native history, action ordering, model-aware planning, checkpoint scope, transport rules, fallback behavior, and default-off configuration.
Preparation and orchestration plan .kiro/specs/openai-codex-native-compaction/design.md, .kiro/specs/openai-codex-native-compaction/tasks.md	The execution plan covers marker validation, reasoning restoration, history construction, pure compaction planning, model compatibility, and pre-output failure handling.
Checkpoint, transport, and accounting execution .kiro/specs/openai-codex-native-compaction/tasks.md	Tasks define V2 collection, exact-prefix checkpoint replacement, account and transport orchestration, continuation reset, usage accounting, and privacy-safe diagnostics.
Validation and implementation gates .kiro/specs/openai-codex-native-compaction/design-review.md, .kiro/specs/openai-codex-native-compaction/tasks.md	The review records three validation rounds and a GO decision. The plan adds integration, live, quality, race, fuzz, privacy, and rollout gates.

Estimated code review effort: 4 (Complex) | ~60 minutes

Possibly related PRs

• matdev83/go-llm-interactive-proxy#158: Supplies the reasoning-preservation contracts extended by this Codex continuity design.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}