benstull/rfc-app
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: CONTRIBUTING.md + SPEC.md §21 analytics chapter

Browse Source 
Lands roadmap item #19 (CONTRIBUTING + transcript-linked onboarding)
and #21 Part B (standing analytics instrumentation discipline) as a
single docs commit. No code change, no version bump — these ride a
future release or land as a no-bump docs commit at the operator's
discretion.

CONTRIBUTING.md (new):
  - Project-evolution framing pointing at wiggleverse/ohm-session-history
    as the authoritative how-we-got-here record.
  - Worked-example links into Sessions E (clean small release),
    I (recovery from deploy fault), K (multi-feature wave with
    operator-secret pause), L (squash-merge across three parallel
    features + #21 Part C identity-lifecycle wiring).
  - PR-shape contract: subagents push feature branches; operator
    tags + deploys (the pattern driver sessions use).
  - CHANGELOG strict-descending convention.
  - RFC 2119 keyword discipline for Upgrade-steps blocks (per §20.4).
  - §19.2 candidate discipline — architectural deferrals get noted
    rather than scope-creeping a release.
  - Test-coverage expectations characterized from the actual
    ~250-test backend pytest surface (no frontend test runner today;
    the discipline is build-clean + backend HTTP contract coverage).
  - Operator-only gestures explicitly enumerated (no tagging, no
    deploying, no pin moves, no secret bytes in conversation).
  - Analytics instrumentation checklist (#21 Part B's CONTRIBUTING
    artifact): named events, autocapture-friendly DOM, replay
    masking, PR description discipline.

SPEC.md §21 (new chapter — Analytics instrumentation and identity):
  - Placed AFTER §20 versioning rather than between §15 and §16, to
    avoid renumbering §19.2 / §19.3 — those numbers are load-bearing
    project nouns referenced from CLAUDE.md, transcripts, and prior
    commits. §15 carries a new forward-pointer naming §21 as the
    peer chapter.
  - §21.1 event-taxonomy conventions (Title Case "Subject Verb",
    snake_case props, no PII).
  - §21.2 required prop families per event kind, including the
    hashed-target_email convention for invite-side events that
    target a not-yet-user (#12).
  - §21.3 autocapture-friendly DOM patterns (stable text,
    aria-label on icon-only buttons, data-amp-track-* on
    repeated rows, data-amp-track-suppress for noise surfaces).
  - §21.4 session-replay masking — credentials MUST be masked,
    PII SHOULD be masked, privacy policy MUST match reality.
  - §21.5 consent-gate contract — pre-consent no init / no
    network / no recording; granted→denied → setOptOut(true)
    within one tick.
  - §21.6 identity lifecycle (per #21 Part C) — identify with
    user_id + properties on sign-in; setUserProperties on
    mid-session change; anonymize on sign-out (after the
    User Signed Out track); identify-BEFORE-track on invite-claim
    paths. §21.6.1 set vs setOnce taxonomy with explicit classification
    rule.
  - §21.7 cohort-shape implications (informative — what the
    Amplitude dashboard can actually answer with the conventions).
  - §21.8 secret-vs-public framing for the overlay binding —
    Amplitude browser key is public (bundle-embedded), Turnstile
    secret half is real-secret; canonical pbpaste-pipe gesture
    for the operator.
  - §21.9 new §19.2 candidates surfaced (session-replay-specific
    consent category, bundle-size budget measurement, property-
    shape CI lint, centralized email-hash helper).
  - §21.10 open question (consent-category split timing).

Grounded in real code: the SPEC chapter cites
frontend/src/lib/analytics.js v0.15.0 + the v0.16.0 (AcceptInvitation)
+ v0.17.0 (InviteClaim) inline #21 Part C wiring as worked examples.
RFC 2119 keywords used precisely throughout.
This commit is contained in:
Ben Stull
2026-05-28 05:39:46 -07:00
parent 1456c8b73f
commit 213f6862d5
2 changed files with 876 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CONTRIBUTING.md
+407
View File
@@ -0,0 +1,407 @@
# Contributing to rfc-app
`rfc-app` is the framework that hosts RFC-shaped collections of
documents — one repo per RFC, a meta repo per collection, a web app
that turns the Git substrate into a writeable surface. The Open
Human Model (OHM) deployment at `ohm.wiggleverse.org` is one
instance. The framework is intended to host more.
This document explains how to propose a change to the framework
itself — a new endpoint, a schema migration, a UI affordance, a
spec clarification. For changes to *content* hosted by a specific
deployment (the OHM RFCs, the OHM roadmap), see that deployment's
own contribution guide (e.g. [`ohm-rfc/CONTRIBUTING.md`](https://git.wiggleverse.org/wiggleverse/ohm-rfc/src/branch/main/CONTRIBUTING.md)).
---
## How the project actually evolves
rfc-app is built in the open in the literal sense: **every build
session produces a full transcript** at
[`wiggleverse/ohm-session-history`](https://git.wiggleverse.org/wiggleverse/ohm-session-history)
on `git.wiggleverse.org`. The transcripts are the authoritative
record of how the framework got from one release to the next — the
decisions, the friction, the dead ends, the reasoning. They are not
curated retrospectives; wrong turns stay in.
If you are proposing a change to rfc-app, **read at least the most
recent session transcript before opening a PR.** The transcripts
show what shape a feature lands in, where the spec gets touched,
what the operator pushes back on, and how the release rides into
deployment. A PR that matches that texture is much more likely to
land cleanly than one shaped by the README alone.
Worked examples to start with:
- **Session E** ([transcript](https://git.wiggleverse.org/wiggleverse/ohm-session-history)) —
a clean small release. Read this for the simplest possible release
shape: one feature, one version bump, one upgrade-steps block, no
surprises.
- **Session I** — recovery from a deploy fault. Read this for how
the project handles things going wrong mid-deploy, and for the
honest no-curation discipline.
- **Session K** — a multi-feature wave with one item paused on an
operator-provided secret. Read this for the subagent dispatch
pattern (the model the project uses to ship multiple features in
parallel), and for the binding rule that the assistant **never**
asks the operator to paste secret bytes into the conversation.
- **Session L** — squash-merge integration across three parallel
features (v0.15.0 / v0.16.0 / v0.17.0), with `#21 Part C`
identity-lifecycle Amplitude wiring folded inline across all
three releases. Read this for how cross-cutting concerns (analytics,
observability) get layered into already-in-flight features
without scope-creeping any single release.
The repository where transcripts live —
[`wiggleverse/ohm-session-history`](https://git.wiggleverse.org/wiggleverse/ohm-session-history) —
is the canonical history. The `git log` of `rfc-app` is the artifact;
the transcripts are the story behind it.
---
## How a contribution flows
The framework runs on a **subagents push feature branches; operator
tags and deploys** model. Contributors — whether human or AI agents
running in a Claude Code subsession — open feature branches and
submit PRs. The operator (the person running the deployment) is the
one who merges, tags, bumps `VERSION`, runs `flotilla deploy` (or
the equivalent for non-OHM deployments), and moves the deployment's
`.rfc-app-version` pin. The driver session transcripts inherit
this shape; contributors inherit it from them.
Concretely:
1. Read the most recent session transcript. Understand what just
shipped and what is in flight.
2. Open an Issue first if your change is exploratory, structural,
or might overlap with in-flight work. The operator will name
any collision.
3. Branch from `main`. Name the branch
`feature/<short-description>` for additive work, `fix/<short-
description>` for bug fixes, `docs/<short-description>` for
documentation-only work. The driver sessions use
`feature/v<target-version>-<slug>` (e.g.
`feature/v0.16.0-owner-invite`) — that shape is welcome but not
required for outside contributors, since contributors do not
pick the target version.
4. **Do not bump `VERSION` or `frontend/package.json#version` in
your PR.** The operator picks the target version at integration
time; bumping ahead causes cherry-pick conflicts. The same
applies to the `CHANGELOG.md` entry header — see below.
5. **Do not tag releases, do not run any deploy gesture, do not
touch any deployment's `.rfc-app-version` pin.** The operator
alone owns those gestures. (For OHM specifically: "I'm the only
one that gets to yolo." See the boundary section in
`ohm-rfc/CONTRIBUTING.md`.)
6. Push your branch and open a PR. Describe what you're proposing
and why, in language the operator can paste into the eventual
release commit. If the change touches `SPEC.md`, name which
section(s) and the contract change.
---
## CHANGELOG convention: strict descending
`CHANGELOG.md` is ordered **newest-on-top**. The header line for
the in-progress version goes at the top of the file; older
releases descend below it. This is the binding convention; the
operator hand-resolves the conflict when two parallel feature
branches both insert at the top of the file (the squash-merge
integration that ships parallel-feature waves keeps the strict-
descending shape — see Session K for the cherry-pick mechanics and
Session L for the hand-resolved-with-a-small-script variant).
A new entry has this shape (read the existing 0.15.0 / 0.16.0 /
0.17.0 entries for worked examples):
```markdown
## 0.X.Y — YYYY-MM-DD
**Minor — schema migration auto-applied; no operator action.** This
release ships <one or two sentences naming the feature and why>.
### Added
- **<New module/endpoint/component>** — what it does, where it lives,
why it exists. Include file paths inline so a reader can click through.
### Changed
- **<Existing surface>** — what changed and how a deployment notices.
### Migration
- **`<NNN_name>.sql`** — auto-applied by `db.run_migrations()` on
backend start. <Describe the schema delta in one sentence.>
### Upgrade steps (from 0.(X-1).Y)
- You **MUST** … (per RFC 2119; see SPEC.md §20.4).
- You **MUST NOT** …
- You **SHOULD** …
- You **MAY** …
```
The header version number is filled in by the operator at merge
time. Your PR's CHANGELOG diff can leave the version as
`0.X.Y — YYYY-MM-DD` (literal placeholder), or use a guessed value
the operator overwrites; either is fine.
---
## `Upgrade steps:` blocks use RFC 2119 keywords
If your change requires deployments to do anything when they
upgrade — set an env var, apply a migration, restart a process,
flip an overlay value, accept a behavioral change — your CHANGELOG
entry **must** include an `### Upgrade steps` block, and that
block **must** use the [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119)
/ [RFC 8174](https://www.rfc-editor.org/rfc/rfc8174) keywords as
defined in `SPEC.md` §20.4:
- **MUST** / **SHALL** / **REQUIRED** — without this step the
deployment will not function correctly. Skipping is a regression
the framework does not handle.
- **MUST NOT** / **SHALL NOT** — previously valid, now no longer
supported.
- **SHOULD** / **RECOMMENDED** — the framework's tested path. A
deployment may deviate when it has a reason.
- **SHOULD NOT** / **NOT RECOMMENDED** — discouraged without being
forbidden.
- **MAY** / **OPTIONAL** — an affordance you can take or skip.
Cross-version upgrades (jumping more than one minor) are computed by
the operator composing each intervening release's steps in order.
Each adjacent step must therefore be locally unambiguous — this is
the whole reason the keyword discipline is binding. Avoid words
like "should probably" or "might want to" inside an upgrade step;
either the framework needs the action or it doesn't.
If your change touches the env contract, **also update**
`backend/.env.example` and/or `frontend/.env.example` in the same
PR so the contract and the documentation land together (§20.4).
---
## SPEC.md and §19.2 candidates
`SPEC.md` is the framework's binding spec. It is honest about open
questions — large sections of it carry "§19.2 candidates," which
are decisions the project has deliberately deferred rather than
guessed at.
The discipline: **architectural or process deferrals get noted as
§19.2 candidates rather than scope-creeping a release.** When you
notice that your change opens a question larger than the change
itself (a different DB shape, a new auth contract, a cross-cutting
UX rethink), the right move is usually to land the narrow change
and add a §19.2 candidate naming the larger question. The candidate
documents what was set aside and why, so a future session can pick
it up with context.
Worked examples from recent sessions:
- v0.11.0 (Session K) shipped device trust and surfaced three new
§19.2 candidates: cross-device session revocation, password-
equivalent change invalidating trust, device-trust window
tunables via env. None of those were in the v0.11.0 scope; they
were noted in SPEC.md §19.2 so a future session can address them
on their own terms.
- v0.15.0 (Session L) shipped the Amplitude wrapper and added
candidates around session-replay-specific consent category +
bundle-size measurement, both deferred to the future Part-A audit.
When you spot a deferred decision in your PR's territory, name it
in your PR description and add it to `SPEC.md` §19.2 in the same
diff. Do not silently expand scope to settle it.
---
## Test-coverage expectations
The backend has the load-bearing test suite at
`backend/tests/`. Tests are organized as `*_vertical.py` files,
each covering one feature end-to-end through the FastAPI app
(provisioning fixtures, hitting the HTTP surface, asserting on the
database state). At time of writing, the suite is ~250 tests across
~25 files. Examples:
- `test_admin_create_user_invite_vertical.py` — v0.17.0's
admin-create user + invite + claim flow, 15 tests covering happy
path + every refusal shape + the audit-trail row.
- `test_rfc_invitations_vertical.py` — v0.16.0's per-RFC invite +
accept flow, 18 tests.
- `test_device_trust_vertical.py` — v0.11.0's 30-day device trust,
14 tests including cookie shape, hash-vs-raw-token discipline,
expired / revoked / forged / cross-user invariants.
Expected coverage for a new feature:
- **Backend feature** — one new `test_<feature>_vertical.py` file
that covers the happy path, every documented refusal/error code,
and any cross-surface effect (rows the feature writes to existing
tables, fields it adds to existing endpoints). Reuse fixtures
from neighboring test files (e.g. `test_propose_vertical.py`'s
`FakeGitea` is widely reused).
- **Migration** — verify migrations are reachable from `backend/.venv`
before pushing: `cd backend && PYTHONPATH=. .venv/bin/pytest -q`
exercises `db.run_migrations()` through the fixture setup.
- **Frontend feature** — there is currently no frontend test
runner. The discipline is: keep the change ships-clean
(`cd frontend && npm run build` succeeds), and the backend
vertical test exercises the HTTP contract the frontend
consumes, which is the meaningful behavioral guarantee.
Frontend changes that ride along with a backend feature land
with the backend test as the regression boundary.
- **Bug fix** — add a regression test in the same vertical file
that proves the original failure mode and verifies the fix.
Run the backend suite before pushing. From `backend/`:
```bash
PYTHONPATH=. .venv/bin/pytest -q
```
(The `PYTHONPATH=.` is a known ergonomic gap — see SPEC.md §19.2
candidate; the suite does not pick up `app/` without it.)
If your PR doesn't include tests, the operator will ask for them
before merge unless the change is genuinely test-irrelevant
(documentation, comments, dev-only tooling).
---
## Analytics instrumentation checklist
> *(This section codifies `ohm-rfc/ROADMAP.md` #21 Part B's
> CONTRIBUTING checklist. It is discipline, not a gate — but the
> operator will push back on PRs that skip it.)*
If your PR adds or changes a user-facing feature, walk this
checklist before opening the PR. The instrumentation conventions
themselves are specified in `SPEC.md` §21 (Analytics instrumentation
and identity); this section is the procedural reminder.
1. **What named event(s) does this feature need?**
Open `frontend/src/lib/analytics.js` and look at the `EVENTS`
constant. Does an existing event cover your feature? If not, is
the new event in the spec's "Subject Verb" Title Case form
(`Comment Posted`, `Invitation Sent`)? Are the prop families
consistent with SPEC.md §21's required-prop catalog (opaque
ids only, no PII, enums lowercased like `'otc'` not `'OTC'`)?
2. **Do interactive elements have stable text / ARIA labels /
`data-amp-track-*` so autocapture is meaningful?**
The frontend ships `autocapture: true`, which instruments
every click and form interaction. The *value* of those events
depends on the DOM the SDK sees: a `<button>` with stable
visible text or an `aria-label` shows up as a meaningful
dashboard row; an icon-only `<button>` with no label shows up
as garbage. New components that introduce interactive elements
should either carry meaningful labels (visible text or ARIA) or
carry a `data-amp-track-name="<Stable Name>"` attribute. For
repeated rows (per-RFC lists, comment lists), use a stable
`data-amp-track-*` identifier so per-row click counts aggregate
to the row's identity rather than to a generic label.
3. **Does any new form field need replay masking?**
Session replay records at `sampleRate: 1` (100% of consented
sessions). New form inputs that capture passwords, OTC codes,
tokens, magic-link URLs, or other secret/credential-equivalent
material **MUST** be masked with Amplitude's masking conventions
(the `.amp-mask` class or the `data-amp-mask` attribute,
whichever the wrapper integration expects in this version).
New inputs that capture arguably-PII (email, real name, free-
text drafts) **SHOULD** also be masked; if a deliberate
un-masking decision is taken, document it in the PR description
and in `SPEC.md` §21.
4. **Does the PR description name the instrumentation decisions?**
A one-sentence summary in the PR description — "fires
`Comment Posted` with `{rfc_slug, comment_id}`; no new form
fields, no new replay-masking concerns" — is enough. If the
decision is "we chose not to instrument this," say that too;
the absence of an event is itself a decision the operator
wants visible. The relevant SPEC chapter (§21) is the binding
reference for what shapes are correct.
If your feature touches an identity-meaningful surface (sign-in,
sign-out, invite-claim, role change, account state change), also
walk the **identity lifecycle** contract in SPEC.md §21.6: every
new claim/sign-in path **MUST** call `identify({ user_id, properties })`
BEFORE the first `track()` event on that surface, so the Amplitude
user record is created with the OHM user_id from the very first
event rather than as an anonymous device that retroactively links.
v0.16.0's `AcceptInvitation.jsx` and v0.17.0's `InviteClaim.jsx`
are the worked examples; mirror their shape.
---
## The operator-only gestures
Some gestures are operator-only. Contributors do not perform them;
PRs that perform them get rejected on principle, not on merit:
- **Tagging a release** (`git tag v0.X.Y` + `git push --tags`).
- **Pushing to `main`** after merge (the operator merges; the
framework's `main` branch tracks releases the operator has
shipped).
- **Bumping `VERSION` and `frontend/package.json#version` to the
shipped value.** The operator does this at integration time so
the version line is consistent across the release commit.
- **Running `flotilla deploy` or any equivalent deployment gesture**
in any deployment of rfc-app. Contributors do not deploy.
- **Moving a deployment's `.rfc-app-version` pin.** That pin lives
in the deployment's content repo (e.g. `ohm-rfc/.rfc-app-version`)
and is moved by the deployment's operator. Contributors to that
deployment do not move it; contributors to the framework
certainly do not.
- **Setting secrets** (anywhere — Secret Manager, env files,
`flotilla secret set`, vendor dashboards, anything). The
binding rule baked in mid-Session-K is: **the assistant never
asks the operator to paste secret bytes into a conversation,
even as one offered option**. The corollary for contributors:
do not include secret values in PR descriptions, commit
messages, or issue comments. Reference secrets by their binding
name (`SMTP_PASSWORD`, `AMPLITUDE_API_KEY`) and let the
operator handle the bytes.
If your change requires a new secret or env var, document the
requirement in the CHANGELOG `### Upgrade steps` block in the
RFC 2119 form ("operators **MUST** set `<NEW_VAR>` ...") and
update the `*.env.example` file. The operator will run the
secret/overlay-set gesture themselves at deploy time.
---
## When in doubt
- **Open an Issue first.** Especially for any change that touches
SPEC.md, the auth/permissions model (§6), the storage shape (§4
/ §5), or the deploy contract (§20). The operator (or a future
driver session) will name what they want before you write code.
- **Read the most recent session transcript.** It will tell you
what shipped last and what's in flight.
- **Cite SPEC.md sections in your PR description.** "Touches §15.4
(per-category email toggles) and adds §19.2 candidate around
per-channel mute granularity" gives the operator a map of where
to read.
---
## License
The framework is released under the MIT License (see
[`LICENSE`](./LICENSE)). By contributing, you agree your work
ships under those terms.
---
## See also
- [`SPEC.md`](./SPEC.md) — the framework's binding spec. §19.2
is the deferred-decisions queue; §20 is the versioning + deploy
contract; §21 is the analytics instrumentation contract.
- [`CHANGELOG.md`](./CHANGELOG.md) — release history in strict
descending order. Read recent entries for the shape your PR's
release-commit will take.
- [`PHILOSOPHY.md`](./PHILOSOPHY.md) — what the framework is for.
PRs whose shape conflicts with the philosophy get a longer
conversation than PRs that fit.
- [`wiggleverse/ohm-session-history`](https://git.wiggleverse.org/wiggleverse/ohm-session-history)
— the authoritative record of how the project has actually
evolved, session by session.
SPEC.md
+469
View File
@@ -2284,6 +2284,13 @@ a given signal, the **storage shape** that makes triage tractable, and
the **out-of-session channels** (email, digest) that let asynchrony the **out-of-session channels** (email, digest) that let asynchrony
actually work. actually work.
(The framework's separate **analytics + session-replay** surface —
Amplitude wiring, event taxonomy, identity lifecycle, consent
contract — is a peer cross-cutting concern specified in §21.
Notifications cover in-product signal-of-others-acting-on-your-work;
analytics covers observability of how the product is used. The two
surfaces do not overlap.)
### 15.1 The signal-surface stack ### 15.1 The signal-surface stack
Five surfaces, each with one narrow job: Five surfaces, each with one narrow job:
@@ -4300,3 +4307,465 @@ Downstream deployments, in exchange for the contract above, commit to:
order; order;
- supply every required env var the framework documents at the - supply every required env var the framework documents at the
version they are running. version they are running.
---
## 21. Analytics instrumentation and identity
The framework ships an Amplitude Analytics + Session Replay wrapper
in v0.15.0 (`frontend/src/lib/analytics.js`), gated by the v0.13.0
cookie/privacy consent surface (`frontend/src/lib/consent.js`,
§14.5). This section codifies the conventions that keep the
instrumentation **quality** healthy as features land — taxonomy
shape, autocapture hygiene, replay masking, the consent contract,
and the identity lifecycle. The conventions are framework-neutral:
every deployment of rfc-app that turns on the wrapper inherits
them.
This chapter is placed semantically after §15 (Notifications) and
§16 (deliberately deferred) as a peer cross-cutting framework
concern. It was added after §20 in the chapter sequence to avoid
renumbering the deferred-decisions surface §19.2, which is a
load-bearing project noun referenced across CLAUDE.md, transcripts,
and prior commits.
### 21.1 Event-taxonomy conventions
Events live in the public `EVENTS` constant in
`frontend/src/lib/analytics.js`. Callers **SHOULD** use one of the
named constants rather than firing arbitrary event strings — that
keeps the Amplitude dashboard coherent over time and makes the
taxonomy reviewable as a single source of truth.
- **Name form: Title Case, "Subject Verb".** E.g.
`Comment Posted`, `Invitation Sent`, `RFC Viewed`,
`User Signed In`, `Admin Permission Decision`. Spaces between
words, no punctuation, no leading verbs (use `RFC Proposed`,
not `Propose RFC`). The strings match the Amplitude dashboard
names exactly.
- **Stability.** New events **SHOULD** land via a release, not
ad-hoc — adding an entry to `EVENTS` is a CHANGELOG-worthy
change because it widens the framework's observable surface
(§20.3). Renaming an event after it has shipped breaks the
dashboard's historical continuity; renames **SHOULD** be
treated as a deprecation cycle (ship both, dashboard-migrate,
drop the old one).
- **Opaque ids only in prop values.** Properties **MUST NOT**
carry PII — no email, no display name, no IP, no free-text
field bodies (titles, comment text, RFC drafts). Properties
**SHOULD** be limited to:
- opaque ids: `rfc_slug`, `rfc_id`, `pr_number`,
`target_user_id`, `invited_by_admin_id`, `thread_id`,
`comment_id`;
- enums (lowercased): `method: 'otc' | 'passcode' |
'device-trust' | 'admin-invite' | 'rfc-invite'`;
- booleans: `trust_device`, `needs_passcode`, `passcode_set`;
- timestamps (ISO 8601);
- small bounded integers: `custom_message_chars` (coarse-grained
signal of admin effort, NOT the message text itself).
- **Casing consistency.** Prop keys use `snake_case` (matches the
backend's JSON shape). Enum values use lowercase with hyphens
(`'rfc-invite'`, not `'rfcInvite'` or `'RFC_INVITE'`). Drift
here ruins dashboard aggregation; the operator-side audit
(§21.7 / `ohm-rfc/ROADMAP.md` #21 Part A) checks for it.
The starting taxonomy as of v0.17.0:
```
PAGE_VIEWED: 'Page Viewed'
RFC_VIEWED: 'RFC Viewed'
USER_SIGNED_IN: 'User Signed In'
USER_SIGNED_OUT: 'User Signed Out'
RFC_PROPOSED: 'RFC Proposed'
PR_OPENED: 'PR Opened'
COMMENT_POSTED: 'Comment Posted'
BETA_ACCESS_REQUESTED: 'Beta Access Requested'
ADMIN_PERMISSION_DECISION: 'Admin Permission Decision'
INVITATION_SENT: 'Invitation Sent' # v0.16.0 / #12
INVITATION_ACCEPTED: 'Invitation Accepted' # v0.16.0 / #12
USER_INVITED: 'User Invited' # v0.17.0 / #16
INVITE_CLAIMED: 'Invite Claimed' # v0.17.0 / #16
```
### 21.2 Required prop families per event kind
Each event family carries a small required prop set. These are
load-bearing for the dashboard's cohort analysis; releases that
add a new event in an existing family **SHOULD** carry the
family's required props.
- **Navigation events** (`Page Viewed`, `RFC Viewed`): carry
`path` (string, pathname only — never the query string if it
could carry a token) for `Page Viewed`; carry `rfc_slug` for
`RFC Viewed`. `rfc_id` **MAY** be added when the cached row is
in hand.
- **Auth-state events** (`User Signed In`, `User Signed Out`):
`User Signed In` carries `method` (one of `'otc'`,
`'passcode'`, `'device-trust'`, `'admin-invite'`). `User
Signed Out` carries no props (the identity binding is cleared
separately via `anonymize()`).
- **Authored-action events** (`RFC Proposed`, `PR Opened`,
`Comment Posted`): carry `rfc_slug`. PRs additionally carry
`pr_number` once the row exists. Comments additionally carry
`thread_id`. None carry the body text.
- **Admin-action events** (`Beta Access Requested`,
`Admin Permission Decision`): the latter carries `action`
(lowercase: `'grant'` / `'revoke'`) and `target_user_id`.
- **Invite-side events** (`Invitation Sent`, `User Invited`): fire
from the inviter's signed-in session. `Invitation Sent` (per-RFC,
#12) carries `rfc_slug` + `role_in_rfc`. `User Invited`
(admin-create, #16) carries `target_user_id` (the OHM user_id of
the just-provisioned user) + `initial_role` +
`custom_message_chars` (a bounded integer signal of admin
effort, never the message text). Per #21 Part C: when the
invitee is not yet a user (#12 per-RFC invitations to an email
address that has never signed in), the invite-side event **MAY**
carry a hashed `target_email` fingerprint (SHA-256 of the
normalized lower-cased email) so the invite + claim pair can be
correlated later. Plain-text `target_email` **MUST NOT** be
carried.
- **Claim-side events** (`Invitation Accepted`, `Invite Claimed`):
fire from the invitee's session, immediately after an
`identify({ user_id, properties })` call binds the OHM user_id
to the Amplitude record (see §21.6). The events carry the
invite context (`rfc_slug` + `role_in_rfc` for the per-RFC
shape; `invited_by_admin_id` + `initial_role` + `needs_passcode`
+ `trust_device` for the admin-create shape).
When in doubt, the principle: a property is correctly shaped iff
the operator could publish it in a session transcript without
hesitation.
### 21.3 Autocapture-friendly DOM patterns
The wrapper initializes Amplitude with `analytics.autocapture: true`,
which auto-instruments page views, clicks, and form interactions.
The *value* of those auto-captured events depends entirely on the
DOM the SDK observes. Releases that add interactive UI **SHOULD**
follow these patterns so the dashboard rows are readable rather
than rows like "Click on `<button>` at `:nth-child(7)`".
- **Stable visible text on interactive elements.** Buttons and
links **SHOULD** have stable, human-readable text content (the
same string Amplitude uses to label the row). Avoid generic
labels like "Read more" / "Click here" that lose context.
- **`aria-label` on icon-only buttons.** Icon-only buttons (the
chevron expanders, kebab menus, close `X`s) **MUST** carry a
meaningful `aria-label`. Default autocapture for an unlabeled
icon button reads as garbage. The `aria-label` is also an
accessibility requirement — the two goals align.
- **`data-amp-track-*` for repeating-list per-row identifiers.**
When a list renders many rows of the same shape (RFC rows,
comment rows, PR rows in a listing), per-row interactive elements
**SHOULD** carry a `data-amp-track-name` attribute that
identifies the row's *kind* and a `data-amp-track-*` attribute
carrying the row's stable id. The convention:
```html
<button
data-amp-track-name="RFC Row Expand"
data-amp-track-rfc-slug={slug}
>…</button>
```
This makes per-RFC click counts aggregate to the RFC rather
than to a generic label, and lets the dashboard answer "which
RFCs got the most engagement" rather than "how many buttons
were clicked."
- **`data-amp-track-suppress` for noise surfaces.** Crowded surfaces
(the admin user-listing post-v0.9.0, the RFC discussion panel
during heavy review) **MAY** apply
`data-amp-track-suppress` (or its current equivalent in the
SDK version in use) to elements whose clicks would flood the
dashboard without informing anything. Suppression is a
deliberate decision; document it inline.
### 21.4 Session-replay masking conventions
The wrapper initializes Amplitude with `sessionReplay.sampleRate: 1`
(100% of consented sessions are recorded for full-DOM playback —
vendor-recommended default for new Amplitude deployments). Replay
has a meaningfully larger privacy footprint than event counters,
and the masking discipline is binding.
- **Credentials MUST be masked.** The OTC code input, passcode
input, any password-type field, the Turnstile widget internals,
the magic-link-claim token if it survives in the URL bar
(browser history, screenshot windows) — these **MUST** be masked
with Amplitude's masking convention (the `.amp-mask` class or the
`data-amp-mask` attribute, whichever the wrapper's SDK version
uses; the wrapper's bootstrap comment names the current
convention). Confirm each masking attribute survives the
wrapper init by inspecting a recorded session before each
release that touches an auth input.
- **PII SHOULD be masked or carefully un-masked.** Email-entry
fields, real-name capture fields (the v0.8.0 first/last/why
panel), free-text RFC body drafts, comment-compose text —
each is arguably PII or near-PII. The per-field decision is
the release's responsibility; document the choice in `SPEC.md`
§21 (this section) and in the release CHANGELOG so future
deployments inherit the call rather than re-deciding.
- **Privacy-policy alignment.** The recorded data **MUST** match
what the deployment's privacy / cookies policy claims. If
reality is broader than the document promises, update the policy
text in the same release.
- **Selective redaction.** Amplitude supports field-level mask
classes that hide value while preserving DOM shape (so the
session is replayable but the value is not). Prefer this over
whole-form masking when only a subset is sensitive.
### 21.5 Consent-gate contract
The wrapper is bound to the v0.13.0 cookie/privacy consent surface
(`frontend/src/lib/consent.js`, §14.5). The binding is **load-
bearing**: the SDK and the session-replay recorder **MUST NOT**
load before consent is granted, and any consent revocation **MUST**
take effect within one tick of the consent flip.
The wrapper's bootstrap implements this contract; releases that
touch the analytics surface **MUST** preserve it.
- **Pre-consent: no init, no network, no recording.** If
`consent.analytics === true` is not currently true (either
because the user denied, or because the banner is up and no
decision has been recorded), the wrapper **MUST NOT** import
the Amplitude SDK, **MUST NOT** open any network request to
Amplitude, and **MUST NOT** start any session-replay recording.
The consent-gated lazy `import('@amplitude/unified')` is the
binding implementation; preserve it.
- **Denied → granted: init at the consent moment.** When consent
flips from denied/undecided to granted, the wrapper **MUST**
initialize the SDK at that moment (a new `initAll(KEY, …)` call
through the lazy-import path). Track and identify calls made
before init resolves **MUST** be queued and drained on init,
so the first signed-in user's first event is not dropped on
the cold-load race.
- **Granted → denied: setOptOut(true) within one tick.** When
consent flips from granted to denied mid-session, the wrapper
**MUST** call `amplitude.setOptOut(true)` so subsequent events
are dropped client-side and session replay stops recording.
The wrapper cannot unload the script tag (the SDK is already
in memory), but the SDK's contract for "drop subsequent events"
is `setOptOut(true)`. This **MUST** happen within one tick of
the consent flip (i.e. synchronously inside the
`onConsentChange` handler).
- **No silent re-grant.** A granted → denied → granted sequence
**MUST** call `setOptOut(false)` (re-enabling the SDK that was
paused) rather than firing a second `initAll` (which would
double-init). The wrapper's bootstrap implements this; releases
that touch the consent integration **MUST** preserve the
distinction.
- **Build-time vs. runtime.** The API key is read from
`import.meta.env.VITE_AMPLITUDE_API_KEY` at build time. When
the env var is unset, the wrapper **MUST** log one console
warning and no-op (every public function becomes a deterministic
no-op) so dev environments without an Amplitude account keep
working. The deploy gesture binds the key via the deployment's
overlay verb (for OHM-shape deployments, `flotilla overlay set`);
see §21.8 for the secret-vs-public discussion.
### 21.6 Identity lifecycle (per #21 Part C)
Amplitude's identity model has a specific pattern that the
framework follows verbatim. Every release that touches an
identity-meaningful surface **MUST** observe this pattern. The
pattern shipped inline across v0.15.0 / v0.16.0 / v0.17.0
(Session L's wave); this section codifies the contract so future
releases inherit it.
**On sign-in success** (`App.jsx`'s `me.user` resolution):
- The wrapper's `identify({ user_id, properties })` call **MUST**
carry both the OHM user_id (`amplitude.setUserId(<id>)`
internally) AND the user's durable property bag. `setUserId`
alone is **NOT** sufficient — without properties, the Amplitude
user record carries only the id, and cohort analysis loses the
shape (role distribution, sign-in-method distribution, etc.)
the dashboard depends on.
- Properties **MUST** be a bag of opaque ids, enums, booleans,
and timestamps — no PII (no email, no display name, no IP).
- Properties **MUST** be classified `set` vs `setOnce` deliberately
(see §21.6.1 below).
- The same `identify` call **MUST** be re-issued on every sign-in
(idempotent at Amplitude's side; cheap; corrects any drift in
the mutable property half).
**On user-state change mid-session** (role grant/revoke, trust-
device add, passcode set, beta-permission flip):
- The wrapper's `setUserProperties(properties)` call **MUST** fire
so the Amplitude record stays current. Mid-session state changes
**MUST NOT** wait for the next sign-in to surface — the dashboard
cohort an admin uses to grant permission is the same dashboard
that next sees the granted user's behavior; staleness here breaks
the cohort feedback loop.
**On sign-out**:
- The wrapper's `anonymize()` call (internally `amplitude.reset()`)
**MUST** fire. `reset` clears the device-id linking AND **MUST**
also clear the property cache so the next anonymous session is a
fresh slate (the wrapper's `anonymize()` does both — releases
that touch the wrapper **MUST** preserve this).
- The `User Signed Out` `track()` call **MUST** fire *before*
`anonymize()`, so the sign-out event is correctly attributed to
the signing-out user rather than to the post-reset anonymous
device.
**On invite-claim** (the v0.16.0 per-RFC invite + v0.17.0 admin-
create invite paths):
- The wrapper's `identify({ user_id, properties })` call **MUST**
fire BEFORE the first `track()` event on the claim surface, so
the Amplitude user record is created with the OHM user_id from
the first event. **MUST NOT** fire `track()` first and `identify`
later — that creates an anonymous device record that
retroactively links, and the cohort attribution for
invite-driven onboarding loses precision.
- The invite-context properties (`claim_method`,
`invited_by_admin_id`, `invited_at`, `initial_role`) are
`setOnce` (immutable user-history markers) — see §21.6.1.
**Inviter-side identification on invite-send events**:
- The inviter's `track('Invitation Sent', …)` and
`track('User Invited', …)` events fire from the inviter's
signed-in session, so the `user_id` attribution is already
correct (it's the inviter's id). The event body carries
`target_user_id` (#16 — admin-create, where the future user is
provisioned at create-time) or a hashed `target_email`
fingerprint (#12 — per-RFC invite, where the invitee is not
yet a user) so the invite + claim pair can be correlated later
in the dashboard.
#### 21.6.1 `set` vs `setOnce` taxonomy
Amplitude distinguishes two property-write semantics:
- **`set(k, v)`** — overwrites the property on every call. The
user record reflects the most recent value.
- **`setOnce(k, v)`** — writes only if the property is not
already present. Subsequent calls are no-ops. The user record
reflects the first value ever written.
The wrapper's `applyProperties` function accepts both: a bare
value uses `.set()`; a sentinel-wrapped value
`['__setOnce__', value]` uses `.setOnce()`. Releases that add new
user properties **MUST** classify each one explicitly, by the
following rule:
- A property whose value is **expected to change over the user's
lifetime** is `set`. Examples: `role` (can flip from
`contributor` to `owner`), `permission_state` (pending → granted),
`passcode_set` (false → true), `device_trusted` (changes per
active device). On each sign-in, the latest value is written;
the dashboard always sees current state.
- A property that is an **immutable historical marker** is
`setOnce`. Examples: `first_sign_in_at` (the timestamp of the
user's first observed sign-in — never re-write), `account_
created_at` (the timestamp of provisioning),
`invited_by_admin_id` (the admin who provisioned this user via
the v0.17.0 path — preserved even if the user is later
re-invited or has their role changed), `invited_at` (the
timestamp at which the invite was sent — distinct from
`claim_method` which is also setOnce because once claim_method
is `'admin-invite'`, that's the path this user took).
The classification is part of the release's contract — flipping a
property from `set` to `setOnce` (or vice versa) mid-life corrupts
the user record and **MUST** be avoided. If a property's
semantics genuinely change, retire the old key and introduce a new
one (same deprecation discipline as event renames in §21.1).
### 21.7 Cohort-shape implications (informative)
The conventions above are designed so that the Amplitude dashboard
can answer cohort questions the operator actually asks:
- *"How many users signed in via the admin-invite path in week N
vs. organic OTC?"* — uses `claim_method` (setOnce) on the user
record + `User Signed In` events with `method`.
- *"Of admin-invited users, what fraction set a passcode within
their first session?"* — uses `claim_method` + `passcode_set`
on the user record + `Page Viewed` events to define "session."
- *"Which RFCs have the most owner-invited contributors?"* — uses
per-RFC `Invitation Sent` / `Invitation Accepted` correlated
via `rfc_slug` + `role_in_rfc`.
- *"What's the gap between invite-send and invite-claim, broken
out by inviter?"* — uses `Invitation Sent` (inviter's session,
inviter `user_id`) + `Invitation Accepted` (invitee's session,
invitee `user_id` after the BEFORE-track identify) joined on
`rfc_slug` + inviter (the inviter's id is the same id on both
events because both invite and claim sides observe it).
The Part-A audit (per `ohm-rfc/ROADMAP.md` #21) confirms these
shapes against real data once a week of beta traffic is in. The
audit is a point-in-time pass; this chapter is the standing
discipline that keeps future work in shape.
### 21.8 Secret vs. public — overlay binding
The Amplitude browser API key (`VITE_AMPLITUDE_API_KEY`) is
**bundle-embedded by design**: it appears as a literal string in
the deployment's JavaScript bundle, visible to anyone with browser
dev tools. The vendor's installation prompt embeds it inline. This
puts it in the same category as Cloudflare Turnstile's site key
(`VITE_TURNSTILE_SITE_KEY`, v0.12.0) — public, not secret.
Deployments **MUST** bind such keys via their overlay verb (for
OHM-shape deployments, `flotilla overlay set`), not via the secret
binding. The matching secret half (the Cloudflare Turnstile
**secret** key, `CLOUDFLARE_TURNSTILE_SECRET`, used server-side
for siteverify) is a true secret bound via `flotilla secret set`.
This per-key distinction is the deployment's responsibility; the
framework's `*.env.example` files name the binding for each.
The binding rule baked in mid-Session-K is: **the operator's
secret bytes never enter the conversation with an assistant**,
even as one offered option. The conversation-layer corollary of
the build-pipeline §3-invariant-1 rule from
`ohm-rfc-app-flotilla/SPEC.md` is that sessions publish in full,
and a secret in a transcript is a leaked secret. The canonical
secret-set gesture for OHM is `pbpaste | flotilla secret set
<deployment> <SECRET_NAME>` (the value goes clipboard → stdin →
Secret Manager without ever appearing in shell history or the
model context). Non-OHM deployments inherit the same discipline
through their own deploy tooling.
### 21.9 §19.2 candidates surfaced by this chapter
- **Session-replay-specific consent category.** v0.13.0's cookie
banner has a single `analytics` toggle that gates both event
counters and full-DOM session replay. Recording has a larger
privacy footprint than counters; a separate consent category
for session replay is the cleaner shape. Captured here and in
`ohm-rfc/ROADMAP.md` #21 Part A.
- **Bundle-size budget for the analytics wrapper.** The
`@amplitude/unified` package adds ~150 KB gzipped (the session-
replay recorder is the bulk). The consent-gated lazy import
keeps the cost off the initial bundle for users who haven't
opted in; the post-consent init path has not been measured
for jank. Captured in #21 Part A.
- **Property-shape lint.** The conventions in §21.1 / §21.2 are
enforced today by review discipline. A small lint (CI grep
against `track(` / `identify(` callsites with a property-key
allowlist + a PII-name denylist) is a future affordance that
catches drift mechanically.
- **Hashed `target_email` derivation.** §21.2 names SHA-256 of
the normalized lower-cased email as the hashing function. The
framework does not currently expose a helper for this — a
small `frontend/src/lib/hash.js` or `backend/app/hash.py` that
centralizes the normalization + hash would make the contract
enforceable. Captured here.
### 21.10 Open question
The wrapper currently uses the Amplitude SDK's autocapture +
session-replay defaults. The v0.13.0 consent surface has a single
toggle for "analytics." Splitting the consent into "analytics"
vs "session replay" is a §19.2 candidate (above) but settling it
also requires a privacy-policy update and a re-prompt of
existing consenters. The cleanest moment to do this is the next
material privacy-policy revision; the conventions in §21.4 hold
in the interim.