[codex] Release 2.0.52 cleanup gate

CHANGELOG.md

@@ -2,6 +2,29 @@
 
 ## [Unreleased]
 
+## [2.0.52] - 2026-05-31
+
+Tighten the cleanup gate lore
+
+Flow 2.0.52 turns the simplification pass into an enforced maintenance boundary. Unused value exports are now driven to zero and guarded by a deadcode export budget, schema barrels stop re-exporting private internals, prompt fragments keep only active generated-prompt inputs, and adapter/runtime helper exports are narrowed to the surfaces that are still actually consumed.
+
+The release also removes the old final-review compatibility lore. Prior `oracleRefs`, `test_oracle`, and `test_oracle_authenticity` payload terms are rejected instead of canonicalized, final-review behavior schemas live in their own module, and detailed final-review gates require meaningful trimmed integration and regression evidence rather than whitespace-only placeholders.
+
+The release deliberately does not add slash commands, runtime tools, prompt modes, state paths, package exports, installer behavior, dependencies, live OpenCode UI automation, or a persisted session schema version. It intentionally contracts internal and legacy review payload surfaces while preserving the existing `@opencode-ai/plugin` and `zod` compatibility boundary.
+
+Constraint: Keep unused value exports at zero through `bun run check:deadcode-exports`
+Constraint: Treat legacy final-review terms as invalid input, not compatibility aliases
+Constraint: Keep `@opencode-ai/plugin` at `1.14.48` and `zod` at `4.1.8`; this release changes no dependency compatibility boundary
+Rejected: Keep broad runtime/schema barrels for possible future callers | the package public API remains root-only, and unused internal exports were hiding ownership
+Rejected: Preserve old final-review aliases after the cleanup | backwards compatibility is intentionally out of scope for this simplification release
+Rejected: Count whitespace-only detailed-review checks as evidence | detailed final review requires meaningful integration and regression accounting
+Confidence: high
+Scope-risk: medium
+Reversibility: moderate
+Directive: Keep future simplification work budget-backed and source-owned; do not widen internal exports or revive compatibility aliases without a current consumer and release-note justification
+Tested: `bun test tests/runtime/final-review-contracts.test.ts` (36 pass, 0 fail, 197 expect() calls); `bun run check` (release gate passed: dependency contract OK with project/plugin/root `zod=4.1.8`, architecture seams OK, fresh surfaces OK, deadcode export budget OK with `exports=0`, release hygiene OK, pack invariants OK for version `2.0.52`, bundle sanity OK, full suite 676 pass/0 fail, lint passed, bench smoke and bench gate passed); `bun run smoke:release` (passed for package `2.0.52`, wrote release-smoke evidence under `prompt-exports/release-smoke/`, real OpenCode CLI not invoked); RepoPrompt MCP code review found one P1 detailed-final-review evidence issue before release, and this patch fixes it
+Not-tested: Live OpenCode UI runtime interaction; live GitHub-hosted release workflow run for tag `v2.0.52` before push
+
 ## [2.0.51] - 2026-05-21
 
 Keep runtime projections out of handoff lore

docs/architecture/runtime-complexity-baseline.md

@@ -10,9 +10,9 @@ This document captures measurable simplification baselines and the recurring Pha
 - Collector: `bun run report:runtime-simplification-metrics`
 - Runtime subdomain breakdown: diagnostic-only `runtime.subdomains` in the metrics report (`application`, `domain`, `transitions`, `lifecycle`, `recovery`, `rendering`, `root`, and any future `src/runtime/<subdomain>/` directory)
 
-## KPI baseline table (captured 2026-05-14)
+## KPI baseline table (captured 2026-05-24)
 
-Current canonical snapshot (captured `2026-05-14T07:09:17.649Z`): runtime files `124`, runtime LOC `17,480`, runtime files >= 300 LOC `7`, top-5 LOC share `9.7%`, architecture seam violations `0`.
+Current canonical snapshot (captured `2026-05-24T12:31:45.180Z`): runtime files `128`, runtime LOC `17,850`, runtime files >= 300 LOC `3`, top-5 LOC share `8.5%`, architecture seam violations `0`. The May 24 simplification pass accepted a small runtime file-count and total-LOC increase to move review-gate, history-presenter, detailed-final-review, and behavior-schema internals behind stable facades while cutting hotspot concentration.
 
 Historical same-pass snapshots remain useful for trend comparison only. The 2026-05-13 current snapshot was runtime files `107`, runtime LOC `17,040`, runtime files >= 300 LOC `14`, top-5 LOC share `14.1%`, architecture seam violations `0`. The preceding 2026-05-13 baseline was runtime files `105`, runtime LOC `17,005`, runtime files >= 300 LOC `14`, top-5 LOC share `15.0%`, with `final-review-behavior-risks.ts` as the largest hotspot at `571` LOC.
 
