From df06a5450e2c6f5402f6d1825f04ac1395b8ac71 Mon Sep 17 00:00:00 2001 From: jester Date: Thu, 16 Apr 2026 19:56:10 +0000 Subject: [PATCH] Reconcile root README with Codex ownership model --- README.md | 81 ++++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 60 insertions(+), 21 deletions(-) diff --git a/README.md b/README.md index f310a55..c99fd89 100644 --- a/README.md +++ b/README.md @@ -1,25 +1,26 @@ # zlh-grind -GPT Execution Workspace for ZeroLagHub. +GPT execution workspace for ZeroLagHub. -This repository exists to preserve execution continuity for long-running implementation work performed with GPT. +This repository preserves execution continuity for long-running implementation work, but it is **not** the final architecture source of truth. -It is the **execution workspace** and **working memory layer** for active implementation. - -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 work -- implementation findings +- unfinished cross-repo work +- implementation findings that matter across repos - session handovers - operational snapshots -- chronological session history +- 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. @@ -31,10 +32,12 @@ Start here, then continue in this order: 1. `SESSION_START.md` 2. `OPEN_THREADS.md` -3. `CONSTRAINTS.md` -4. `PROJECT_CONTEXT.md` *(if current platform state matters)* -5. `INFRASTRUCTURE.md` *(if VM/IP context matters)* -6. `UPSTREAMS.md` *(if cross-repo context matters)* +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. @@ -42,8 +45,7 @@ Do **not** start by digging through history unless the live docs are insufficien ## Live Working Set -These root files are the live control panel for the repo: - +These root files are the live control panel for platform-wide state: - `SESSION_START.md` - `OPEN_THREADS.md` - `CONSTRAINTS.md` @@ -51,14 +53,53 @@ These root files are the live control panel for the repo: - `INFRASTRUCTURE.md` - `UPSTREAMS.md` -Keep these current and concise. +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 @@ -73,8 +114,6 @@ These support the live docs, but they are not the normal starting point for a fr This repository should not become a dumping ground for every possible context artifact. -Do not let root-level docs multiply without a clear reason. - Root docs should answer only one question: **What must a new session know right now to continue work safely?** @@ -86,7 +125,7 @@ Root docs should answer only one question: Never assume speculative features are implemented. When in doubt: - - trust the live working set first -- use history folders for conflict resolution +- 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