jester/zlh-grind
1
0
Fork 0
Code Issues 14 Pull Requests Actions Packages Projects Releases Wiki Activity
c57c5ba3df
zlh-grind/CODE_REVIEW_WORKFLOW.md

6.8 KiB
Raw Blame History

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

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

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

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:

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