add 0054/SESSION-0054.0-TRANSCRIPT-2026-06-01T03-24--2026-06-01T03-25.md + replace placeholder/variant SESSION-0054.0-TRANSCRIPT-2026-06-01T03-24--INPROGRESS.md

0054/SESSION-0054.0-TRANSCRIPT-2026-06-01T03-24--2026-06-01T03-25.md

@@ -0,0 +1,233 @@
+# Session 0054.0 — Transcript
+
+> Date: 2026-06-01
+> Goal (as launched): walk the full engineering runbook end-to-end as a
+> *test run* — fake-build a throwaway app and deploy it for real, then tear
+> it down. Discover whether the runbook actually works for a brand-new app.
+>
+> Outcome: **The runbook's design+build half was walked for real on a
+> throwaway URL-shortener (`wiggle-snip`): prototype → SPEC v0.0.1 → ROADMAP
+> → standard-stack build with 14 green tests + a building Vite frontend +
+> `/api/health`. The deploy half was NOT executed** — at the deploy gate the
+> operator redirected: don't deploy from this session, instead (a) hand off a
+> reusable prompt for a future operator-driven deploy, and (b) use what we'd
+> learned to scope a new **`launch-app` skill suite** that takes an engineer
+> from "I want to build an app" to a verified pre-prod deploy. That suite was
+> spec'd: **`wiggleverse/engineering/launch-app/SPEC.md` v0.0.1 + ROADMAP.md**,
+> with `flotilla-core` extraction as the critical-path Slice 1. No cloud
+> resources, Gitea repos, or deploys were created.
+>
+> **Scope-change / publication note (transcript-honest):** this session began
+> *off the record*. At the deploy gate the operator explicitly chose "don't
+> publish a transcript" — correct for a throwaway deploy test. But the session
+> then pivoted into real org-level tooling design (the `launch-app` spec), and
+> the operator reversed the call: "the scope of this conversation changed, so
+> let's do a proper transcript." Hence this file. The earlier
+> off-the-record decision is recorded here precisely because it was reversed —
+> the record shows the judgement, not a tidied version of it.
+>
+> **Timestamp caveat:** the start-gesture claim (SESSION-PROTOCOL §"session
+> start") was NOT run at the true session start — the session opened in the
+> `ecomm` working dir as an off-the-record test and was elevated to a
+> published transcript only at the end (the protocol's "claims its ID at
+> publish time" path). The `03-24`/`03-25` stamps are the claim/finalize
+> window; the actual work spanned roughly the preceding hour.
+
+---
+
+## Pre-session state
+
+- No `wiggle-snip` anything existed. Working dir was
+  `~/projects/wiggleverse/ecomm` (an unrelated project); this session never
+  touched ecomm.
+- The runbook of record: `~/projects/wiggleverse/engineering/README.md`
+  (the canonical handbook; `~/projects/wiggleverse/ENGINEERING-GUIDE.md` is
+  the now-superseded draft). Read in full this session.
+- `scaffold-gcp-project` skill present at
+  `~/.claude/skills/scaffold-gcp-project/SKILL.md` — the one existing
+  cloud-foundation skill.
+- `ohm-rfc-app-flotilla` present — OHM's operator CLI, the template any new
+  deployment's flotilla would fork from.
+
+## Plan
+
+Walk the guide §1 lifecycle for a deliberately trivial app: idea →
+prototype (§2) → SPEC (§3) → ROADMAP (§7) → build on the standard stack
+(§4, §8) → deploy via flotilla (§8, §9) → verify `/api/health` → tear down.
+The app is a vehicle to exercise the *pipeline*, so it was chosen for
+minimal domain complexity and maximal stack coverage.
+
+## Turn-by-turn arc
+
+### Arc 1 — Choose the test app
+Grounded in the guide first (read the engineering-pattern memory + handbook
+§1–§9). Proposed four candidates via AskUserQuestion (guestbook, deploy
+counter, link shortener, quote board), framed around which best exercises
+every layer (a migration + WAL write, an API, a Vite build, a health check)
+with least domain noise. **Operator chose the link shortener** — it earns a
+redirect route + slug generation without real complexity.
+
+### Arc 2 — Reconnaissance: is the runbook even tractable for a new app?
+Before building, inspected `ohm-rfc-app-flotilla`. **Key finding: flotilla
+is OHM-specific, not generic** — its README says each deployment forks its
+own `<deployment>-flotilla`, and a generic library is a §19.2 candidate
+"once a second deployment exists." Confirmed the deploy *shape* matches the
+standard stack (`plan.py`/`deploy.py` run `backend/.venv/bin/pip install` +
+`cd frontend && npm ci && npm run build` → `systemctl restart` → verify
+`/api/health`), but it is OHM-coupled in two spots: the `pin.py` hard
+`rfc-app >= 0.2.3` floor and the `audit.py` rfc-app-lockfile target. Noted
+that **this test run is itself the "second deployment" the guide predicted**
+would justify extracting a generic flotilla.
+
+### Arc 3 — Prototype (guide §2)
+Vibe-coded `~/projects/wiggleverse/wiggle-snip-prototype/prototype.py`
+(stdlib-only http.server + sqlite). **Wrong turn:** left a nonsense
+expression `for _ in rangeate(10) if False else range(10)` in the slug
+minter; caught and cleaned to `range(10)` before running. Ran it and
+exercised every endpoint: health, shorten (201), redirect (302 + Location),
+unknown slug (404), bad URL (400), bad JSON (400), hit-counter increment.
+The proto's job was done the moment the contracts were describable (§2).
+
+### Arc 4 — SPEC + ROADMAP (guide §3, §7)
+Matched the house style (numbered §, citable invariants, deferred-topics
+section) by reading `rfc-app/SPEC.md` first. Wrote `wiggle-snip/SPEC.md`
+v0.0.1 — invariants: opaque slugs (§3.1), no slug reuse (§3.3), fail-loud
+collision (§3.4), validate-before-store (§4.1), unknown-slug-is-404 (§5.1),
+health-reports-version (§6.1), forward-only schema (§2.1). Then
+`ROADMAP.md`, 5 slices with a next-session brief.
+
+### Arc 5 — Build on the standard stack (guide §4, §8)
+Mirrored `rfc-app/backend` layout. Built `backend/` (FastAPI, `db.py`
+migration runner cloned from rfc-app's shape, `001_init.sql`, slug minter
+with an *injected* randomness seam for testability, `main.py` routes) +
+`frontend/` (vanilla Vite). **Wrong turns / friction:**
+- A `cd`-in-compound Bash call and an `rm -rf … &` background call were both
+  permission-denied; reworked to absolute paths + foreground.
+- FastAPI rejected the redirect route's `RedirectResponse | JSONResponse`
+  union return type; fixed with `response_model=None`.
+14 backend tests pass (incl. the collision-retry-then-fail-loud path and a
+slug-opacity check). Frontend `npm run build` produces `dist/`; lockfile
+committed (flotilla's `npm ci` needs it). Verified the full stack on one
+origin via curl: health reports version, homepage + assets served from
+`dist/`, shorten → 201, redirect → 302, unknown → 404. Added `.gitea/
+workflows/test.yml`, README, `.gitignore`, `VERSION`.
+
+### Arc 6 — The deploy gate, and the first pivot
+Presented the deploy gate honestly: a real deploy creates a billable GCP
+project + VM, real Gitea repos, and (per guide §6) a public transcript.
+Operator had earlier chosen "full real deploy," but at the trigger
+**redirected**: do NOT deploy from this session. Instead, produce a
+self-contained prompt for a *fresh* operator-driven session that uses
+`scaffold-gcp-project` + the runbook to deploy `wiggle-snip` and capture
+skill-improvement feedback. Also chose **"don't publish"** a transcript
+(off-the-record test). Delivered that prompt. Teardown (the planned final
+step) became moot — nothing was provisioned.
+
+### Arc 7 — Skill-scope question → the second pivot
+Operator asked whether `scaffold-gcp-project` currently covers (a) asking
+about the app, (b) defining+validating topology, (c) all resource
+names/locations. Read the SKILL.md and answered precisely: it asks only for
+repo-name/org/billing/region/profile; it is explicitly **"cloud foundation
+only,"** stops before the VM, validates only the project-id regex, and
+leaves topology + most resource names to the operator/flotilla. Identified
+the **gap**: the middle band between "cloud foundation scaffolded" and "app
+deployed" has no skill.
+
+### Arc 8 — Scope the `launch-app` suite, and decide its shape
+Explored the full scope of a suite that takes "I want to build an app" →
+deployed (≥ pre-prod), for a technical-but-not-GCP-expert engineer. Read
+guide §10–§12 + the `register-ohm.sh` deployment record to ground the
+target topology and the full resource-name set. Surfaced two genuine
+forks via AskUserQuestion. **Operator decided:**
+- **Milestone = PRE-PROD ONLY** (no prod, no Stage-2 blue/green/canary).
+  This collapses the target to a single disposable pre-prod env =
+  topologically the §8 single-VM shape, and drops all of §10.6 from v1.
+- **Extract `flotilla-core`** (not fork-per-app) — the real fix the guide's
+  §19.2/§11 "second deployment" trigger predicts.
+
+### Arc 9 — Write the suite's SPEC + ROADMAP, and the build prompt
+Wrote `wiggleverse/engineering/launch-app/SPEC.md` v0.0.1 (orchestrator
+state machine, `deployment.toml` schema + fail-closed validation rules,
+per-phase-skill responsibilities, the `flotilla-core` extraction contract
+incl. its §7.3 "OHM still deploys" regression oracle, and the teaching/
+safety invariants incl. the hard-secrets rule §8.3) + `ROADMAP.md` (5
+slices, `flotilla-core` first, `wiggle-snip` as the dogfood fixture).
+Delivered a paste-ready prompt to kick off the Slice-1 build session.
+Updated agent memory (project notes for the suite + the fixture).
+
+### Arc 10 — Scope changed → produce this transcript
+Operator: "the scope of this conversation changed, so let's do a proper
+transcript." Reversed the Arc-6 off-the-record call. Read SESSION-PROTOCOL,
+claimed **0054** via `claim-session-id.sh`, finalized + published this file.
+
+## Cut state (end of session)
+
+- **`~/projects/wiggleverse/wiggle-snip`** — built + tested, NOT deployed.
+  backend (FastAPI/SQLite-WAL/migration `0001_init`/`/api/health`), frontend
+  (Vite→dist), 14 tests green, CI defined, `SPEC.md` v0.0.1, `ROADMAP.md`.
+- **`~/projects/wiggleverse/wiggle-snip-prototype`** — throwaway proto.
+- **`~/projects/wiggleverse/engineering/launch-app/`** — `SPEC.md` v0.0.1 +
+  `ROADMAP.md` (NEW; local working copies, not yet committed/PR'd into the
+  `wiggleverse/engineering` repo — that's an operator gesture).
+- **No** GCP project, VM, Gitea repos, ADC change, or deploy. Nothing to
+  tear down.
+- Two paste-ready prompts handed to the operator in-chat: (1) deploy
+  `wiggle-snip` via scaffold-gcp-project + runbook; (2) build `launch-app`
+  Slice 1 (`flotilla-core` extraction).
+
+## §19.2 / process candidates surfaced
+
+- **`flotilla-core` extraction** — the headline. flotilla is OHM-coupled
+  (`pin.py` rfc-app floor, `audit.py` lockfile target, OHM names). This test
+  run is the literal "second deployment" that justifies pulling the generic
+  9-phase engine into a reusable package + thin `deployment.toml`. Decided:
+  do it (launch-app ROADMAP Slice 1). Regression oracle = OHM still deploys
+  through the core (launch-app SPEC §7.3).
+- **The `scaffold-gcp-project` → deploy gap** — no skill owns topology
+  definition/validation or the full resource-name set; `launch-app` SPEC
+  §6.6 (`define-deployment`) + §6.7 (`provision-vm`) are the proposed fill.
+- **`scaffold-gcp-project` should confirm, not assume, the standard stack**
+  (launch-app SPEC §6.5) — it currently has no app-intake interview.
+
+## What lands on the operator's plate
+
+- Decide whether to commit/PR the new `engineering/launch-app/` SPEC+ROADMAP
+  into `wiggleverse/engineering` (operator gesture).
+- When ready, run either handed-off prompt: deploy `wiggle-snip` to validate
+  the runbook, or start the `flotilla-core` extraction (Slice 1).
+- Optional: fold a pointer to `launch-app` into the engineering guide's
+  table of contents / §12 so it's discoverable.
+
+## Prompt the operator can paste into the next Claude Code session
+
+```
+Build the launch-app skill suite — Slice 1: extract flotilla-core.
+
+Read first:
+- Suite spec:    ~/projects/wiggleverse/engineering/launch-app/SPEC.md  (esp. §7 flotilla-core, §9 invariants, §10 out-of-scope)
+- Suite roadmap: ~/projects/wiggleverse/engineering/launch-app/ROADMAP.md (Slice 1 is the task)
+- Rulebook:      ~/projects/wiggleverse/engineering/README.md  (§8 stack, §8.4 cloud profile)
+- Extract FROM:  ~/projects/wiggleverse/ohm-rfc-app-flotilla (note pin.py, audit.py, deploy.py, registry.py)
+- Dogfood fixture (built + tested): ~/projects/wiggleverse/wiggle-snip
+
+Task: pull the generic 9-phase deploy engine out of ohm-rfc-app-flotilla into
+an installable flotilla-core consuming a deployment.toml (schema = SPEC §5.1),
+carrying NO app-specific defaults. De-OHM it (SPEC §7.2): remove the pin.py
+rfc-app >=0.2.3 floor (pin floor → optional per-app config, default none);
+generalize audit.py off rfc-app lockfiles; parameterize the OHM data-dir /
+DB-filename / user-agent names.
+
+DEFINITION OF DONE (SPEC §7.3 — do not skip): repoint OHM's flotilla to consume
+flotilla-core as a thin shim and PROVE OHM STILL DEPLOYS through it unchanged.
+The existing OHM deployment is the regression oracle; new tests alone are NOT done.
+
+Scope guard (SPEC §10): pre-prod, single-environment only. NO slots / ramp /
+promote / rollback / compat-gate / watcher (that's guide §10). If you start
+adding any, stop.
+
+Process: spec-driven (cite SPEC/guide § in commits; branch → PR, not straight to
+main). Hard secrets rule (guide §6 / SPEC §8.3): never put a secret byte in the
+session; hand the operator stdin-piped commands. At the end, hand over the
+Slice-2 prompt, and note anything in the SPEC that turned out wrong/underspecified
+against the real code so we can correct it before Slices 2–5.
+```

0054/SESSION-0054.0-TRANSCRIPT-2026-06-01T03-24--INPROGRESS.md

@@ -1,22 +0,0 @@
-# Session 0054.0 — Transcript
-
-> Date: 2026-06-01
-> Start: 2026-06-01T03-24 (PST implied)
-> Status: **PLACEHOLDER — claimed at session start; finalized at session end.**
->
-> This file reserves session ID 0054. The driver replaces this body
-> with the full transcript before publishing, and renames the file to
-> its final SESSION-0054.0-TRANSCRIPT-2026-06-01T03-24--<end>.md form.
-
----
-
-## Launch prompt
-
-```
-Let's go through the process of trying to launch a new app using the engineering runbook. This is a test run - we'll tear it all down after we're done. Any ideas for what app we should fake build to first deploy it?
-
-[Session anchored in the ecomm working dir; began as an off-the-record runbook
-test, then the operator elevated it to a published transcript once the scope
-changed from a throwaway deploy test to scoping the launch-app skill suite.]
-
-```