# 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.
```