Reconcile root README with Codex ownership model
This commit is contained in:
parent
6a1ec70f69
commit
df06a5450e
81
README.md
81
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
|
||||
|
||||
Loading…
Reference in New Issue
Block a user