252 lines
13 KiB
Markdown
252 lines
13 KiB
Markdown
# Session 0046.0 — Transcript
|
||
|
||
> Date: 2026-05-30
|
||
> Goal: Fold the operator's two-tier-testing refinement into the
|
||
> published docs — engineering handbook §10.3 + ohm-rfc ROADMAP #38
|
||
> (note on #40) — then, if time, author the rfc-app Tier-1 local-Docker
|
||
> e2e scaffold as #37/#38 groundwork (no VM work).
|
||
>
|
||
> Outcome: **Done. Handbook §10.3 rewritten to the two-tier model
|
||
> (engineering PR #1, merged). ohm-rfc ROADMAP now carries the full
|
||
> two-tier treatment — #38 table row + detailed narrative, #40 narrative
|
||
> + table row (PR #4 core + PR #5 coherence, both merged). rfc-app
|
||
> `e2e/` Tier-1 scaffold authored (PR #4, left OPEN for review). No
|
||
> deploys, no tags, no pin bumps — docs + groundwork only.**
|
||
>
|
||
> Texture note: this session ran amid the harness-corruption /
|
||
> parallel-execution conditions flagged at launch (the prior advisory
|
||
> "0046" hit Bash/Read garbling). Concretely: ROADMAP commits appeared
|
||
> on `main` authored at this session's start time, and my coherence
|
||
> commit (`30326e3`) reached `main` via a PR I did not open (#5,
|
||
> `roadmap/38-body-two-tier`) while my own PR (#6, same commit) sat
|
||
> open and un-mergeable. Plus a wedged Gitea merge-queue window. Every
|
||
> claim below was re-verified against committed blobs, not large dumps.
|
||
|
||
---
|
||
|
||
## Pre-session state
|
||
|
||
- Claimed session **0046** via `claim-session-id.sh` (max+1; the prior
|
||
advisory "0046" never pushed a claim). Active `--INPROGRESS` at start:
|
||
0026, 0027 (stale), **0045** (a genuinely in-flight parallel session).
|
||
- **engineering** (`wiggleverse/engineering`): one commit (`4ae1d03`
|
||
seed). §10.3 was PPE-gate-only — no two-tier / local-Docker content.
|
||
The repo now exists (the memory's "repo not yet created" was stale);
|
||
`README.md` is canonical, `~/projects/wiggleverse/ENGINEERING-GUIDE.md`
|
||
is the now-superseded original draft.
|
||
- **ohm-rfc** (`ben.stull/ohm-rfc`): Phase F / Track Δ (#37–#42) present
|
||
(PR #3). At session start a commit `2e403dd` ("ROADMAP #38/#40:
|
||
two-tier") was already on `main` via PR #4, authored 06:29 — i.e. the
|
||
prior corrupted turn's captured work had in fact landed, contradicting
|
||
the launch brief's "did NOT yet write into the published docs." It
|
||
updated the **#38 table row** + **#40 narrative bullet** only.
|
||
- **rfc-app** (`ben.stull/rfc-app`): v0.31.0 (meta-only topology). No
|
||
checked-in e2e suite; `scripts/seed_*` only. Backend = FastAPI/uvicorn
|
||
`app.main:app` :8000, env-driven (`config.py` requires Gitea + OAuth +
|
||
SECRET_KEY + webhook secret); frontend = Vite; email via SMTP env.
|
||
|
||
---
|
||
|
||
## Plan
|
||
|
||
- [x] Claim session id (first gesture).
|
||
- [x] Read SESSION-PROTOCOL.md + ROADMAP Phase F / Track Δ.
|
||
- [x] Handbook §10.3 → two-tier model (branch → PR → merge).
|
||
- [x] ohm-rfc ROADMAP #38 + note on #40 (verify done / complete coherence
|
||
via PR with Keychain PAT).
|
||
- [x] rfc-app Tier-1 local-Docker + e2e skeleton scaffold (if time).
|
||
- [x] Surface open decisions (#42, #37 OAuth, v1 timing) — not default.
|
||
- [x] Update memory.
|
||
- [x] Finalize + publish transcript LAST.
|
||
|
||
---
|
||
|
||
## Turn-by-turn arc
|
||
|
||
### Arc 1 — Orient + claim, detect the corruption
|
||
|
||
Read the protocol + ROADMAP. Claimed 0046. Early on, two reads of the
|
||
same `git log` disagreed (one showed `2e403dd` as HEAD, the next showed
|
||
the PR-#4 merge `ff4ff67`) — the flagged corruption, live. Adopted a
|
||
discipline for the rest of the session: verify against `git show <sha>` /
|
||
`git show origin/main:<path>` (committed blobs), never trust a large or
|
||
first-time dump.
|
||
|
||
### Arc 2 — Handbook §10.3 (engineering)
|
||
|
||
Rewrote §10.3 from "The PPE gate tests the combination a normal deploy
|
||
skips" → **"Two-tier testing: one suite, local Docker then PPE."** The
|
||
suite is environment-agnostic (one `BASE_URL` + a mail-sink API URL);
|
||
Tier 1 = local `docker compose` (backend + built frontend + fresh SQLite
|
||
+ Mailpit) in the dev loop + CI on every PR (needs no VM → not blocked on
|
||
PPE); Tier 2 = the same suite vs PPE on the VM as the deploy gate. The
|
||
N−1/N compat-gate steps were preserved and re-homed: they run **first in
|
||
Tier-1 Docker** (boot N−1 image → migrate → test → swap N image → test),
|
||
PPE as prod-like confirmation. Also nudged §10.6 (machinery list +
|
||
build-order). **Kept §10.4/§10.5/§10.6 numbering stable** because ROADMAP
|
||
references handbook sections by number (#38→§10.3, #40→§10.2–§10.3,
|
||
#41→§10.4, #42→§10.5). Branch → PR #1 → merged (`1f3c8e7`, merge
|
||
`4bab7a0`).
|
||
|
||
### Arc 3 — ohm-rfc ROADMAP coherence (#38 / #40)
|
||
|
||
Verified PR #4 (`2e403dd`) had already landed the core (#38 table row +
|
||
#40 narrative bullet), leaving two gaps: the **#38 detailed narrative**
|
||
(### 38 block, still PPE-only) and the **#40 table row**. Filled both on
|
||
branch `session-0046/two-tier-narrative-coherence` (commit `30326e3`):
|
||
#38 narrative now has the environment-agnostic contract + Tier 1/Tier 2 +
|
||
"Tier 1 depends on nothing; Tier 2 depends on #37"; #40 row notes the
|
||
compat gate runs first in Tier-1 Docker. Opened **PR #6**.
|
||
|
||
The Keychain PAT API path needed care: `ben/ohm-rfc` 307-redirects;
|
||
canonical is `ben.stull/ohm-rfc`. A POST hung once (killed it; it had in
|
||
fact created the PR — 409 on retry). Then **PR #6 would not merge**:
|
||
persistent `HTTP 405 "Please try again later"` for >2 min across retries
|
||
and a close/reopen, despite `mergeable: true` and no branch protection —
|
||
Gitea's conflict-check queue wedged server-side (a lingering lock, likely
|
||
aggravated by the hung request + concurrent-session load).
|
||
|
||
**Resolution discovered at finalize:** `main` later already contained my
|
||
exact commit `30326e3` — merged via **PR #5** (`roadmap/38-body-two-tier`,
|
||
merge `5760b5d`), a PR I did not open. A parallel actor (session 0045, or
|
||
a corrupted parallel execution of this one) re-merged my commit. PR #6
|
||
was thus redundant (empty diff vs base — the real reason for the 405);
|
||
**closed it as superseded by #5.** Net: `main` (5760b5d) carries the
|
||
complete two-tier ROADMAP treatment, coherent.
|
||
|
||
### Arc 4 — rfc-app Tier-1 e2e scaffold (#37/#38 groundwork)
|
||
|
||
Read the real runtime shape (`config.py`, systemd unit, `vite.config.js`
|
||
proxy, `email.py` SMTP env, OTC endpoints `POST /auth/otc/request` +
|
||
`/auth/otc/verify`). **Key finding:** Tier 1 cannot be a trivial
|
||
two-container compose — the backend has a hard **Gitea dependency** (reads
|
||
`META_REPO` content via the Gitea API, bot writes, `config.py` requires
|
||
Gitea + OAuth env). So a hermetic Tier 1 needs a disposable Gitea (real
|
||
container + bootstrap) or a stubbed gitea client — a genuine #38 design
|
||
decision, surfaced not defaulted. Also: auth in tests uses **OTC, not
|
||
OAuth** (the #37 caveat dissolves because #5/OTC shipped in v0.7.0).
|
||
|
||
Authored `e2e/` (9 files, additive, no existing code touched): `README.md`
|
||
(the design + the Gitea-dependency decision + the #40 compat-gate
|
||
mapping), `docker-compose.yml` (backend + built-frontend + fresh-SQLite
|
||
tmpfs + Mailpit + disposable Gitea + a bootstrap init, all `down -v`
|
||
disposable; Dockerfiles marked TODO(#38)), `.env.example` (OTC auth,
|
||
SMTP→Mailpit, `RFC_APP_INSECURE_WEBHOOKS=1`), `playwright.config.js`
|
||
(env-agnostic, reads `BASE_URL`), `tests/helpers/mailpit.js` (poll sink
|
||
API → extract OTC code / link; catch-all addressing → no provisioned
|
||
mailboxes), and two spec stubs (`smoke`, `otc-login`, `test.fixme`).
|
||
**Not a release** — no VERSION/CHANGELOG/pin/deploy. Pushed via SSH;
|
||
opened **PR #4 (rfc-app), left OPEN for review** (correct end state for a
|
||
framework-repo scaffold; should not auto-merge).
|
||
|
||
### Arc 5 — surface decisions, memory, finalize
|
||
|
||
Updated `project_engineering_handbook.md` memory (repo exists/canonical;
|
||
§10.3 = two-tier; open items refreshed). Surfaced the open decisions
|
||
(below). Wrote + published this transcript.
|
||
|
||
---
|
||
|
||
## Cut state (end of session)
|
||
|
||
| repo | state |
|
||
| --- | --- |
|
||
| engineering | `main` @ `4bab7a0` (PR #1 merge of `1f3c8e7`) — §10.3 two-tier testing + §10.6 touch-up |
|
||
| ohm-rfc | `main` @ `5760b5d` (PR #5 merge of `30326e3`, atop PR #4 `2e403dd`) — full two-tier #38 (table+narrative) + #40 (narrative+row). PR #6 closed (superseded). |
|
||
| rfc-app | branch `session-0046/e2e-tier1-scaffold` @ `a5a66e5`, **PR #4 OPEN** — `e2e/` Tier-1 scaffold. No release. |
|
||
| OHM live | **untouched** — no deploy this session (docs + groundwork). |
|
||
| ohm-rfc pin | **unchanged** (`.rfc-app-version` not bumped). |
|
||
| memory | `project_engineering_handbook.md` updated. |
|
||
|
||
| Track Δ ledger | Status |
|
||
| --- | --- |
|
||
| Two-tier refinement → handbook §10.3 | ✅ shipped (eng PR #1) |
|
||
| Two-tier refinement → ROADMAP #38/#40 | ✅ shipped (ohm-rfc PR #4 + #5) |
|
||
| #37 PPE | ⏸ gated on v1 (no VM work done) |
|
||
| #38 e2e suite | 🟡 Tier-1 scaffold opened (rfc-app PR #4, for review) |
|
||
| #39–#42 | ⏸ not started (chained, post-v1) |
|
||
|
||
---
|
||
|
||
## §19.2 / process candidates surfaced
|
||
|
||
1. **Gitea merge-queue wedge.** Persistent `405 "Please try again later"`
|
||
for >2 min, surviving close/reopen, with `mergeable:true`. The
|
||
conflict-check worker appears to stick after a killed/hung API request
|
||
under concurrent-session load. May affect ANY merge instance-wide
|
||
during such a window — operator may need to restart Gitea / its queue.
|
||
A client-side `--max-time` on every `curl` is now mandatory discipline
|
||
(one hung request poisoned the queue and held a server lock).
|
||
2. **PR identity under parallelism.** Two PRs (#5, #6) carried the *same*
|
||
commit sha into the same base; one merged, one became an empty-diff
|
||
orphan. Sessions should check `git branch -r --contains <their commit>`
|
||
before assuming their own PR is the merge path — content-addressing
|
||
means another actor can land "your" commit under a different branch.
|
||
3. **`config.py` Gitea-hardness vs. hermetic Tier-1.** The required
|
||
Gitea + OAuth env is the structural obstacle to a cheap local e2e.
|
||
Worth a framework note on a test-mode seam (the (A) real-Gitea vs (B)
|
||
stub decision) so #38 doesn't rediscover it cold.
|
||
|
||
---
|
||
|
||
## What lands on the operator's plate
|
||
|
||
1. **#42 auto-rollback model — GENUINELY OPEN, surfaced not defaulted.**
|
||
(a) always-on VM-side watcher (relaxes flotilla's laptop-only model for
|
||
one purpose) vs. (b) bounded bake during the operator's session
|
||
(10–15 min post-cutover, no daemon). Needed before #42 is built
|
||
(post-v1, after #41). Handbook §10.5 + ROADMAP #42 both flag it.
|
||
2. **#37 OAuth-per-host caveat — effectively RESOLVED, confirm.** Because
|
||
#5 email/OTC shipped (v0.7.0), PPE + the e2e suite log in via OTC, so
|
||
no per-host OAuth app is needed. The scaffold encodes OTC-only auth.
|
||
Flagging in case you still want an OAuth path tested on PPE.
|
||
3. **v1 timing.** Track Δ's live PPE-on-VM parts are gated on flotilla v1.
|
||
I stood up **nothing** on the VM (local scaffold only). Confirm v1
|
||
timing before any VM stand-up for #37.
|
||
4. **rfc-app PR #4 (e2e scaffold)** — review when ready; its README poses
|
||
the Tier-1 **Gitea-dependency decision** (real disposable Gitea +
|
||
bootstrap vs. stub the gitea client) that #38 must settle.
|
||
5. **Gitea merge-queue** may be wedged (see §19.2 #1) — a queue/Gitea
|
||
restart may be warranted; could affect session 0045 too.
|
||
|
||
---
|
||
|
||
## Prompt the operator can paste into the next Claude Code session
|
||
|
||
```
|
||
OHM driver session. Read ~/git/ohm-infra/SESSION-PROTOCOL.md and
|
||
~/projects/wiggleverse/ohm-rfc/ROADMAP.md (Phase F / Track Δ, #37–#42)
|
||
first. Claim your session id via claim-session-id.sh --start <now>.
|
||
|
||
Context from session 0046: the two-tier testing refinement is fully
|
||
landed — engineering handbook §10.3 (eng PR #1) and ohm-rfc ROADMAP
|
||
#38/#40 (ohm-rfc PR #4 + #5) both on main. The e2e suite is
|
||
environment-agnostic (one BASE_URL + mail-sink API URL): Tier 1 local
|
||
Docker per-PR (no VM), Tier 2 PPE as the deploy gate; the #40 compat
|
||
gate runs first in Tier-1 Docker.
|
||
|
||
A Tier-1 e2e scaffold is OPEN for review at rfc-app PR #4 (branch
|
||
session-0046/e2e-tier1-scaffold, new e2e/ dir, NOT a release). Its
|
||
README poses the one real #38 design decision to settle FIRST: how
|
||
Tier 1 satisfies the backend's hard Gitea dependency — a real
|
||
disposable Gitea container + bootstrap (high fidelity) vs. stubbing
|
||
the gitea client (fast). Auth in tests is OTC, not OAuth (the #37
|
||
OAuth caveat dissolved once #5/OTC shipped).
|
||
|
||
Possible next moves:
|
||
- Decide the Tier-1 Gitea approach, then flesh out rfc-app PR #4
|
||
(Dockerfiles + gitea bootstrap + real selectors) toward a passing
|
||
Tier-1 suite — this is #38 and does NOT need the VM.
|
||
- #37 (PPE on the VM) + everything live in Track Δ is GATED ON
|
||
flotilla v1 — confirm v1 timing with the operator before any VM work.
|
||
- #42 auto-rollback has an OPEN model decision (always-on VM watcher
|
||
vs bounded-bake-during-session) — surface it, don't default.
|
||
|
||
Heads-up: session 0046 hit a wedged Gitea merge-queue (persistent 405
|
||
"please try again later") and harness Bash/Read corruption — verify
|
||
git state against committed blobs (git show origin/main:<path>), put
|
||
--max-time on every curl, and check `git branch -r --contains <your
|
||
commit>` before assuming your own PR is the merge path (0046 had its
|
||
commit merged via someone else's PR). Session 0045 was also in flight.
|
||
```
|