From fa504660bdecae027a67053a389495228a3d8141 Mon Sep 17 00:00:00 2001 From: jester Date: Sun, 19 Apr 2026 12:55:34 +0000 Subject: [PATCH] Add Codex cross-repo review workflow and cleanup rules --- CODE_REVIEW_WORKFLOW.md | 240 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 240 insertions(+) create mode 100644 CODE_REVIEW_WORKFLOW.md diff --git a/CODE_REVIEW_WORKFLOW.md b/CODE_REVIEW_WORKFLOW.md new file mode 100644 index 0000000..2dbe60b --- /dev/null +++ b/CODE_REVIEW_WORKFLOW.md @@ -0,0 +1,240 @@ +# 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