@@ -21,37 +21,37 @@ Historical pass snapshots are retained in investigation logs; this document trac
 | KPI | Baseline | Target direction | Measurement method | Notes |
 | --- | --- | --- | --- | --- |
 | Architecture seam violations | `0` | Hold at `0` | `bun run check:architecture-seams:enforce` | Enforced in CI |
-| Runtime TypeScript file count | `124` | Down | `report:runtime-simplification-metrics` | Current refactors trade more files for smaller hotspots |
-| Runtime LOC | `17,480` | Down | `report:runtime-simplification-metrics` | Fresh local measurement on 2026-05-14 |
-| Runtime files >= 300 LOC | `7` | Down | `report:runtime-simplification-metrics` | Improved from 2026-05-13 snapshot |
-| Top-5 runtime-file LOC share | `9.7%` | Down | `report:runtime-simplification-metrics` | Improved from `14.1%` 2026-05-13 snapshot |
-| Runtime churn hotspot leader | `src/runtime/schema.ts` (26 touches / 30d) | Down | `git log` via metrics script | Next churn leaders: `session-lifecycle.ts` (18), `session-workspace.ts` (18), `transitions/plan.ts` (18), `domain/index.ts` (15) |
-| Runtime subdomain LOC/file distribution | See 2026-05-14 subdomain snapshot below | Down or localized by touched subdomain | `report:runtime-simplification-metrics` | Diagnostic-only; helps prove localized improvement without adding a hard gate |
+| Runtime TypeScript file count | `128` | Down | `report:runtime-simplification-metrics` | Current refactors trade more files for smaller hotspots |
+| Runtime LOC | `17,850` | Down | `report:runtime-simplification-metrics` | Fresh local measurement on 2026-05-24 |
+| Runtime files >= 300 LOC | `3` | Down | `report:runtime-simplification-metrics` | Improved from `7` on 2026-05-14 |
+| Top-5 runtime-file LOC share | `8.5%` | Down | `report:runtime-simplification-metrics` | Improved from `9.7%` on 2026-05-14 |
+| Runtime churn hotspot leader | `src/runtime/schema.ts` (17 touches / 30d) | Down | `git log` via metrics script | Next churn leaders: `session-presenters.ts` (13), `domain/index.ts` (13), `session-actions.ts` (11), `transitions/plan.ts` (11) |
+| Runtime subdomain LOC/file distribution | See 2026-05-24 subdomain snapshot below | Down or localized by touched subdomain | `report:runtime-simplification-metrics` | Diagnostic-only; helps prove localized improvement without adding a hard gate |
 | Fast test lane runtime | `~0.22s` local | Hold low | timed `bun run test:fast` | Keep this as refactor safety lane |
 | Replay/integration lane runtime | `~0.15s` local | Hold low | timed `bun run test:replay` | Keep replay lane stable |
 
-## 2026-05-14 runtime simplification snapshot
+## 2026-05-24 runtime simplification snapshot
 
 Largest runtime files after the latest runtime simplification pass:
 
-1. `src/runtime/schema-review-shared.ts` — `353` LOC
-2. `src/runtime/transitions/execution-completion-validation.ts` — `347` LOC
-3. `src/runtime/application/session-presenters.ts` — `341` LOC
-4. `src/runtime/domain/final-review-coverage.ts` — `332` LOC
-5. `src/runtime/application/session-actions.ts` — `326` LOC
+1. `src/runtime/application/session-actions.ts` — `326` LOC
+2. `src/runtime/transitions/completion-gates.ts` — `308` LOC
+3. `src/runtime/application/doctor-checks.ts` — `305` LOC
+4. `src/runtime/transitions/execution-completion-normalization.ts` — `295` LOC
+5. `src/runtime/transitions/plan.ts` — `292` LOC
 
 Runtime subdomain snapshot (`fileCount` / `totalLoc` / large files):
 
 | Subdomain | Files | LOC | Files >= 300 LOC |
 | --- | ---: | ---: | ---: |
-| `application` | `34` | `4,791` | `3` |
-| `domain` | `30` | `4,185` | `1` |
+| `application` | `35` | `4,885` | `2` |
+| `domain` | `31` | `4,254` | `0` |
 | `json` | `2` | `431` | `0` |
 | `lifecycle` | `1` | `34` | `0` |
 | `recovery` | `2` | `153` | `0` |
 | `rendering` | `1` | `8` | `0` |
-| `root` | `41` | `5,288` | `1` |
-| `transitions` | `13` | `2,590` | `2` |
+| `root` | `42` | `5,470` | `0` |
+| `transitions` | `14` | `2,615` | `1` |
 
 ## Phase 4 execution loop (delete-first simplification)
 
