234 lines
13 KiB
Markdown
234 lines
13 KiB
Markdown
# 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.
|
||
```
|