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]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 3e97883d-0af7-41f6-8425-7b341e67acba

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

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.}