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.
Ben Stull