@@ -70,11 +70,11 @@ For each simplification phase, capture the metrics report immediately before and
 
 ## Current top hotspot candidates
 
-1. `src/runtime/schema-review-shared.ts` (largest file: `353` LOC)
-2. `src/runtime/transitions/execution-completion-validation.ts` (large file: `347` LOC)
-3. `src/runtime/application/session-presenters.ts` (large file: `341` LOC)
-4. `src/runtime/domain/final-review-coverage.ts` (large file: `332` LOC)
-5. `src/runtime/schema.ts` (highest churn: `26` touches / 30d)
+1. `src/runtime/application/session-actions.ts` (large file: `326` LOC)
+2. `src/runtime/transitions/completion-gates.ts` (large file: `308` LOC)
+3. `src/runtime/application/doctor-checks.ts` (large file: `305` LOC)
+4. `src/runtime/transitions/execution-completion-normalization.ts` (near-threshold file: `295` LOC)
+5. `src/runtime/schema.ts` (highest churn: `17` touches / 30d)
 
 ## Guardrails
 

docs/development.md

@@ -27,6 +27,8 @@ Useful scripts:
 
 - `bun run build`
 - `bun run deadcode`
+- `bun run report:deadcode-exports`
+- `bun run check:deadcode-exports`
 - `bun run test`
 - `bun run test:fast`
 - `bun run test:deep`
@@ -49,8 +51,9 @@ Useful scripts:
 
 Gate status terms:
 
