From e4d1fdd7ea3c820e9ebdc557c11555cc72eee57e Mon Sep 17 00:00:00 2001 From: Fr0zka Date: Sun, 16 Aug 2026 14:41:00 +0200 Subject: [PATCH] docs(opstack): experimental is pushed and tracked -- correct the flat "never push" rule The rule said "Never push" without qualification, which was true while experimental existed only locally and became misleading the moment it did not: a future session would read it and let origin/experimental drift. Now: push experimental freely (tracked since 2026-07-29), never push main, which stays pinned at the known-good commit. Both statements of the rule are updated (OPSTACK-HANDOFF.md and OPSTACK-PROMPT.md's crash-safe discipline). Also added at both sites, because it is the failure mode this creates: a pushed commit is NOT a "verified green" marker. This branch carries unbuilt work by design, so OPSTACK-PROGRESS.md remains the only record of what was actually built and measured, and the remote records only what was written. Co-Authored-By: Claude Opus 5 --- OPSTACK-HANDOFF.md | 6 +++++- OPSTACK-PROMPT.md | 4 +++- 2 files changed, 8 insertions(+), 2 deletions(-) diff --git a/OPSTACK-HANDOFF.md b/OPSTACK-HANDOFF.md index add374d..68a6c3b 100644 --- a/OPSTACK-HANDOFF.md +++ b/OPSTACK-HANDOFF.md @@ -151,7 +151,11 @@ built and green. "~[-1,1]". Over-estimating costs CPU; under-estimating deletes collision. - `ProcessQueue` stays `EQueueMode::Mpsc`; `Epoch` carries through every async path; don't "optimize" the `ARCHITECTURE §8.10` invariants. -- Commit per coherent unit with a real message. **Never push.** `main` is the known-good fallback. +- Commit per coherent unit with a real message. **`experimental` is pushed and tracked + (`origin/experimental`, since 2026-07-29) — keep it in sync. NEVER push `main`**, which stays the + known-good fallback at the commit it has always been. ⚠️ A pushed commit here is **not** a + "verified green" marker: the branch carries unbuilt work by design, and only `OPSTACK-PROGRESS.md` + says what was actually built. - Update `CODEMAP §3`, `ARCHITECTURE §8`, tick `OPSTACK-PLAN`, append to `OPSTACK-PROGRESS.md`. - **When inserting a class into `VoxelDensityOpStack.cpp` / `VoxelHeightOpStack.cpp`, put it ABOVE the labelled end of the anonymous namespace.** Anchoring on the FACTORIES banner puts it outside, diff --git a/OPSTACK-PROMPT.md b/OPSTACK-PROMPT.md index 56485df..94263b5 100644 --- a/OPSTACK-PROMPT.md +++ b/OPSTACK-PROMPT.md @@ -146,7 +146,9 @@ mid-edit, and nobody will be watching.** Everything below follows from that. CRASH-SAFE DISCIPLINE (non-negotiable when unattended) 1. `git commit` after every coherent unit — a file, a test, a header. Small and often. You are on branch `experimental`; `main` is the known-good fallback, so committing costs nothing and a - half-finished commit is infinitely better than an uncommitted half-edit. Never push. + half-finished commit is infinitely better than an uncommitted half-edit. Pushing `experimental` + is fine and expected (it is tracked as `origin/experimental` since 2026-07-29); **never push + `main`.** 2. Maintain `OPSTACK-PROGRESS.md` at the plugin root. APPEND (never rewrite) a dated entry per milestone: what you did, what you believe is true, what is UNVERIFIED (i.e. everything not yet built), and the single next action. Write the entry BEFORE starting the work it describes, so an