132 lines
3.5 KiB
Markdown
132 lines
3.5 KiB
Markdown
# zlh-grind
|
||
|
||
GPT execution workspace for ZeroLagHub.
|
||
|
||
This repository preserves execution continuity for long-running implementation work, but it is **not** the final architecture source of truth.
|
||
|
||
It is the working memory layer for:
|
||
- current platform context
|
||
- active cross-repo work
|
||
- session startup guidance
|
||
- repo-specific tracking handoff into `Codex/`
|
||
|
||
---
|
||
|
||
## What This Repo Is For
|
||
|
||
Use this repository to preserve:
|
||
- active execution context
|
||
- unfinished cross-repo work
|
||
- implementation findings that matter across repos
|
||
- session handovers
|
||
- operational snapshots
|
||
- chronological session history when deep recovery is needed
|
||
|
||
The goal is simple: a new session should be able to enter this repository, read a small set of files, and continue work safely.
|
||
|
||
---
|
||
|
||
## Front Door
|
||
|
||
Start here, then continue in this order:
|
||
|
||
1. `SESSION_START.md`
|
||
2. `OPEN_THREADS.md`
|
||
3. `Codex/README.md`
|
||
4. the relevant repo tracker under `Codex/`
|
||
5. `CONSTRAINTS.md`
|
||
6. `PROJECT_CONTEXT.md` *(if current platform state matters)*
|
||
7. `INFRASTRUCTURE.md` *(if VM/IP context matters)*
|
||
8. `UPSTREAMS.md` *(if cross-repo context matters)*
|
||
|
||
Do **not** start by digging through history unless the live docs are insufficient.
|
||
|
||
---
|
||
|
||
## Live Working Set
|
||
|
||
These root files are the live control panel for platform-wide state:
|
||
- `SESSION_START.md`
|
||
- `OPEN_THREADS.md`
|
||
- `CONSTRAINTS.md`
|
||
- `PROJECT_CONTEXT.md`
|
||
- `INFRASTRUCTURE.md`
|
||
- `UPSTREAMS.md`
|
||
|
||
Repo-specific truth lives under:
|
||
- `Codex/API/*`
|
||
- `Codex/Portal/*`
|
||
- `Codex/Agent/*`
|
||
|
||
Keep root concise and keep repo-specific work in Codex.
|
||
|
||
---
|
||
|
||
## Codex Ownership Model
|
||
|
||
`Codex/` is the repo-specific execution layer.
|
||
|
||
Use:
|
||
- `Codex/API/*` for `jester/zpack-api`
|
||
- `Codex/Portal/*` for `jester/zpack-portal`
|
||
- `Codex/Agent/*` for `jester/zlh-agent`
|
||
|
||
Each repo folder contains:
|
||
- `README.md` — front door for that repo track
|
||
- `CURRENT_STATE.md` — what is implemented now
|
||
- `OPEN_ITEMS.md` — unfinished work only
|
||
- `DECISIONS.md` — settled choices / do-not-re-litigate notes
|
||
|
||
Root `OPEN_THREADS.md` is for **cross-repo/platform work only**.
|
||
|
||
---
|
||
|
||
## Cleaning Rule
|
||
|
||
Do not let stale work accumulate.
|
||
|
||
When a repo-specific item is completed:
|
||
- remove it from that repo’s `Codex/*/OPEN_ITEMS.md`
|
||
- move durable implemented behavior into `CURRENT_STATE.md`
|
||
- move settled choices into `DECISIONS.md`
|
||
- remove it from root `OPEN_THREADS.md` unless it still has active cross-repo/platform implications
|
||
|
||
If an item exists in root and also belongs to only one repo, it should usually be removed from root.
|
||
|
||
Do not re-add old items without current evidence that they are still open or have regressed.
|
||
|
||
---
|
||
|
||
## History And Deep Context
|
||
|
||
Use these only when deeper recovery is needed:
|
||
- `SESSION_LOG/` — chronological implementation history
|
||
- `Session_Summaries/` — session handovers and milestone summaries
|
||
- `SCRATCH/` — temporary or investigative notes
|
||
- `docs/` — reference and archive material
|
||
- `MANAGEMENT/` — non-core planning material
|
||
|
||
These support the live docs, but they are not the normal starting point for a fresh session.
|
||
|
||
---
|
||
|
||
## Repo Boundary
|
||
|
||
This repository should not become a dumping ground for every possible context artifact.
|
||
|
||
Root docs should answer only one question:
|
||
|
||
**What must a new session know right now to continue work safely?**
|
||
|
||
---
|
||
|
||
## Session Rule
|
||
|
||
Never assume speculative features are implemented.
|
||
|
||
When in doubt:
|
||
- trust the live working set first
|
||
- trust the relevant `Codex/*` tracker for repo-owned work
|
||
- use history folders only for conflict resolution
|
||
- update the live docs after meaningful work is completed
|