262 lines
13 KiB
Markdown
262 lines
13 KiB
Markdown
# Session 0037.0 — Transcript
|
||
|
||
> Date: 2026-05-28 → 2026-05-29 (spanned midnight, PST implied)
|
||
> Goal: Operator-driven philosophy session that grew into shipping
|
||
> content + a framework doc release. No rfc-app feature code change.
|
||
>
|
||
> Outcome: **Three things shipped + deployed to OHM.**
|
||
> (1) `ohm-rfc/PHILOSOPHY.md` reframed off the model-training story onto
|
||
> "software is built operationalizing OHM concepts"; new
|
||
> `ohm-rfc/OPERATIONAL-MODEL.md` capturing the concept→mechanic
|
||
> operational layer + its governance.
|
||
> (2) `OPERATIONAL-MODEL.md` surfaced on-site at
|
||
> `/docs/specs/operational-model` (deploys.id=41) via the existing
|
||
> configurable specs surface — no rfc-app code change.
|
||
> (3) `rfc-app v0.30.0` — the user guide (`DOCS.md`, `/docs/user-guide`)
|
||
> brought back in sync with the shipped app after ~23 versions of drift
|
||
> (deploys.id=42). Pin 0.29.0 → 0.30.0.
|
||
>
|
||
> Notes:
|
||
> - This session did **not** run the start-gesture claim; ID 0037 was
|
||
> claimed at session end (the §83/§7 fallback). Start time is
|
||
> **approximate**.
|
||
> - **Re-finalized** (this is the second publish). The first publish
|
||
> covered Arcs 1–5 (the philosophy doc work); Arcs 6–7 + the v0.30.0
|
||
> release landed after and are folded in here.
|
||
> - The shared-checkout / parallel-session hazard recurred (Arc 6) — a
|
||
> concurrent session's uncommitted `ROADMAP.md` blocked a pull; handled
|
||
> per the worktree-for-parallel-git discipline.
|
||
|
||
---
|
||
|
||
## Pre-session state
|
||
|
||
- **OHM live**: rfc-app v0.29.0, deploys.id=40, healthy.
|
||
- **ohm-rfc pin**: 0.29.0. **ohm-rfc HEAD**: `02d22fe` (Session 0035.0).
|
||
- **Live `/api/philosophy`**: the original model-training-framed
|
||
`PHILOSOPHY.md`.
|
||
- The operator opened with a roadmap question that became an extended
|
||
design conversation about what OHM is *for*.
|
||
|
||
---
|
||
|
||
## Turn-by-turn arc
|
||
|
||
### Arc 1 — Roadmap status read
|
||
|
||
Read `ROADMAP.md` end-to-end; reported the Phase A–E feature arc
|
||
(#1–#16) shipped and the remaining tail (#22 consent copy, #21A
|
||
Amplitude audit, #18/#20 ops, #33/#34 naming, #31b/#25 polish). Flagged
|
||
the #27/v0.24.0 row as reading stale against the 0.29.0 pin.
|
||
|
||
### Arc 2 — "Is OHM a good idea?" → the thesis
|
||
|
||
Operator supplied the thesis: an **ethical social and content platform**
|
||
("wiggling through the world") where defining the concepts (informed
|
||
consent, etc.) drives the engagement model. Pressure-tested it: the real
|
||
insight is that existing platforms run on *implicit* definitions
|
||
("engagement = clicks") and that's the source of harm. Pushed on three
|
||
risks: the definition→mechanic gap, left/right-brain as a credibility
|
||
liability, and the who-defines governance/legitimacy problem.
|
||
|
||
### Arc 3 — Operational RFCs (the architecture crystallizes)
|
||
|
||
Operator: "we also need RFCs for the operational model, not just
|
||
concepts." Settled the shape: **two RFC kinds** — concept (declarative
|
||
contract) and operational (mechanic; must cite the concept it serves;
|
||
carries a validation/sunset clause). Traceability makes "is this
|
||
ethical?" checkable. Then the governance edge: collaboration ≠ unowned;
|
||
the real artifact is the **ratification procedure**; the concept layer is
|
||
the spine; keep accountability locatable. Left open deliberately: the
|
||
tie-break when two co-authors both argue their mechanic serves the
|
||
concept.
|
||
|
||
### Arc 4 — Capturing it as docs
|
||
|
||
Recommended a **separate doc + one-line bridge** over weaving in. Wrote
|
||
`OPERATIONAL-MODEL.md` + a forward-pointer in `PHILOSOPHY.md`. Two
|
||
operator corrections reshaped `PHILOSOPHY.md`: (1) "software is *built
|
||
using* OHM concepts, not just models trained on it" → added the
|
||
"Two ways a system can consume OHM" section; (2) "drop model training
|
||
entirely" → confirmed scope ("drop training, keep co-authoring") and
|
||
rewrote the opening, three-panel diagram, asymmetry, code's-dictionary,
|
||
and humility note. Kept verbatim: the human+machine co-authoring
|
||
mechanism and the POSIX/IETF/HTTP analogy.
|
||
|
||
### Arc 5 — Commit + deploy of the philosophy reframe
|
||
|
||
Committed both docs (`9a4277c`), pushed `origin`. Traced the non-obvious
|
||
content-deploy path: `PHILOSOPHY.md` is served from the VM file at
|
||
`PHILOSOPHY_PATH=/opt/ohm-rfc-app/meta-content/PHILOSOPHY.md` (a clone of
|
||
`ben.stull/ohm-rfc`), **not** baked by `flotilla deploy`. The clone was
|
||
frozen at an ancient commit (`eae9dc5`, pin 0.2.1 era) and never pulled.
|
||
`git pull --ff-only` on the VM (IAP SSH) fast-forwarded it (landing on
|
||
`6cf7e41` — parallel session 0036.0's ROADMAP reconcile sat on top of my
|
||
commit). The backend caches the file (`philosophy.load()`; `refresh()`
|
||
exists but is **never called**), so a restart was needed —
|
||
`systemctl restart ohm-rfc-app.service`. Verified `/api/philosophy`
|
||
served the rewrite. *(First transcript publish happened here.)*
|
||
|
||
### Arc 6 — Operational model on the live site (deploys.id=41)
|
||
|
||
Operator: "add operational model to the live site." Found the clean path
|
||
with **no rfc-app code change**: the `/docs/specs/<name>` surface
|
||
(`backend/app/docs_specs.py`, from roadmap #30) renders arbitrary
|
||
markdown fetched at runtime from a Gitea raw URL, configured by the
|
||
`OHM_DOCS_SPECS` overlay var (default = rfc-app SPEC + flotilla SPEC).
|
||
|
||
Hit the **shared-checkout hazard**: the `ohm-rfc` checkout had a parallel
|
||
session's uncommitted `ROADMAP.md` (its new item #35, operator RFC
|
||
authoring). Set up an isolated worktree for the one-file philosophy-link
|
||
fix, then the operator said "hang tight while that session finishes" —
|
||
cleaned up the worktree and **paused**. Once the operator confirmed the
|
||
other session pushed, resumed on the now-clean checkout:
|
||
- Fixed the `PHILOSOPHY.md` forward-pointer from a relative
|
||
`./OPERATIONAL-MODEL.md` (404s in the rendered page) to the route
|
||
`/docs/specs/operational-model` (`d79ce46`); symmetric fix in
|
||
`OPERATIONAL-MODEL.md` → `/philosophy` (`5861e9e`).
|
||
- `flotilla overlay set OHM_DOCS_SPECS` = the two default SPECs + the
|
||
operational-model entry (raw URL on `ben.stull/ohm-rfc`). Confirmed the
|
||
JSON value round-trips correctly through flotilla's always-quoting
|
||
`.env` materializer (`_escape_env_value`) + python-dotenv.
|
||
- VM `meta-content` pull (for the philosophy link) + `flotilla deploy`
|
||
(id=41, v0.29.0 redeploy materializing the new env + restart).
|
||
- Verified: `/api/docs/specs/manifest` lists "OHM Operational Model";
|
||
`/docs/specs/operational-model` serves the body; the philosophy link
|
||
resolves.
|
||
|
||
### Arc 7 — User-guide drift review + rfc-app v0.30.0 (deploys.id=42)
|
||
|
||
Operator: "review the user guide and update anything if it's drifted."
|
||
The framework user guide is `rfc-app/DOCS.md`, served at
|
||
`/docs/user-guide` from the **deployed tag** (no `DOCS_PATH` override).
|
||
Fanned out 3 read-only Explore agents over `rfc-app` (auth flow; propose
|
||
+ contribute surfaces; roles/admin/notifications), each cited to code, to
|
||
ground the rewrite and avoid trading old drift for new.
|
||
|
||
Finding: the guide is **mostly accurate** — roles, branches, PRs,
|
||
graduation, AI-in-chat, and the full notifications system (inbox, badges,
|
||
toasts, the four email categories, digest, quiet hours, watch states) are
|
||
all genuinely shipped, not aspirational. Drift was concentrated:
|
||
- **"Signing in"** still described the pre-OTC email *allowlist*. Rewrote
|
||
for email + one-time-code (v0.7.0), optional passcode (v0.10.0),
|
||
trust-device 30d (v0.11.0), optional Turnstile (v0.12.0, deployment-
|
||
gated), and the beta-request → `pending` → admin-`granted` gate
|
||
(v0.8.0), plus admin-create + invite-claim (v0.17.0). Allowlist is
|
||
vestigial (empty by default).
|
||
- **"Proposing a new RFC"**: four → five fields (optional use-case #26;
|
||
AI tag-suggestion disclosure #27).
|
||
- **"Roles & permissions"**: added the `pending` state.
|
||
- New **"Invitations, cross-references, and contribution requests"**
|
||
(#12 owner invites; #28 auto-link / create-RFC / ask-to-contribute).
|
||
- New **"Privacy and cookies"** (#11 / #13).
|
||
|
||
Shipped as **rfc-app v0.30.0** (docs-only minor): `VERSION` +
|
||
`frontend/package.json` bumped (lockfile `version` left at its existing
|
||
stale 0.24.0 — `npm ci` checks the dep tree, not the project version, and
|
||
prior releases did the same), CHANGELOG entry, commit `1558cc3`, tag
|
||
`v0.30.0` pushed to **origin + benstull** (the VM deploys from the
|
||
mirror). Pin `0.29.0 → 0.30.0` (`edf4a85`). `flotilla deploy` id=42,
|
||
`/api/health` → 0.30.0. Verified the live guide reflects all sections and
|
||
the stale allowlist text is gone.
|
||
|
||
---
|
||
|
||
## Cut state (end of session)
|
||
|
||
| | |
|
||
| --- | --- |
|
||
| ohm-rfc | HEAD `edf4a85` (pin 0.30.0). Content commits this session: `9a4277c` (philosophy reframe + OPERATIONAL-MODEL.md), `d79ce46` + `5861e9e` (cross-link fixes). Pushed `origin`. |
|
||
| rfc-app | **v0.30.0** (`1558cc3`) on main; tag pushed `origin` + `benstull`. Docs-only (DOCS.md + VERSION + package.json + CHANGELOG). |
|
||
| OHM live | deploys.id=**42**, v0.30.0, healthy. (id=41 was the v0.29.0 redeploy that materialized the `OHM_DOCS_SPECS` env for the operational-model surface.) |
|
||
| ohm-rfc pin | 0.30.0. |
|
||
| /api/philosophy | rewritten philosophy + route cross-link. |
|
||
| /docs/specs/operational-model | live ("OHM Operational Model"). |
|
||
| /docs/user-guide | v0.30.0 updated guide. |
|
||
|
||
| Item | Status |
|
||
| --- | --- |
|
||
| PHILOSOPHY.md reframe + OPERATIONAL-MODEL.md | ✅ shipped + deployed (no version) |
|
||
| OPERATIONAL-MODEL.md on-site (/docs/specs) | ✅ shipped + deployed (id=41) |
|
||
| rfc-app v0.30.0 — user-guide drift sync | ✅ shipped + deployed (id=42) |
|
||
|
||
---
|
||
|
||
## §19.2 candidates surfaced
|
||
|
||
1. **`meta-content` is not synced by any gesture.** The VM's
|
||
`/opt/ohm-rfc-app/meta-content` clone (source for `PHILOSOPHY_PATH`)
|
||
had drifted ~27 minor versions and was only updated by a hand
|
||
`git pull` this session. Candidate: a `flotilla content sync
|
||
<deployment>` verb (pull meta-content + restart / hit a refresh
|
||
endpoint).
|
||
2. **`philosophy.refresh()` / `docs.refresh()` are dead code.** The
|
||
in-process cache is only cleared by process restart; the documented
|
||
"reconciler sweep calls `force=True`" has no caller. Wire a periodic
|
||
refresh or delete the dead code + fix the docstring.
|
||
3. **Two homes for deployment docs, two update mechanics.**
|
||
`PHILOSOPHY.md` is served from the meta-content file (updates via
|
||
meta-content pull + restart); `DOCS.md` is served from the **deployed
|
||
rfc-app tag** (updates require a release + deploy, as v0.30.0 did).
|
||
The generic `/docs/specs` surface (`OHM_DOCS_SPECS`) is a third path —
|
||
runtime gitea-raw fetch with a 5-min TTL, no deploy needed. Worth a
|
||
short note in DEPLOYMENTS.md so the next operator knows which lever
|
||
updates which doc. (The operational-model doc rides `/docs/specs` and
|
||
thus updates with no deploy — but lands under the "Specs" nav label,
|
||
a slight semantic stretch; a dedicated companion route would need a
|
||
framework code change.)
|
||
4. **Shared-checkout / parallel-session hazard recurred** (Arc 6). A
|
||
concurrent session's uncommitted `ROADMAP.md` blocked a pull;
|
||
reinforces the worktree-for-parallel-git discipline for any hands-on
|
||
git in the shared checkout while other sessions run.
|
||
|
||
---
|
||
|
||
## What lands on the operator's plate
|
||
|
||
1. **The open governance tie-break** (Arc 3) is unanswered by design —
|
||
"when two co-authors both argue their mechanic serves the cited
|
||
concept, what breaks the tie?" That answer *is* the platform's
|
||
governance model; settle it consciously, likely as the first
|
||
operational RFC.
|
||
2. **left-brain/right-brain caution** (Arc 2): hold as a frame under
|
||
test, not a poured foundation.
|
||
3. **Roadmap item #35** (operator RFC authoring from a Claude Code
|
||
session) was added to `ROADMAP.md` by a parallel session, not this
|
||
one — noted here only so the cross-session record is coherent.
|
||
4. Nothing else pending — all three deliverables shipped + verified.
|
||
|
||
---
|
||
|
||
## Prompt the operator can paste into the next Claude Code session
|
||
|
||
```
|
||
You are an OHM driver session. Reserve your own session ID
|
||
(~/git/ohm-infra/scripts/claim-session-id.sh --start <now>) — the number
|
||
is advisory. Read ohm-rfc/ROADMAP.md + its "Operating instructions" block.
|
||
|
||
Recent context (Session 0037.0, 2026-05-28→29): a content + docs session.
|
||
OHM is now on rfc-app v0.30.0 (deploys.id=42, healthy). Shipped:
|
||
(1) ohm-rfc/PHILOSOPHY.md reframed off model-training onto "software is
|
||
built operationalizing OHM concepts"; new ohm-rfc/OPERATIONAL-MODEL.md
|
||
(concept→mechanic operational layer + governance), live at
|
||
/docs/specs/operational-model; (2) rfc-app v0.30.0 — the /docs/user-guide
|
||
(DOCS.md) brought back in sync with the shipped app (sign-in/OTC, propose
|
||
use-case field, pending state, invitations, cross-references, privacy).
|
||
|
||
Deployment-content levers to know:
|
||
- PHILOSOPHY.md → VM meta-content git clone (PHILOSOPHY_PATH); NO gesture
|
||
syncs it (it had drifted to 0.2.1). Update = `git -C meta-content pull`
|
||
+ `systemctl restart ohm-rfc-app` via IAP SSH. (§19.2: a `flotilla
|
||
content sync` verb would fix this.)
|
||
- DOCS.md → served from the deployed rfc-app tag; update = release+deploy.
|
||
- /docs/specs/<name> → runtime gitea-raw fetch, configured by the
|
||
OHM_DOCS_SPECS overlay, 5-min TTL, no deploy needed.
|
||
|
||
Open roadmap tail: #22 (consent copy, needs operator+counsel text), #21
|
||
Part A (Amplitude audit, needs real-world data), #18/#20 ops follow-
|
||
throughs, #33/#34 naming alignment, #31b + #25-followup polish, and the
|
||
new #35 (operator RFC authoring). No core features remain. Pick one, or
|
||
ask the operator what's next.
|
||
```
|