241 lines
11 KiB
Markdown
241 lines
11 KiB
Markdown
# Session 0035.0 — Transcript
|
||
|
||
> Date: 2026-05-28
|
||
> Goal: OHM roadmap driver, parallel-safe. Pick up unblocked work; the
|
||
> launch handoff named two fallback options if nothing was unblocked.
|
||
>
|
||
> Outcome: **Shipped flotilla v1.3.0 — a read-only `webhook` verb that
|
||
> formalizes the manual org-wide Gitea-hook sweep Session 0034 ran by
|
||
> hand. Verified live against OHM (clean). No rfc-app release, no OHM
|
||
> deploy (operator-tool code). Recorded that the other fallback option
|
||
> — the email-hygiene proposal — was already superseded by rfc-app
|
||
> v0.18.0.**
|
||
>
|
||
> Highlights:
|
||
> - flotilla `webhook expect/unexpect/expected/list/check` (SPEC §11.5,
|
||
> §12.1, §13.8); new `gitea.py` + `webhooks.py`; migration 005.
|
||
> - Live `webhook check --org`: clean, 6 repos swept, no strays;
|
||
> reproduced 0034's findings (ohm-meta hook present, `ben/ohm-rfc`
|
||
> 403→not-inspectable).
|
||
> - 203 tests green (19 new). Merged to main, tagged v1.3.0, pushed.
|
||
|
||
---
|
||
|
||
## Launch prompt
|
||
|
||
```
|
||
OHM roadmap driver, parallel-safe. Claim ID first; read SESSION-PROTOCOL §7
|
||
+ ohm-rfc/ROADMAP.md; verify live state. STATE (end of 0034): OHM live at
|
||
v0.29.0, flotilla v1.2.0, feature arc #26–#29 done. Most feature items
|
||
blocked (#21A/#20B date-gated ~06-04; #22 counsel; #31b screenshots;
|
||
#33/#34 operator-led). If nothing's unblocked, two clean options: (1) build
|
||
the flotilla webhook list/check verb (runbook §19.2 #4 — pure-flotilla,
|
||
formalizes the manual hook sweep this session did by hand; needs a small
|
||
"expected hook set" design call; flotilla v1.3.0); (2) the framework-side
|
||
email-hygiene minor in ohm-infra/RFC-APP-EMAIL-HYGIENE-PROPOSAL.md. Hard
|
||
rules unchanged.
|
||
```
|
||
|
||
---
|
||
|
||
## Plan
|
||
|
||
- [x] Claim session ID (0035), read SESSION-PROTOCOL §7 + ROADMAP.
|
||
- [x] Verify live state (pin, health, flotilla version).
|
||
- [x] Decide between the two fallback options.
|
||
- [x] Build flotilla `webhook` verb: schema + registry CRUD + gitea client
|
||
+ inspection/drift + CLI + tests.
|
||
- [x] Bump to v1.3.0; SPEC/CHANGELOG; live-verify; merge/tag/push.
|
||
- [x] Cross-repo coherence (ROADMAP #18, runbook note).
|
||
- [x] Finalize + publish transcript.
|
||
|
||
---
|
||
|
||
## Pre-session state
|
||
|
||
- **OHM live**: v0.29.0, healthy (`{"version":"0.29.0","status":"ok"}`),
|
||
deploys.id=40, at `ohm.wiggleverse.org`.
|
||
- **ohm-rfc pin** (`ben/ohm-rfc/.rfc-app-version`): `0.29.0`. Tip
|
||
`ec4ff4d`.
|
||
- **flotilla**: v1.2.0, `main` at `ef34ffe`. Clean working tree but for
|
||
an untracked `.claude/` (session tooling) + a stray leftover worktree
|
||
`.claude/worktrees/agent-ab800baf41f74f86d/` from a prior session.
|
||
- **Active sessions in the shared history repo at claim time**: 0026 and
|
||
0027 (both `--INPROGRESS`, claimed 13-46). Treated as stale/abandoned
|
||
(their substantive work — the audit-0026 hardening pins — already
|
||
landed); no overlap with this session's pure-flotilla surface.
|
||
|
||
---
|
||
|
||
## Turn-by-turn arc
|
||
|
||
### Arc 1 — Claim + orient
|
||
|
||
Claimed session **0035** via `claim-session-id.sh` (push accepted at
|
||
`1795030`). Read SESSION-PROTOCOL §7 (the claim/finalize/publish
|
||
discipline) and ROADMAP.md end-to-end, including the version-target table
|
||
and operating instructions.
|
||
|
||
Verified live state: pin 0.29.0, health ok, flotilla v1.2.0. Confirmed the
|
||
date-gated items (#21A/#20B, ~06-04) are still blocked (today is 05-28),
|
||
#22 needs counsel, #31b needs operator screenshots, #33/#34 are
|
||
operator-led. So the active-wave fallback applied: pick one of the two
|
||
named options.
|
||
|
||
### Arc 2 — Choosing between the two options
|
||
|
||
Read both option docs:
|
||
|
||
- **Option 2 (email-hygiene minor)** — `RFC-APP-EMAIL-HYGIENE-PROPOSAL.md`
|
||
was authored by Session 0013 (M.3) **before** #18/#20 shipped. Its three
|
||
surfaces — the `build_envelope` hardened-header helper, the
|
||
`outbound_emails` audit table, and webhook-handler mandatory-secret — all
|
||
**already landed in rfc-app v0.18.0** (per the #18/#20 version-target
|
||
rows). The proposal is largely superseded; only a webhook replay-window
|
||
remnant remains. Not clean.
|
||
- **Option 1 (flotilla webhook verb)** — pure-flotilla, in this repo, no
|
||
deploy, no new operator secret (the `GITEA_BOT_TOKEN` is already bound),
|
||
parallel-safe (no other active flotilla session), and directly formalizes
|
||
the manual sweep 0034 did by hand. Clean.
|
||
|
||
Chose Option 1. Recorded the Option-2-is-stale finding as a memory
|
||
(`project_email_hygiene_superseded.md`) so a future handoff doesn't
|
||
re-pick it.
|
||
|
||
### Arc 3 — The "expected hook set" design call
|
||
|
||
The launch prompt flagged a "small expected hook set design call."
|
||
Grounded it in the code + reality rather than blocking on the operator
|
||
(all sub-decisions were determined by existing principles):
|
||
|
||
- **Where the expected set lives** → the §13 deployment record, not the
|
||
CLI (the two-layer rule). Confirmed by reality: OHM's hook is on
|
||
`wiggleverse/ohm-meta`, but the deployment's `corpus_repo` /
|
||
`pin_source_repo` are both `ben/ohm-rfc` — so the expected hook
|
||
**cannot be derived** from existing fields; it must be **declared**.
|
||
- **Read-only vs auto-fix** → read-only in v1.3.0, mirroring §9's "report
|
||
loudly, never auto-rollback." An auto-remediate `webhook apply` is a
|
||
§19.2 candidate.
|
||
- **Inspection set** → expected-hook repos ∪ `corpus_repo` ∪
|
||
`pin_source_repo`, with `--org` extending to every repo under
|
||
`GITEA_ORG` (the full 0034 sweep).
|
||
|
||
### Arc 4 — Implementation
|
||
|
||
- **Migration 005** (`expected_webhooks` table: repo, url, events, active),
|
||
registry `ExpectedWebhook` + `set/unset/list_expected_webhook(s)`,
|
||
mirroring the `secret_refs`/`overlay_entries` shape.
|
||
- **`gitea.py`** — authenticated read client: `Authorization: token`,
|
||
reusing `pin.py`'s certifi SSL context + UA. `list_repo_hooks` +
|
||
paginated `list_org_repos`. 401/403 → `GiteaAuthError`.
|
||
- **`webhooks.py`** — resolves `GITEA_URL`/`GITEA_ORG` from the overlay and
|
||
reads `GITEA_BOT_TOKEN` transiently from Secret Manager (never persisted,
|
||
§3 invariant 1); `inspection_set`, `inspect_repos` (per-repo 403 tolerated
|
||
→ `not inspectable`, doesn't abort the sweep), `check_drift`
|
||
(missing/unexpected/mismatch/uninspectable; an un-inspectable repo with no
|
||
expectation is a warning, not a hard finding).
|
||
- **CLI** — `webhook expect/unexpect/expected/list/check`, `--json` on read
|
||
verbs, `--org` on list/check, non-zero exit on drift.
|
||
- **Tests** — `test_webhook.py`, 19 cases (registry CRUD, drift matrix,
|
||
hook parsing, full CLI surface with Gitea + Secret-Manager monkeypatched).
|
||
|
||
### Arc 5 — Docs, release, live verification
|
||
|
||
- SPEC §11.5 (the authenticated webhook read surface + read-only stance),
|
||
§12.1 verb inventory, §13.8 (OHM's expected set). CHANGELOG 1.3.0 with an
|
||
RFC-2119 `Upgrade steps:` block.
|
||
- VERSION + pyproject → 1.3.0.
|
||
- **Seeded OHM's expected hook** into the live flotilla DB:
|
||
`webhook expect ohm-rfc-app wiggleverse/ohm-meta https://ohm.wiggleverse.org/api/webhooks/gitea`.
|
||
- **Live verification** (read-only GETs against `git.wiggleverse.org`):
|
||
- `webhook list`: `wiggleverse/ohm-meta #2` present + active with 12
|
||
events; `ben/ohm-rfc` → `not inspectable (HTTP 403)` — exactly 0034's
|
||
finding.
|
||
- `webhook check`: **OK** (exit 0), scoped (2 repos) and `--org` (6 repos,
|
||
no strays).
|
||
- 203 tests green. Committed `fb9bd04`, FF-merged to `main`, tagged
|
||
**v1.3.0**, pushed `main` + tag to origin. Deleted the feature branch.
|
||
- Caught + unstaged a stray `.claude/worktrees/...` embedded repo before
|
||
committing; added `.claude/` to `.gitignore`.
|
||
|
||
### Arc 6 — Cross-repo coherence
|
||
|
||
- **ohm-rfc** ROADMAP #18 row: appended the v1.3.0 webhook-verb tooling
|
||
note. Committed `02d22fe`, pushed to origin.
|
||
- **ohm-infra** `EMAIL-AND-WEBHOOK-HARDENING-RUNBOOK.md`: annotated the
|
||
operator-execution sequence to point the by-hand sweep at the new verb.
|
||
(ohm-infra is not a git repo — local operational reference only.)
|
||
|
||
---
|
||
|
||
## Cut state (end of session)
|
||
|
||
| | |
|
||
| --- | --- |
|
||
| flotilla | `main` @ `fb9bd04`, tag **v1.3.0** pushed to origin. webhook verb shipped. |
|
||
| ohm-rfc | `main` @ `02d22fe` (ROADMAP #18 tooling note), pushed. Pin unchanged at 0.29.0. |
|
||
| ohm-infra | runbook annotated (local, uncommitted — not a git repo). |
|
||
| OHM live | deploys.id=40, v0.29.0, healthy. **Unchanged — no deploy this session.** |
|
||
| flotilla live DB | OHM expected-webhook seeded; `webhook check` OK. |
|
||
|
||
| Ledger | Status |
|
||
| --- | --- |
|
||
| flotilla v1.3.0 `webhook` verb (#18 runbook follow-up) | ✅ shipped + live-verified |
|
||
| Option 2 (email-hygiene minor) | ⏸ not picked — already superseded by rfc-app v0.18.0 |
|
||
|
||
---
|
||
|
||
## §19.2 candidates surfaced
|
||
|
||
1. **`webhook apply` (auto-remediate).** v1.3.0 is read-only. A future verb
|
||
could create a missing expected hook or delete a stray one (with the
|
||
`GITEA_WEBHOOK_SECRET` wired into the created hook's config). Deferred
|
||
until drift-by-hand becomes the bottleneck; carries write-risk that wants
|
||
the same care as `secret set`.
|
||
2. **Event-list assertion.** OHM's expected hook is declared with `events=*`
|
||
(URL + active + presence checked, exact event list not asserted).
|
||
Tightening to an explicit comma-list would catch event drift but needs
|
||
the operator to settle the canonical event set.
|
||
|
||
---
|
||
|
||
## What lands on the operator's plate
|
||
|
||
1. **Nothing blocking.** v1.3.0 is a local operator-tool release; no deploy,
|
||
no secret, no pin bump.
|
||
2. **Optional**: verify the `ben.stull/ohm-rfc` hook by hand (Gitea web UI) —
|
||
the bot can't read it (403), so `webhook check` reports it
|
||
`not inspectable` rather than confirming it. This is runbook #4, still an
|
||
operator self-check.
|
||
3. **Optional**: decide whether to tighten OHM's expected hook to an explicit
|
||
event list (§19.2 candidate 2 above).
|
||
|
||
---
|
||
|
||
## Prompt the operator can paste into the next Claude Code session
|
||
|
||
```
|
||
OHM roadmap driver, parallel-safe. Claim your own ID first (advisory only);
|
||
read ohm-infra/SESSION-PROTOCOL §7 + ohm-rfc/ROADMAP.md; verify live state.
|
||
|
||
STATE (end of 0035): OHM live at v0.29.0 (deploys.id=40, healthy), ohm-rfc
|
||
pin 0.29.0, flotilla now v1.3.0. Session 0035 shipped the flotilla webhook
|
||
list/check verb (pure-flotilla, no deploy) and live-verified it — the org
|
||
hook posture is clean.
|
||
|
||
Most feature items still blocked: #21A / #20B date-gated (~06-04, so likely
|
||
unblocked NOW or within days if it's on/after 06-04 — check the date and the
|
||
DMARC rua data); #22 needs operator-drafted + counsel-reviewed copy; #31b
|
||
needs operator screenshots; #33/#34 operator-led.
|
||
|
||
If #21A (Amplitude deep audit — needs ~1wk of v0.15.0 data) or #20B (email
|
||
deliverability follow-up — needs ~1wk of DMARC p=none rua data) is now
|
||
date-unblocked, that's the cleanest feature work. Otherwise check the
|
||
ROADMAP for anything newly shippable. Do NOT re-pick the email-hygiene
|
||
proposal (RFC-APP-EMAIL-HYGIENE-PROPOSAL.md) — its content already shipped
|
||
in rfc-app v0.18.0 (see the #18/#20 rows + the memory).
|
||
|
||
Hard rules unchanged: never ask for secret bytes; transcript is the final
|
||
step; deliver the next handoff in chat before publishing.
|
||
```
|