# Code Review Workflow

This document captures the current Codex-based review workflow for ZeroLagHub cross-repo code review and cleanup.

## Current review goal

Review the three active implementation repos together without breaking operations:
- `zlh-agent`
- `zpack-api`
- `zpack-portal`

Primary goals:
- verify inter-repo contracts and ownership boundaries
- identify mismatches and risky assumptions
- identify behavior-preserving cleanup / code-fold opportunities
- keep cleanup separate from runtime/toolchain modernization

## Current setup

All target repos should be fully up to date before review begins.

Codex environments are **one repo per environment**. The current working setup is:
- `Agent Review` environment -> `zlh-agent`
- `API Review` environment -> `zpack-api`
- `Portal Review` environment -> `zpack-portal`

There is **no multi-repo Codex environment** in the current setup. Cross-repo synthesis happens afterward in a separate chat/task by comparing the three outputs.

Recommended environment settings:
- universal image
- container caching ON
- setup script automatic
- internet access OFF unless explicitly needed

## Review order

1. review `zlh-agent` first as the source of truth for runtime behavior
2. review `zpack-api` second as the auth/transport/contract layer
3. review `zpack-portal` third as the UI/state/rendering layer
4. synthesize the three outputs in a separate chat/task
5. only then start cleanup / folding waves

## Cross-repo review checklist

For all three repos, the critical flows to trace are:
- provision / start / first boot
- stop / restart
- status / readiness
- backup create / list / delete / restore
- file edit / upload / revert
- console connect / reconnect

For each flow, review should identify:
- owner of behavior
- current contract
- assumptions about the other repos
- confirmed aligned areas
- mismatches / risky assumptions
- cleanup-safe folds
- high-risk breakpoints
- suggested follow-up checks

## Repo prompts

### Agent Review prompt

```text
Review this repository as the source of truth for runtime behavior in the ZeroLagHub stack.

Focus on:
- provisioning/startup
- stop/restart
- readiness and status
- backup/create/list/delete/restore
- file edit/upload/revert
- console lifecycle

Goals:
- identify owned behavior
- identify assumptions this repo makes about API and Portal
- identify any behavior that other repos are likely depending on implicitly
- identify cleanup-safe folds that preserve behavior
- identify any risky areas where refactoring could break operations

Do not refactor yet.
Do not propose broad architecture changes.
Prefer operational correctness over style commentary.

Return in this exact structure:
1. Owned behavior
2. Current contracts exposed to other repos
3. Assumptions about API/Portal
4. Confirmed aligned or stable areas
5. Mismatches / risky assumptions
6. Cleanup-safe folds
7. High-risk breakpoints
8. Suggested follow-up checks
```

### API Review prompt

```text
Review this repository as the transport, auth, and contract layer between zlh-agent and the Portal in the ZeroLagHub stack.

Focus on:
- auth / ownership / IP checks
- route forwarding to agent
- status polling and shaping
- backup/create/list/delete/restore forwarding
- restore async-start contract
- file edit/upload/revert forwarding
- websocket / console proxy behavior

Goals:
- identify owned behavior
- identify assumptions this repo makes about agent behavior
- identify assumptions this repo makes about Portal behavior
- identify duplicated logic that belongs in agent or portal instead
- identify cleanup-safe folds that preserve behavior
- identify risky areas where refactoring could break operations

Do not refactor yet.
Do not propose broad architecture changes.
Prefer operational correctness over style commentary.

Return in this exact structure:
1. Owned behavior
2. Current contracts exposed to Portal
3. Assumptions about agent
4. Confirmed aligned or stable areas
5. Mismatches / risky assumptions
6. Cleanup-safe folds
7. High-risk breakpoints
8. Suggested follow-up checks
```

### Portal Review prompt

```text
Review this repository as the UI/state/rendering layer of the ZeroLagHub stack.

Focus on:
- polling and status rendering
- server action flows
- backup/create/list/delete/restore UX
- restore accepted -> in-progress -> completion behavior
- file edit/upload/revert UX
- console connect/reconnect behavior
- any duplicated logic that looks like it belongs in API or agent

Goals:
- identify owned behavior
- identify assumptions this repo makes about API responses and agent semantics
- identify status/rendering mismatches that could mislead users
- identify cleanup-safe folds that preserve behavior
- identify risky areas where refactoring could break operations

Do not refactor yet.
Do not propose broad architecture changes.
Prefer operational correctness over style commentary.

Return in this exact structure:
1. Owned behavior
2. Current contracts consumed from API
3. Assumptions about API/agent
4. Confirmed aligned or stable areas
5. Mismatches / risky assumptions
6. Cleanup-safe folds
7. High-risk breakpoints
8. Suggested follow-up checks
```

## Synthesis step

After all three reviews complete, paste the outputs into a separate chat/task with headers like:

```text
AGENT REVIEW
...

API REVIEW
...

PORTAL REVIEW
...
```

Then synthesize into:
- confirmed aligned contracts
- mismatches
- risky assumptions
- operational breakpoints
- cleanup-safe folds
- suggested fix order

## Cleanup / folding rules

Cleanup happens **after** synthesis, not before.

Shared rule across Agent / API / Portal:
- prefer behavior-preserving folding over broad refactors
- fold repeated flows first
- split oversized files by responsibility second
- merge repeated flows, not concepts
- keep helpers small and concrete
- keep cleanup separate from runtime/toolchain/dependency upgrades

## Current cleanup direction

### Agent
- fold Forge + NeoForge installer flow
- fold devcontainer runtime installers
- split oversized HTTP files by responsibility
- add only small concrete helpers

### API
- fold repeated forwarding/auth/IP-guard patterns
- centralize stream-vs-JSON forwarding
- split oversized route/service files by responsibility

### Portal
- fold repeated API-client/status-polling/state-mapping logic
- centralize shared management action handling
- split oversized page/component/state files by responsibility

## Current toolchain posture

Current pinned / confirmed runtime posture at time of writing:
- Node: `22.22.2`
- Go: updated to a current supported line

Toolchain/runtime upgrades should be tracked and validated separately from cleanup-only changes.

## Session restart note

If a fresh session is needed, resume by:
1. reading this file
2. checking `OPEN_THREADS.md`
3. checking repo-specific trackers under `Codex/*/OPEN_ITEMS.md`
4. continuing the three-review -> synthesis -> cleanup workflow