From fe07dd9cba20a7d3f318553ff1e3c2ecd9508167 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Thu, 15 Oct 2026 10:25:50 +0000 Subject: [PATCH] docs(sps): add six SPS review docs fitted to repo facts Co-authored-by: The Gaffer --- docs/DECISIONS/README.md | 45 ++++++++++++++ docs/LICENSING.md | 46 +++++++++++++++ docs/OPERATIONS.md | 84 ++++++++++++++++++++++++++ docs/OWNERSHIP.md | 60 +++++++++++++++++++ docs/PROJECT_OVERVIEW.md | 123 +++++++++++++++++++++++++++++++++++++++ docs/RELEASES.md | 68 ++++++++++++++++++++++ 6 files changed, 426 insertions(+) create mode 100644 docs/DECISIONS/README.md create mode 100644 docs/LICENSING.md create mode 100644 docs/OPERATIONS.md create mode 100644 docs/OWNERSHIP.md create mode 100644 docs/PROJECT_OVERVIEW.md create mode 100644 docs/RELEASES.md diff --git a/docs/DECISIONS/README.md b/docs/DECISIONS/README.md new file mode 100644 index 0000000..de7afdc --- /dev/null +++ b/docs/DECISIONS/README.md @@ -0,0 +1,45 @@ +> SPS_REVIEW_REQUIRED — this file is an unreviewed scaffold. A repository owner must verify every statement against the sources cited and remove this marker only after review. + +# Architecture Decision Records + +ADRs record **decisions that were actually made**. Do not fabricate historic decisions +or retroactively claim approvals. New entries follow the repository's established ADR +format. + +## Where decisions already live (check these first) + +| Location | Content | +| --- | --- | +| `docs/adr-001-nextjs-app-router.md` | Accepted 2026-01-15: Next.js App Router + React 19 (decider: Drferdi, Principal Architect); rationale, consequences, mitigations | +| `.agents/DECISIONS.md` | Append-only capsule log, newest first; e.g. 2026-09-26 migration from `abyss-monorepo` to SAFRS standalone capsule (toolchain pnpm 11.21.0, Node 24) | +| `.agents/HANDOFF.md` | Session handoff (overwritten, not appended); current next action: re-point the Vercel project for `sentrahai.com` to the capsule root (Chief) | +| `ARCHITECTURE.md` + `docs/architecture.md` | Architecture deep-dive + short overview | +| `CHANGELOG.md` | Dated record of notable changes (Keep a Changelog / SemVer), including the 2026-04-18 docs-truth audit | +| `docs/deployment.md` | Deployment decisions as documented (Railway); see `docs/OPERATIONS.md` for the Vercel note in `.agents/HANDOFF.md` | + +There is no `docs/adr/` directory in this repo; the only ADR file is +`docs/adr-001-nextjs-app-router.md`. TODO for Gaffer: confirm where future ADRs should +live (same `docs/` level with sequential numbering, or a new `docs/adr/` directory). + +## Format for a new ADR (mirrors `docs/adr-001-nextjs-app-router.md`) + +- Title, status, date, deciders. +- Context (the problem, with repo evidence). +- Decision (what was chosen). +- Rationale (criterion → reason table). +- Consequences (positive / negative) and mitigations. +- Signature line used by this repo (`_Architected and built by Drferdi …_` is the + convention in existing docs; `CONTRIBUTING.md` requires `// Architected and built by + Drferdi.` in new code files). + +## Rules + +- Durable capsule decisions go to `.agents/DECISIONS.md` (dated heading, decision, + rationale, evidence); session state goes to `.agents/HANDOFF.md` (overwrite, ~1k + tokens). +- Clinical-capability claims (e.g. `featureList` in `app/layout.tsx`, demo datasets in + `SentraSim`/`ClinicalTrajectory`/`ClinicalPrognosis`) require Chief verification + (`docs/ai-governance.md`, `CONTRIBUTING.md`) — an ADR does not substitute for that + sign-off. +- TODO for Gaffer: designate the ADR approver and whether ADRs need a second reviewer + beyond the decider. diff --git a/docs/LICENSING.md b/docs/LICENSING.md new file mode 100644 index 0000000..00fee83 --- /dev/null +++ b/docs/LICENSING.md @@ -0,0 +1,46 @@ +> SPS_REVIEW_REQUIRED — this file is an unreviewed scaffold. A repository owner must verify every statement against the sources cited and remove this marker only after review. + +# Licensing and Intellectual Property — Sentraverse + +This file summarizes the license posture. The binding text is the existing +[`LICENSE`](../LICENSE) file at the repository root — nothing here grants rights beyond +it. + +## Current status (from `LICENSE`) + +- Proprietary software license. Copyright `© 2025–2026 Sentra Healthcare Solutions. All + rights reserved.` Founder & Clinical Steward: Dr. Ferdi Iskandar, S.H., M.Kn., CMDC, + CLM. +- Unauthorized use strictly prohibited without prior express written permission: no + copying, reproducing, duplicating, distributing, publishing, transmitting, + modifying, adapting, translating, reverse-engineering, sublicensing, selling, + renting, leasing, commercial exploitation, or use to train machine-learning/AI + systems. +- Permitted use is limited to (a) internal development and review by authorized Sentra + team members, and (b) security research under a signed responsible-disclosure + agreement. +- Clinical disclaimer: the software is a clinical decision-support tool, not a certified + medical device under any regulatory framework (BPOM, Kemenkes, FDA, MDR, or + equivalent) unless stated in separate regulatory documentation; all clinical outputs + assist — not replace — licensed healthcare professionals. +- No warranty ("AS IS"); no liability for claims/damages from use or inability to use. +- Contact for commercial licenses or vulnerability reports: email + `drferdiiskandar@melinda.co.id`, web `https://sentrahai.com`. + +## Notes and required confirmations + +- `README.md` §25 states `ISC © 2026 Sentra Healthcare Solutions`, and `package.json` + declares `"license": "ISC"`. These differ from the proprietary `LICENSE` file above, + which is the binding text in the repo. +- TODO for Gaffer: reconcile the `ISC` references in `README.md` §25 and `package.json` + with the proprietary `LICENSE` file, and confirm the approved public license line. +- Third-party dependencies are listed in `package.json` (`dependencies` / + `devDependencies`) with a `pnpm-lock.yaml` and `pnpm-workspace.yaml` overrides; no + license-attribution inventory exists in the repo. +- TODO for Gaffer: confirm third-party license obligations/attribution, whether any + source-available or server-side components must remain private, and the authorization + required before any distribution beyond the permitted uses in `LICENSE`. + +A repository being accessible does not make it open-source. Do not describe this +repository as open-source unless the owner replaces `LICENSE` with an approved +open-source text and updates `README.md` and `package.json` to match. diff --git a/docs/OPERATIONS.md b/docs/OPERATIONS.md new file mode 100644 index 0000000..b1be2ad --- /dev/null +++ b/docs/OPERATIONS.md @@ -0,0 +1,84 @@ +> SPS_REVIEW_REQUIRED — this file is an unreviewed scaffold. A repository owner must verify every statement against the sources cited and remove this marker only after review. + +# Operations Runbook — Sentraverse + +This runbook describes only what the repository states. It does not authorize +production intervention. For release authority and gates, see `docs/RELEASES.md`. + +## Commands (capsule root, via `node scripts/pnpm.mjs` — `AGENTS.md`) + +| Purpose | Command | +| --- | --- | +| Install | `node scripts/pnpm.mjs install --frozen-lockfile` | +| Lint | `node scripts/pnpm.mjs run lint` (`eslint .`) | +| Typecheck | `node scripts/pnpm.mjs run typecheck` (`tsc --noEmit`) | +| Test | `node scripts/pnpm.mjs run test` (`node --test app/api/medical-knowledge/route.test.mjs`) | +| Build | `node scripts/pnpm.mjs run build` (`next build --webpack`) | +| Run | `node scripts/pnpm.mjs run start` (serves `127.0.0.1:4340`; contract smoke: `GET /` → 200) | +| Deploy dry-run | `node scripts/pnpm.mjs run deploy:dry-run` | +| Browser E2E smoke | `node scripts/pnpm.mjs run test:e2e` (`playwright test` over `e2e/smoke.spec.ts`; needs Playwright browsers installed) | + +Local development: `pnpm dev` (webpack, stable) or `pnpm dev:turbo` (experimental) on +`http://localhost:3000`; production preview via `pnpm build && pnpm start` +(`README.md` §17, `docs/setup.md`). Use pnpm, not npm/yarn/bun (`README.md` §17). +The site runs with zero required environment configuration (`README.md` §17). + +## Configuration and secrets posture + +- Optional env vars (`README.md` §18, `project.contract.json`, `next.config.mjs`): + `NEXT_PUBLIC_PILOT_LOGIN_URL` (client CTA target; allow-listed to `sentrahai.com` + hosts, falls back to `/dashboard`), `SENTRA_DASHBOARD_URL` (server; enables + `/dashboard/:path*` rewrites), `SENTRA_ASSISTVERSE_URL` (server; `/asisten-medis` + rewrite, defaults to `https://site-assist-seven.vercel.app`), `GEMINI_API_KEY` + (optional; `/api/medical-knowledge` forwards the question only when set — + `docs/data.md`, nothing persisted). +- `.env.example` lists placeholder entries (`NEXTAUTH_SECRET`, `NEXTAUTH_URL`, + `DATABASE_URL`, `ANTHROPIC_API_KEY`, `SENTRY_DSN` as `TO_BE_SUPPLIED_BY:*`); the repo + states no env vars are required to run the dev server (`docs/setup.md`). +- Never expose secrets or patient data; do not use production credentials or production + data (`AGENTS.md`). Name environment variables, never their values (`.agents/CONTEXT.md` + convention). No hardcoded secrets, API keys, or credentials in PRs (PR template + security checklist). + +## Deployment targets (as documented — verify before operating) + +- `docs/deployment.md` documents Railway (auto-detected Next.js; `npm run build` / + `npm run start`; production `https://sentrahai.com`; rollback via `railway rollback` + or dashboard redeploy; post-deploy `curl` checks for headers, sitemap, robots, + `llms.txt`). +- `.agents/HANDOFF.md` (2026-09-26) records the next action as re-pointing the Vercel + project for `sentrahai.com` to the capsule root (Chief); `.github/workflows/ci.yml` + header notes "Deploy ditangani Vercel". +- TODO for Gaffer: confirm the current production target (Railway vs. Vercel), who can + deploy, and the authoritative rollback procedure. + +## Health signals and verification + +- Contract smoke: `GET http://127.0.0.1:4340/` → `200`, artifact `.next/BUILD_ID` + (`project.contract.json`). +- Deploy dry-run (`scripts/deploy-dry-run.mjs`, no network, no credentials): requires + `.next/BUILD_ID` (build first) and fails if `GEMINI_API_KEY` or + `SENTRA_DASHBOARD_URL` appear in the client bundle. +- E2E smoke (`e2e/smoke.spec.ts`): homepage `main` landmark renders; `/insights`, + `/story`, `/privacy`, `/terms` return 200; `#contact` with "Join Waiting List" link is + visible. `playwright.config.ts` serves `pnpm dev` with 120s timeout. +- Security headers on all routes (`next.config.mjs` `headers()`, `SECURITY.md`): + `X-Content-Type-Options`, `X-Frame-Options: DENY`, `X-XSS-Protection`, + `Referrer-Policy`, `Permissions-Policy`, `Strict-Transport-Security` + (`max-age=63072000; includeSubDomains; preload`), `Content-Security-Policy`. +- Manual checklist before production (`docs/testing.md`): 15 home components without + console errors, nav/overlay behavior, article pages + 404 for unknown slugs, SEO nodes + (JSON-LD, sitemap, robots, `llms.txt`), responsive breakpoints, header presence via + `curl -I`. + +## Incident handling + +- Report vulnerabilities privately per `SECURITY.md` (see `docs/OWNERSHIP.md`); do not + open a public issue. +- Preserve evidence, restrict sensitive data, and request authorization before any + production intervention. This site processes no PHI and has no database or user + sessions (`SECURITY.md`, `docs/data.md`). + +TODO for Gaffer: confirm monitoring, alert routing, on-call ownership, backup/restore +scope (static site — confirm whether any state needs recovery), and capacity/cost +ownership. No runbook in the repo states these today; do not infer them from this file. diff --git a/docs/OWNERSHIP.md b/docs/OWNERSHIP.md new file mode 100644 index 0000000..0c0d0cf --- /dev/null +++ b/docs/OWNERSHIP.md @@ -0,0 +1,60 @@ +> SPS_REVIEW_REQUIRED — this file is an unreviewed scaffold. A repository owner must verify every statement against the sources cited and remove this marker only after review. + +# Repository Ownership and Governance — Sentraverse + +## Authority (facts in the repo) + +- **Human owner:** Chief (dr. Ferdi Iskandar) — `AGENTS.md` ("Objective and ownership"), + `project.contract.json` (`owner`), `.agents/CONTEXT.md`. +- **Default risk:** `R1`. Breaking public routes or the `/dashboard` and `/asisten-medis` + rewrites needs review (`AGENTS.md`). +- **Clinical content authority:** all clinical claims (statistics, accuracy metrics, demo + dataset values in `SentraSim`, `ClinicalTrajectory`, `ClinicalPrognosis`, copy in + `app/insights/data.ts`, `components/Services.tsx`, `components/Hero.tsx`) must be + verified by Chief (Dr. Ferdi Iskandar) before merge/publication (`CONTRIBUTING.md` + "Clinical Content Policy", `docs/ai-governance.md`, `.github/PULL_REQUEST_TEMPLATE.md` + content checklist). +- **Protected areas:** security headers and rewrites in `next.config.mjs`; + `/api/medical-knowledge` (`.agents/CONTEXT.md`). The PR template additionally requires + review for changes to `headers()` security configuration and `remotePatterns` + (`next.config.mjs`). +- **Security reports:** privately to `drferdiiskandar@melinda.co.id` with subject + `[SECURITY] sentra-main — `; no public GitHub issue; 48-hour + acknowledgement, 90-day remediation window requested (`SECURITY.md`). +- **License contact:** `LICENSE` names Sentra Healthcare Solutions, founder & clinical + steward Dr. Ferdi Iskandar, contact `drferdiiskandar@melinda.co.id` / + `https://sentrahai.com` (see `docs/LICENSING.md`). + +## Module and path stewardship (from repo structure) + +- Public routes and composition: `app/` (landing `app/page.tsx`, `story`, `insights`, + `sentrapedia`, `ekosistem`, `sentrawiki`, `privacy`, `terms`, `api/`). +- Section and showcase components: `components/` (including `blueprint-story/`, + `sentrasim/`, `sentrapedia/`, `sentrawiki/`, `ekosistem/`, `ui/`). +- Governance primitives: `lib/design-governance.ts`, `lib/site-links.ts` (internal link + single source of truth), `lib/use-smooth-scroll.ts`, `lib/utils.ts`. +- Docs: root `README.md`, `ARCHITECTURE.md`, `CHANGELOG.md`, `CONTRIBUTING.md`, + `SECURITY.md`, `ROADMAP.md`, plus `docs/` index (`docs/README.md`). Durable capsule + decisions: `.agents/DECISIONS.md`. + +TODO for Gaffer: confirm per-module maintainers (if any beyond the owner above), the +security contact for non-vulnerability governance questions, and the escalation channel. + +## Collaboration rules + +- This capsule owns its runtime (own pnpm workspace, lockfile, scripts, build config) + and never depends on another capsule; do not modify other capsules or shared packages + without recording scope expansion (`AGENTS.md`). +- `CONTRIBUTING.md` workflow: branch from `main`, `lint` with zero errors, `build` + without TypeScript errors, open a PR against `main` with the template completed; + commit format `type(scope): description` (`feat`, `fix`, `content`, `style`, + `refactor`, `docs`, `chore`, `perf`). +- CI (`.github/workflows/ci.yml`): on push to `main`/`master`/`claude/**`/`feature/**` + and on PRs to `main`/`master`, `lint` must pass before `build` runs + (pnpm `11.21.0`, Node `24`, `pnpm install --frozen-lockfile`). +- Documentation improvements do not grant permission to modify software, CI, secrets, or + deployment configuration. + +TODO for Gaffer: confirm branch/merge rules (required reviewers, protected paths beyond +`next.config.mjs` and `/api/medical-knowledge`, merge vs. squash policy) — the repo +states the PR template and CI gates but no explicit branch-protection settings. diff --git a/docs/PROJECT_OVERVIEW.md b/docs/PROJECT_OVERVIEW.md new file mode 100644 index 0000000..123b6f7 --- /dev/null +++ b/docs/PROJECT_OVERVIEW.md @@ -0,0 +1,123 @@ +> SPS_REVIEW_REQUIRED — this file is an unreviewed scaffold. A repository owner must verify every statement against the sources cited and remove this marker only after review. + +# Project Overview — Sentraverse + +Public Sentra marketing website and platform hub for `sentrahai.com` (see `AGENTS.md` +"Objective and ownership" and `.agents/CONTEXT.md`). Domain: `healthcare` +(`project.contract.json` id `healthcare/sentraverse`). + +## What this repository is + +- **Project:** Sentraverse — the official website, product narrative layer, and public + knowledge surface for Sentra Healthcare AI (`README.md` §01). +- **Audience stated in `README.md`:** Puskesmas, klinik pratama, referral hospitals, + clinicians, healthcare operators, public-sector stakeholders, and technical partners. +- **Clinical posture:** clinical decision support (CDSS). Sentra supports clinical + reasoning, triage awareness, workflow acceleration, and timely escalation; it does not + replace professional medical judgment (`README.md` §10–§11, §24; `docs/ai-governance.md`, + `docs/clinical-logic.md`). +- **Human owner:** Chief (dr. Ferdi Iskandar) — `AGENTS.md`, `project.contract.json` + (`owner`), `.agents/CONTEXT.md`. +- **Default risk:** `R1`. Breaking public routes or the `/dashboard` and `/asisten-medis` + rewrites needs review (`AGENTS.md`). + +## Product surfaces and routes + +Content surfaces and routes as documented in `README.md` §07 and §12 (verified against +`app/`): + +| Surface | Route | Source | +| --- | --- | --- | +| Clinical-AI landing (15-section scroll experience, `app/page.tsx`) | `/` | `app/page.tsx`, `README.md` §08–§09 | +| Founder story, milestones, roadmap | `/story` | `app/story/` | +| Clinical-AI editorial index (`app/insights/data.ts`) | `/insights`, `/insights/[slug]` | `app/insights/` | +| 144-disease primary-care clinical reference | `/sentrapedia` | `app/sentrapedia/`, `components/sentrapedia/` | +| Product ecosystem and application catalog | `/ekosistem` | `app/ekosistem/`, `components/ekosistem/` | +| Architecture, governance, compliance knowledge base | `/sentrawiki` | `app/sentrawiki/`, `components/sentrawiki/` | +| Privacy policy / Terms of use | `/privacy`, `/terms` | `app/privacy/`, `app/terms/` | +| Supporting API routes | `/api/medical-knowledge`, `/api/melinda/chat`, `/api/melinda/ocr`, `/api/sentra-assist` | `app/api/` | +| Dashboard rewrite (proxied when `SENTRA_DASHBOARD_URL` is set) | `/dashboard/:path*` | `next.config.mjs` `rewrites()` | +| Assistverse rewrite (defaults to `https://site-assist-seven.vercel.app`) | `/asisten-medis`, `/asisten-medis/:path*` | `next.config.mjs` `rewrites()` | + +SEO/discoverability assets: `app/sitemap.ts`, `app/robots.ts` (disallows `/dashboard`), +`app/opengraph-image.tsx`, JSON-LD in `app/layout.tsx`, `public/llms.txt`, Google Search +Console file `app/google22238cc24e0d1002.html` (`README.md` §20, `CHANGELOG.md`). + +## Non-goals and boundaries (from the repo) + +- No database and no persistent data: content is static TypeScript data under `app/` and + `components/`; no patient data is collected or stored (`docs/data.md`, + `docs/data-model.md`, `docs/privacy.md`). +- No autonomous diagnosis or treatment claims; Sentra AI is not registered as a medical + device (`README.md` §24, `LICENSE` "CLINICAL DISCLAIMER"). +- Never expose secrets or patient data; do not use production credentials or production + data (`AGENTS.md` "Prohibited actions"). + +## Stack (verified in `package.json`) + +- Next.js `16.3.8` (App Router, `--webpack` for dev/build), React 19, TypeScript `5.9` + (strict), Tailwind CSS v4 (`@theme` in `app/globals.css`), GSAP `3.14` + ScrollTrigger, + Framer Motion `12`, `pnpm@11.21.0`. +- Runtime contract: Node 24 (`project.contract.json`, `.github/workflows/ci.yml` + `node-version: '24'`); `package.json` `engines` requires `>=24 <25`. `README.md` §17 + states Node `>= 22` / pnpm `>= 9` — TODO for Gaffer: confirm which minimum the docs + should state. +- Package name/version: `@the-abyss/sentraverse` `1.0.0` (`package.json`). +- Standalone capsule: own `pnpm-workspace.yaml`, lockfile, scripts, and build config; no + dependency on an enclosing workspace (`AGENTS.md`, `pnpm-workspace.yaml` comments). + +## Scripts (`package.json`, run via `node scripts/pnpm.mjs` per `AGENTS.md`) + +| Script | Command | +| --- | --- | +| `dev` | `next dev --webpack` (local server `http://localhost:3000` per `README.md` §17) | +| `dev:turbo` | `next dev --turbopack` | +| `build` | `next build --webpack` | +| `start` | `next start --hostname 127.0.0.1 --port 4340` (contract `run`/smoke: `127.0.0.1:4340/`) | +| `lint` | `eslint .` | +| `typecheck` | `tsc --noEmit` | +| `test` | `node --test app/api/medical-knowledge/route.test.mjs` | +| `test:e2e` | `playwright test` (`e2e/smoke.spec.ts`; needs Playwright browsers installed) | +| `deploy:dry-run` | `node scripts/deploy-dry-run.mjs` (requires `.next/BUILD_ID`; fails if server-only names `GEMINI_API_KEY`, `SENTRA_DASHBOARD_URL` appear in the client bundle) | + +External services are declared by environment-variable name only +(`project.contract.json`): npm registry (required), `GEMINI_API_KEY` (optional, for +`/api/medical-knowledge`), `SENTRA_DASHBOARD_URL` (optional), `SENTRA_ASSISTVERSE_URL` +(optional). Client CTA target `NEXT_PUBLIC_PILOT_LOGIN_URL` falls back to `/dashboard` +(`README.md` §18). + +## Repository map (top level) + +`AGENTS.md`, `ARCHITECTURE.md`, `CHANGELOG.md`, `CONTRIBUTING.md`, `SECURITY.md`, +`README.md`, `ROADMAP.md`, `LICENSE`, `app/`, `components/`, `lib/`, `src/` (README only), +`tests/` (README only), `docs/`, `e2e/`, `public/`, `scripts/` (`deploy-dry-run.mjs`, +`pnpm.mjs`, `setup.sh`), `next.config.mjs` (security headers + rewrites), `package.json`, +`pnpm-workspace.yaml`, `pnpm-lock.yaml`, `.github/` (CI `lint` + `build`, PR template), +`.agents/` (`HANDOFF.md`, `CONTEXT.md`, `DECISIONS.md`). + +Canonical docs: `README.md`; `ARCHITECTURE.md` (deep-dive) with overview in +`docs/architecture.md`; `docs/` index in `docs/README.md`; `CHANGELOG.md` (Keep a +Changelog / SemVer); `CONTRIBUTING.md`; `SECURITY.md`. + +## Contacts stated in the repo + +- Founder & CEO: dr. Ferdi Iskandar (`README.md` §26). +- Email (public site contact): `drferdiiskandar@sentrahai.com` (`README.md` §26). +- License/security contact: `drferdiiskandar@melinda.co.id`, web `https://sentrahai.com` + (`LICENSE`, `SECURITY.md` with `[SECURITY]` subject line). +- Lab/location as stated in `README.md` §26: Melinda Advanced Technology Laboratory, + Kediri, East Java. + +TODO for Gaffer: confirm the current public contact address and which inbox handles +security reports, licensing requests, and pilot inquiries. + +## Success criteria (repo-stated) + +- Production-facing changes pass build, lint, and Playwright smoke validation + (`README.md` §17); CI runs `lint` then `build` on push/PR to `main`/`master` + (`.github/workflows/ci.yml`). +- TypeScript strict build, ESLint, Playwright smoke, stable GSAP pinned sections, + CDSS-boundary language, visible accurate medical disclaimer, valid sitemap/robots/ + metadata/OG/JSON-LD (`README.md` §19). +- Clinical claims (statistics, accuracy metrics, demo dataset values) require Chief + sign-off before merge (`CONTRIBUTING.md`, `docs/ai-governance.md`, PR template). diff --git a/docs/RELEASES.md b/docs/RELEASES.md new file mode 100644 index 0000000..13faf1c --- /dev/null +++ b/docs/RELEASES.md @@ -0,0 +1,68 @@ +> SPS_REVIEW_REQUIRED — this file is an unreviewed scaffold. A repository owner must verify every statement against the sources cited and remove this marker only after review. + +# Release Procedure — Sentraverse + +This file documents the release mechanics the repository states. It does not authorize +any release, publish, merge, push, or deployment. + +## Versioning and changelog + +- Versioning: Semantic Versioning; changelog format: Keep a Changelog (`CHANGELOG.md` + header). Current package version: `1.0.0` (`package.json` `version`). +- `[Unreleased]` section records the 2026-04-18 docs-truth audit and planned items + (lazy-loading, per-page OG metadata, `ClinicalPrognosis` promotion, OpenTelemetry, + RSC migration, bundle-analyzer wiring); `[1.0.0]` (2026-03-16) records pages, the four + articles in `app/insights/data.ts`, landing sections, UI primitives, design tokens, + SEO/metadata, and infrastructure (`CHANGELOG.md`). +- TODO for Gaffer: confirm who cuts a version (bumps `package.json`, writes + `CHANGELOG.md`) and the tagging convention — the repo states the format but no release + owner or tag practice. + +## Authority and gates + +- Clinical content gate: new clinical claims (statistics, accuracy metrics), article + content, demo data in `SentraSim`/`ClinicalTrajectory`/`ClinicalPrognosis`, and + `public/llms.txt` metric changes require Chief (Dr. Ferdi Iskandar) review + (`CONTRIBUTING.md`, `docs/ai-governance.md`, PR template content checklist). +- Quality gate: `lint` with zero ESLint errors and `build` (strict TypeScript) with zero + errors; CI enforces `lint` before `build` on push/PR (`.github/workflows/ci.yml`; + pnpm `11.21.0`, Node `24`, `--frozen-lockfile`). +- Security gate (PR template): no hardcoded secrets; no new `next.config.mjs` + `remotePatterns` domains without justification; no `headers()` changes without review. +- SEO gate (PR template + `README.md` §19): new routes in `app/sitemap.ts` with correct + `changeFrequency`/`priority`, updated meta descriptions and OG images, valid JSON-LD / + sitemap / robots. +- TODO for Gaffer: designate the release approver and environment gates (who authorizes + production push, and what evidence — CI run, dry-run output, visual scroll review — + must be attached). + +## Pre-release checklist (from the repo) + +From `docs/deployment.md` and `README.md` §17–§19, before every production deployment: + +- [ ] `lint` — zero ESLint errors. +- [ ] `build` — zero TypeScript errors, bundle completes. +- [ ] `test` (`node --test app/api/medical-knowledge/route.test.mjs`) and, where + applicable, `test:e2e` Playwright smoke pass. +- [ ] `deploy:dry-run` passes (`.next/BUILD_ID` present; no server-only names in the + client bundle). +- [ ] New clinical claims verified by Chief (see authority above). +- [ ] New articles added to `app/insights/data.ts` and `app/sitemap.ts`; + `public/llms.txt` updated if products/metrics changed; `app/layout.tsx` JSON-LD + `featureList` updated if capabilities changed. +- [ ] Security headers verified (`curl -I https://sentrahai.com`). +- [ ] Scroll-driven sections visually sanity-checked after layout/animation changes. + +## Release record (fill per approved release) + +For each release capture: version/commit, scope, changelog entry, verification evidence +(CI run, `deploy:dry-run` output), known risks, approver, target, and rollback / +monitoring outcome. No release-record entries exist in the repo today. + +## Rollback (as documented — verify target first) + +- Per `docs/deployment.md` (Railway): `railway rollback`, or dashboard → Deployments → + select previous deployment → Redeploy; then re-run the post-deploy `curl` checks. +- TODO for Gaffer: confirm whether Railway rollback still applies or whether the Vercel + target noted in `.agents/HANDOFF.md` has superseded it, and state the authoritative + rollback command for the current host.