Ullrich Schäfer 37073eafd7 Spec catchup: drift fixes, account-settings split, notifications archive

Drift (specs aligned to shipped code):
- social-follows: locked-account access rule for /users/:u/followers and
  /users/:u/following (owner + accepted-follower see; non-followers of
  private get 404). Adds the follow→notification lifecycle requirement.
  Fills the placeholder Purpose.
- public-profiles: counts degrade to plain text (not anchors) for viewers
  who can't see the lists. Cross-references social-follows. Fills the
  placeholder Purpose.
- journal-auth slimmed to cookie session + Terms gate. Auth methods moved
  out (see authentication-methods).

Splits:
- account-settings (14-line stub) deleted, content split into:
  - profile-settings (display name, bio, profile_visibility)
  - account-management (email change with verification, account deletion)
  - connected-services (Wahoo + future external integrations)
- authentication-methods split out of journal-auth: passkeys
  (register/login/add/delete), magic links, 6-digit codes
  (login + register), method toggle on register/login forms,
  dev-console fallback.

New specs:
- sse-broker: /api/events, in-process broker, useUnreadNotifications
  hook, Caddy passthrough, multi-process forward-compat contract.

Archived: notifications change → openspec/changes/archive/2026-04-26-notifications.
Promoted the four delta spec files into top-level specs:
- specs/notifications/ (new capability)
- specs/activity-feed/ (added: public activity fan-out)
- specs/journal-landing/ (added: Notifications navbar entry)
- specs/social-follows/ (added: follow→notification lifecycle)

Added openspec/CAPABILITIES.md grouped index covering all 40 specs with
a Conventions section explaining cross-references, naming, and the
catch-up-vs-change rule.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

2026-04-26 02:02:43 +02:00

6.1 KiB

Raw Blame History

Capabilities Index

Top-level index of every spec under openspec/specs/, grouped by area. Each spec describes a capability the platform exposes (or supports internally). Use this as the entry point when navigating the spec library — the alphabetical directory listing is fine for grep, but groupings make it easier to spot drift, overlap, and coverage gaps.

When adding a new spec, slot it into the most relevant group below and update this index in the same change. When merging or splitting specs, update both the directory and this index in the same change.

Identity & access

journal-auth — cookie session, terms-of-service consent gate (initial accept + re-accept on version bump).
authentication-methods — passkeys (WebAuthn), magic links, 6-digit codes, the method toggle on register/login forms.
security-hardening — cross-cutting hardening (CSP, headers, rate-limit-adjacent concerns).
rate-limiting — per-route rate-limit policy.

Profile & settings

profile-settings — display name, bio, profile-visibility editing UX.
account-management — email change with re-verification, account deletion (irreversible, cascades).
connected-services — third-party integrations (Wahoo today; Strava, Garmin later) connected from settings.
public-profiles — /users/:username page (full vs. locked stub), open-graph metadata.

social-follows — follow API, follower/following collections (with locked-account access rules), Pending request lifecycle, /feed.
activity-feed — the /feed aggregation behavior (note: also referenced from social-follows; this spec covers feed-specific concerns).

Notifications & realtime

notifications — notifications table, four event types (follow_request_received / follow_request_approved / follow_received / activity_published), generation hooks, fan-out, /notifications page with cursor pagination, mark-read APIs, 90-day retention.
sse-broker — /api/events endpoint, in-process pub/sub registry, client EventSource hook, Caddy passthrough. Transport-only; specific event payloads are owned by the capability that emits them (notifications today).

Routes (Planner core)

planner-session — anonymous Yjs session lifecycle.
session-notes — per-session shared notes.
route-management — CRUD around saved routes.
route-preview — preview rendering of saved routes.
route-drag-reshape — drag-to-reshape interaction.
route-splitting — split routes at points.
route-coloring — generic line color modes.
road-type-coloring — road-type-specific color mode.
elevation-map-interaction — hover-to-locate between elevation chart and map.
multi-day-routes — overnight markers + per-day export.
no-go-areas — drawn polygons that re-route avoidance.
crash-recovery — recovering an interrupted session.
planner-journal-handoff — JWT-callback save flow back to Journal.

Routing engine

brouter-integration — BRouter container + routing-host election + the API the client expects.

Map / overlays

map-core — shared Leaflet wrappers in @trails-cool/map.
map-display — base-tile selection and rendering.
osm-tile-overlays — OSM raster overlays.
osm-poi-overlays — POI overlay layer.

Imports

gpx-import — GPX file parsing and route ingestion.
wahoo-import — Wahoo activity sync rules.

Journal landing & content

journal-landing — anonymous landing + signed-in personal dashboard.
legal-disclaimers — Terms / Privacy / Imprint pages.
transactional-emails — magic-link, welcome, etc. email templates.

Infrastructure & ops

infrastructure — Hetzner host topology, Caddy front, vSwitch.
local-dev-environment — pnpm dev orchestration, Docker services.
secret-management — SOPS-encrypted env files, key rotation.
observability — Prometheus, Loki, Grafana dashboards.
shared-packages — workspace package boundaries (@trails-cool/types, @trails-cool/map, etc.).

Conventions

Spec filenames use kebab-case capability names (profile-settings, social-follows, sse-broker).
Cross-spec references should link to the other spec's path rather than duplicate requirements (see public-profiles linking to social-follows for the followers/following list access rule, and account-management linking to journal-auth for the Terms gate).
New behavior lands through openspec/changes/<name>/ with a delta in specs/<capability>/spec.md. The delta is promoted to the top-level spec when the change is archived (via /opsx:archive).
Drift catch-up — i.e. updating a spec to match shipped code without changing behavior — can be edited directly without a change, since there's no behavioral payload to propose. Always update CAPABILITIES.md in the same edit if a spec is added, removed, or renamed.

6.1 KiB Raw Blame History