pal-e-docs

Review: Write convention-sveltekit-spa convention note

review-412-2026-03-26 Review

review needs-refinement
Project

Verdict: NEEDS_REFINEMENT

Template Completeness

  • [x] Type — Feature
  • [x] Lineage — Related to phase-pal-e-platform-29-sveltekit-convention
  • [x] Repo — forgejo_admin/pal-e-app
  • [x] User Story — well-formed As/I want/So that
  • [x] Context — explains mcd-tracker-app as proven pattern, Phase 29 origin, capacitor-mobile dependency
  • [x] File Targets — documentation-only with reference files listed
  • [x] Acceptance Criteria — 4 criteria, all verifiable
  • [x] Test Expectations — includes exact MCP tool commands
  • [x] Constraints — extract-only, follow convention-frontend-css style, cover Capacitor detection
  • [x] Checklist — 3 items
  • [x] Related — 4 related notes listed

Traceability

  • [ ] story:X label — MISSING. Board item #412 has labels type:feature,arch:convention but no story: label. This work serves the developer-building-apps user story. Needs a story label (e.g. story:dev-execute or a capacitor-specific story).
  • [x] arch:convention label — present on board item
  • [x] Forgejo issue — forgejo_admin/pal-e-app#51, open, valid

File Targets

  • [x] ~/mcd-tracker-app/svelte.config.js — verified: adapter-static with fallback: 'index.html', strict: true
  • [x] ~/mcd-tracker-app/src/lib/keycloak.js — verified: keycloak-js, PKCE (S256), check-sso init, Capacitor platform detection via getBaseUrl(), auto token refresh
  • [x] ~/mcd-tracker-app/src/lib/api.js — verified: client-side fetch with Bearer token from keycloak, VITE_API_URL env var with fallback
  • [x] ~/mcd-tracker-app/Dockerfile — verified: multi-stage node:22-alpine build, nginx:alpine serving, SPA fallback try_files, static asset caching

Repo Placement

Issue filed on forgejo_admin/pal-e-app. The work creates a pal-e-docs convention note — no code files are modified. The repo choice is acceptable since the convention directly serves pal-e-app architecture, and sibling items #413/#414 on the same repo consume this convention. However, Phase 29 (the parent phase) lives on board-pal-e-platform, not board-pal-e-docs. This is a minor mismatch but not blocking — the board item itself is correctly placed on board-pal-e-docs (id: 412).

Dependencies

  • Downstream (undocumented): Board item #413 ("Migrate pal-e-app auth + data fetching to client-side") and #414 ("Switch pal-e-app to adapter-static + nginx") both depend on this convention existing. Neither has a depends:412 label.
  • Parent phase: Phase 29 (board item #286 on board-pal-e-platform) lists this as Deliverable 1. Phase is in backlog column.
  • Blocked consumer: project-capacitor-mobile > sveltekit-spa-configuration section is confirmed empty (0 content blocks), waiting for this convention content.
  • No upstream blockers: All reference files exist and contain the expected patterns. No blocking dependencies.

Acceptance Criteria

All 4 acceptance criteria are agent-verifiable via MCP tools. Test expectations include exact tool calls (get_note, get_section). The "Run command: N/A" is appropriate for documentation-only work. One gap: no criterion verifies that the convention covers all 6 topics listed (stack, auth, CSS, data fetching, routing, API config) — the criteria only check existence and that it "covers" them, which is subjective. An agent could create a skeleton note and pass. Consider adding section-level verification.

Blast Radius

  • westside-app also uses adapter-static (confirmed in svelte.config.js). The convention should be written to cover this second consumer, but the issue only references mcd-tracker-app as the reference implementation. Not blocking, but the agent should be aware.
  • pal-e-app currently uses adapter-node — items #413/#414 would migrate it to match this convention.
  • westside-contracts uses adapter-node — different pattern (server-side), not a consumer.
  • convention-frontend-css exists (verified) and provides good format reference as the ticket claims.

Recommendation

Two items to fix before READY:
  • Add story: label to board item #412. Suggested: story:dev-execute or create a new story for convention documentation work.
  • Add dependency labels on items #413 and #414: depends:412 (or equivalent), so the board reflects execution order.
Optional improvements (not blocking):
  • Mention westside-app as a second consumer in the Context or Related section of the issue.
  • Add section-level acceptance criteria (e.g., "convention has sections for: stack, auth, css, data-fetching, routing, api-config").