Delivera

Delivery intelligence for scrum teams and leaders, backed by Jira.

Delivera answers what to say, who to chase, and what proof to show — in about 10 seconds on the Brief.

Primary surfaces

Route	Surface	Purpose
/governance	Brief	Delivery answer, owner actions, PI confidence, agent queue
/current-sprint	Sprint	What must move today (blockers, owners, nudges)
/report	Proof	Evidence and drill-down for the current Brief

Proof (report) above-fold: header Refresh / Export replace duplicate sidebar Preview when top chrome is present; filter summary lives in the mission strip (sidebar summary hidden when chips exist); scorecard and heavy widgets defer until opened.

Bookmarks: /brief → /governance. /leadership and /program-increment → /governance#decision-snapshot. /value-delivery → /report. /teams and /risks-blockers → /current-sprint (with #stuck-card where applicable).

Root / lands on Brief when auth is off; otherwise follows your configured auth landing.

Global chrome

Authenticated pages use a Jira-style top bar (#app-top-chrome, Delivera-Shared-Top-Chrome-01Render-UI.js):

• Brief · Sprint · Proof surface switcher (primary wayfinding)
• Sidebar toggle, workspace context, search, Create, notifications, help, settings, avatar
• Left sidebar: context card + data pulse only (nav links hidden on desktop)
• Duplicate page-level Create buttons are suppressed when top chrome is present
• Mobile/tablet (≤768px): search collapses to a 36px icon (.is-collapsed); brand slot hides; focus expands search to a second row (body.top-search-active) and grows chrome height to 98px. Help and avatar hide at ≤480px. Escape dismisses expanded search.
• Brief notifications: dock stays collapsed until the bell is tapped; on governance mobile it opens as a bottom sheet so it does not cover the scope Refresh row.
• Brief mobile with owner clusters: full command card hides; owner action clusters become the primary above-fold surface.

Notifications mount in #app-notification-slot under the top bar (Delivera-Shared-Notifications-Dock-Manager.js).

Brief highlights

• Shared project catalog (Delivera-Shared-Projects-Catalog-01SSOT.js, GET /api/projects-catalog.json)
• Loading shell: #gov-loading reuses Sprint spinner markup (Delivera-Governance-Brief-Page-02Loading-State.js); cache hit paints instantly with a scope-bar “Refreshing…” chip (preserveContent pattern)
• Cache-first paint: peekGovernanceBriefCache renders the last scoped answer before network; Refresh calls invalidateBriefCacheEntry + ?refresh=1 on client and server
• Scope SSOT: project changes call notifyScopeChanged() (Delivera-Shared-Scope-Notify-01Bridge.js) so sidebar, top chrome, and scope bar stay aligned; quarter key is GOVERNANCE_QUARTER_KEY in Delivera-Shared-Storage-Keys.js
• Client-side brief cache (Delivera-Shared-Brief-Client-Cache-01Bridge.js) and deduped quarters fetch (Delivera-Shared-Quarters-List-01Fetch-Memo.js) cut repeat network round-trips
• Brief load runs inbox + brief in parallel; scorecard defers until evidence <details> opens
• Above-fold order: answer → owner clusters → setup debt → verdict → PI strip; agent queue and feedback in collapsed <details>
• Responsive layout: scope capsule, answer blocks, PI counters, and tables use auto-fit grids + data-table-scroll-wrap (no horizontal bleed on mobile)
• Page-level Export brief hides when top chrome is present (export stays in command overflow menu)
• PI baseline wizard with optional slide upload; AI keys live in Settings (/settings#gov-ai-helper) or .env — providers: OpenAI, Claude, OpenRouter (OPENROUTER_API_KEY). Work-draft canvas links to Settings (no duplicate key UI).
• Inbox drawer with icon tabs; guided nudge review (not silent approve)

Details: context.md. Brief SSOT gate: npm run test:journey:brief-ssot. Layout gate: npm run test:journey:layout-overlap. Full governance bundle: npm run test:journey:governance.

Quickstart

Prerequisites: Node.js >=20, Jira credentials.

npm install
cp .env.example .env   # set JIRA_HOST, JIRA_EMAIL, JIRA_API_TOKEN
npm run dev:safe       # recommended: port guard + CSS watch + API reload (one server per machine)
npm run dev            # or npm run dev:hot for CSS watch + nodemon

Production-style: npm start (runs build:css first).

Dev port conflicts: dev:safe refuses to start when ports 3000–3002 are already bound. Use npm run dev:safe:force to clear listeners, or set PORT=3010 npm run dev:safe when another process owns 3000.

Playwright against an already-running server:

npm start
# another terminal:
BASE_URL=http://localhost:3000 SKIP_WEBSERVER=true npm run test:smoke

Health probe: GET /healthz returns { ok: true, ready: true } when the process is listening (used by Render and deploy smoke tests).

Auth modes

• No auth (local default): open Brief without login vars
• Legacy: SESSION_SECRET, APP_LOGIN_USER, APP_LOGIN_PASSWORD
• SuperTokens: SUPERTOKENS_ENABLED=true (optional SUPERTOKENS_HYBRID_MODE=true)

Full matrix: docs/environment.md

Common commands

Command	Use
npm run build:css	Compile public/css/* → public/styles.css
npm run check:css	Fail if styles.css is out of sync
npm run validate:jira-env	Probe Jira /myself with .env
npm run dev:safe	Port guard + CSS watch + API reload (recommended)
npm run dev:hot	Single-port dev with CSS + API reload
npm run test:all	Full fail-fast orchestration
npm run test:smoke	Short UX smoke
npm run test:current-sprint:dedupe-fold	Sprint header/viewport gate
npm run test:journey:brief-ssot	Brief loading shell, cache-first paint, scope sync, Refresh bypass
npm run test:journey:layout-overlap	Governance/report/sprint layout overlap + mobile clip gate (fail-fast)
npm run test:journey:governance	Brief / governance Playwright bundle
npm run test:journey:ux-core	Cross-surface UX gate
npm run vercel:deploy	Manual Vercel deploy after vercel login

Orchestration, journeys, and SKIP_WEBSERVER: TESTING.md

CSS contract

Edit partials under public/css/ only. Never edit public/styles.css directly.

npm run build:css
npm run check:css

Ownership: public/css/README.md

Deployment

• Render: render.yaml — always-on Node, background workers
• Vercel: root index.js + vercel.json — zero-config Express; workers disabled

Pre-deploy: npm run build:css, npm run check:css, then your chosen test gate.

Vercel note: vercel.json bundles public/** into the serverless function for HTML routes (/governance, etc.). If deploy fails on includeFiles, clear conflicting Functions overrides in the Vercel project dashboard.

Full guide: docs/deployment.md

Documentation

Topic	Doc
Environment	docs/environment.md
Deployment	docs/deployment.md
API	docs/api-reference.md
Troubleshooting	docs/troubleshooting.md
Release history	docs/release-notes.md
Testing	TESTING.md
Architecture	context.md

Architecture (short)

• Entry: server.js — listenWithRetry, graceful SIGTERM/SIGINT drain, deferred background workers
• Lifecycle: lib/Delivera-Server-Lifecycle-01Graceful.js
• Worker leader lock (multi-instance): lib/Delivera-Worker-Leader-01Lock.js when WORKER_LEADER_LOCK=1 or INSTANCE_COUNT>1
• App factory: lib/Delivera-Express-Core-App-Factory-Handler.js
• Routes: routes/views.js, routes/api.js (GET /healthz)
• UI: public/*.html, public/Delivera-*.js, compiled public/styles.css
• Fetch retry on 502/503: public/Delivera-Shared-Runtime-Notification-Bridge.js

License

MIT