-- **Hard** gates fail the command and block merge/release readiness. Examples: `bun run check:dependency-contract`, `bun run check:architecture-seams:enforce`, `bun run check:generated-drift`, `bun run gate:completion-lane`, `bun run test:replay`, and `bun run bench:gate`.
-- **Advisory** gates are supplemental visibility and do not block by exit code. `bun run check:boundary-report` is advisory by design today: it exits `0` and reports prompt/tool boundary findings unless a future reviewed change promotes it with script, docs, and test updates.
+- **Hard** gates fail the command and block merge/release readiness. Examples: `bun run check:dependency-contract`, `bun run check:architecture-seams:enforce`, `bun run check:generated-drift`, `bun run deadcode`, `bun run gate:completion-lane`, `bun run test:replay`, and `bun run bench:gate`.
+- **Advisory** gates are supplemental visibility and do not block by exit code. `bun run check:boundary-report` and `bun run report:deadcode-exports` are advisory by design today: they exit `0` and report findings unless a future reviewed change promotes them with script, docs, and test updates.
+- **Ratcheted** gates fail on regression against the current reviewed budget while allowing known remaining cleanup debt to be handled incrementally. `bun run check:deadcode-exports` runs inside `bun run check` and fails if unused exported symbols or duplicate exports increase above the checked-in budget.
 - **Diagnostic/report** commands support investigation or planning. `bun run check:architecture-seams` is seam report mode; `bun run report:runtime-simplification-metrics` prints simplification metrics. Use the corresponding hard gate (`check:architecture-seams:enforce`) for pass/fail readiness.
 
 The full matrix, artifact owners, source-of-truth scripts, repeated-inside-`check` status, and CI/local no-weakening rules live in [`docs/maintainer-contract.md#gate-contract-matrix`](maintainer-contract.md#gate-contract-matrix).

docs/maintainer-contract.md

@@ -167,6 +167,8 @@ Accepted simplification tradeoffs should be explicit: a file-count increase is a
 | Architecture seams enforce | `bun run check:architecture-seams:enforce` | architecture seam owner | `scripts/cross-area/architecture-seams.mjs` | targeted seam blocker and part of `bun run check` | focused fast-fail lane and/or covered by `bun run check` | hard | yes | fails on blocked cross-layer imports | Preserve enforce mode as the merge contract; report mode is not a substitute. |
 | Architecture seams report | `bun run check:architecture-seams` | architecture seam owner | `scripts/cross-area/architecture-seams.mjs` | local diagnostic inventory | optional diagnostic artifact only | diagnostic | no | exits `0` while reporting seam findings | Keep separate from hard enforcement to avoid accidental blocking semantics. |
 | Generated drift | `bun run check:generated-drift` | prompt/review/descriptor owners | `package.json` composed script | generated prompt/review/descriptor parity check | focused fast-fail lane and/or covered by `bun run check` | hard | indirect | fails on generated prompt/review/descriptor parity drift | Keep either direct invocation in `check` or equivalent covered constituent checks + explicit proof in no-weakening notes. |
+| Unused-code gate | `bun run deadcode` | package/runtime maintainers | `package.json#scripts.deadcode` + `package.json#knip` | unused file, dependency, unlisted, unresolved, binary, and catalog check | covered by `bun run check` | hard | yes | fails on hard Knip issue types | Keep symbol-level export reports separate unless intentional internal barrels and schema facades have reviewed allowlists. |
+| Unused-code export budget | `bun run check:deadcode-exports`; use `bun run report:deadcode-exports` for details | package/runtime maintainers | `package.json#scripts.check:deadcode-exports` + `scripts/cross-area/deadcode-export-budget.mjs` + `package.json#knip` | unused export/type/duplicate regression budget | covered by `bun run check`; report command remains advisory | ratcheted hard budget | yes | fails when symbol-level counts exceed the checked-in budget | Lower the budget when cleanup removes high-confidence declarations; do not raise it without a reviewed reason. |
 | Completion lane | `bun run gate:completion-lane` | runtime completion owner | `scripts/cross-area/check-completion-lane.mjs` | focused completion invariant gate and part of `bun run check` | focused fast-fail lane and/or covered by `bun run check` | hard | yes | fails on completion-lane invariant violation | Completion/reviewer gates are release-critical and must remain hard. |
 | Snapshot persistence gate | `bun run test:replay` | runtime persistence owners | `tests/runtime/semantic-invariants.test.ts` + `tests/runtime/final-completion-gates.test.ts` | snapshot/runtime invariant gate and part of `bun run check` | focused fast-fail lane and/or covered by `bun run check` | hard | yes | fails on runtime invariant regression | Snapshot-first persistence is the supported authority; event/replay/checkpoint stores are intentionally absent. |
 | Benchmark gate | `bun run bench:gate` | performance owner | `scripts/cross-area/bench-gate.mjs` | benchmark baseline gate and part of `bun run check` | focused fast-fail lane and/or covered by `bun run check` | hard | yes | fails on benchmark baseline regression | `bench:smoke` may provide extra signal, but `bench:gate` owns baseline failure. |

docs/releases/v2.0.52.md

@@ -0,0 +1,22 @@
+# v2.0.52
+
+Tighten the cleanup gate lore
+
+Flow 2.0.52 turns the simplification pass into an enforced maintenance boundary. Unused value exports are now driven to zero and guarded by a deadcode export budget, schema barrels stop re-exporting private internals, prompt fragments keep only active generated-prompt inputs, and adapter/runtime helper exports are narrowed to the surfaces that are still actually consumed.
+
+The release also removes the old final-review compatibility lore. Prior `oracleRefs`, `test_oracle`, and `test_oracle_authenticity` payload terms are rejected instead of canonicalized, final-review behavior schemas live in their own module, and detailed final-review gates require meaningful trimmed integration and regression evidence rather than whitespace-only placeholders.
+
+The release deliberately does not add slash commands, runtime tools, prompt modes, state paths, package exports, installer behavior, dependencies, live OpenCode UI automation, or a persisted session schema version. It intentionally contracts internal and legacy review payload surfaces while preserving the existing `@opencode-ai/plugin` and `zod` compatibility boundary.
+
+Constraint: Keep unused value exports at zero through `bun run check:deadcode-exports`
+Constraint: Treat legacy final-review terms as invalid input, not compatibility aliases
+Constraint: Keep `@opencode-ai/plugin` at `1.14.48` and `zod` at `4.1.8`; this release changes no dependency compatibility boundary
+Rejected: Keep broad runtime/schema barrels for possible future callers | the package public API remains root-only, and unused internal exports were hiding ownership
+Rejected: Preserve old final-review aliases after the cleanup | backwards compatibility is intentionally out of scope for this simplification release
+Rejected: Count whitespace-only detailed-review checks as evidence | detailed final review requires meaningful integration and regression accounting
+Confidence: high
+Scope-risk: medium
+Reversibility: moderate
+Directive: Keep future simplification work budget-backed and source-owned; do not widen internal exports or revive compatibility aliases without a current consumer and release-note justification
+Tested: `bun test tests/runtime/final-review-contracts.test.ts` (36 pass, 0 fail, 197 expect() calls); `bun run check` (release gate passed: dependency contract OK with project/plugin/root `zod=4.1.8`, architecture seams OK, fresh surfaces OK, deadcode export budget OK with `exports=0`, release hygiene OK, pack invariants OK for version `2.0.52`, bundle sanity OK, full suite 676 pass/0 fail, lint passed, bench smoke and bench gate passed); `bun run smoke:release` (passed for package `2.0.52`, wrote release-smoke evidence under `prompt-exports/release-smoke/`, real OpenCode CLI not invoked); RepoPrompt MCP code review found one P1 detailed-final-review evidence issue before release, and this patch fixes it
+Not-tested: Live OpenCode UI runtime interaction; live GitHub-hosted release workflow run for tag `v2.0.52` before push