slp-modular-cms/aidlc-docs/features/gitea-deployment-workflow/aidlc-state.md

# AI-DLC State Tracking

## Project Information
- **Feature Name**: Gitea Deployment Workflow
- **Feature Slug**: gitea-deployment-workflow
- **Project Type**: Brownfield
- **Start Date**: 2026-07-27T00:00:00Z
- **Current Stage**: CONSTRUCTION - Code Generation complete for Round 2 (U3 + U4)
- **Branch**: feature/gitea-deployment-workflow

## Workspace State
- **Existing Code**: Yes
- **Reverse Engineering Needed**: Completed — full rerun on 2026-07-27 (user chose Q3 = B)
- **Workspace Root**: K:\Development\Projects\SlpModularCms

## Reverse Engineering Status
- [x] Reverse Engineering — Completed on 2026-07-27
- **Artifacts Location**: aidlc-docs/_shared/reverse-engineering/ (all 8 artifacts regenerated + timestamp)
- **Verified by execution**: Release build 0 errors / 50 warnings; 219 backend tests pass; 213 frontend tests pass; `pnpm run lint` **fails** (5 errors, 1 warning); 2 high-severity transitive package advisories

## Code Location Rules
- **Application Code**: Workspace root (NEVER in aidlc-docs/)
- **Feature Documentation**: aidlc-docs/features/gitea-deployment-workflow/ only
- **Shared Artifacts**: aidlc-docs/_shared/
- **Structure patterns**: See code-generation.md Critical Rules

## Language Configuration
- **Documentation Language**: English
- **Conversation Language**: User Language (Dutch)

## Extension Configuration
| Extension | Enabled | Decided At |
|---|---|---|
| Security Baseline | Yes (blocking) | Requirements Analysis |
| Property-Based Testing | No | Requirements Analysis |

## Operations Configuration
- **Include Operations Phase**: Yes
- **Decided At**: Requirements Analysis

### Deployment Setup
- **Included**: Yes
- **Method**: CI/CD (Gitea Actions — confirms what U5/U6 already built)
- **Completed**: 2026-07-28. Real domains: `test.slpsoftware.nl` / `slpsoftware.nl`. Ports 5100/5101
  chosen for the Pi's local Kestrel bindings. Database backup script drafted. Full FTPS future-switch
  procedure drafted (Q5 = B), with an explicit caveat that shared hosting is very likely IIS-based,
  so systemd-restart and atomic-symlink-switch do not carry over unchanged — treated as a starting
  brief for a future Infrastructure Design pass, not a ready-to-execute procedure
- **Revised after user feedback (real host facts)**: `webadmin` (the Pi's FileZilla/SFTP account,
  root `/mnt/storage1/www/`) cannot SSH in and is not the deploy account — it's the
  `WEBSITE_WORKSPACE.md` website-author role. A **separate, dedicated** SSH-capable account now runs
  the deploy pipeline (`PI_MAIN_USERNAME`), with deploy paths under that account's own home
  directory rather than under `/mnt/storage1/www/html/`, so the CMS's release structure never
  interferes with the other hosted websites. `shared/wwwroot-web` is now a cross-account symlink to
  wherever `webadmin` uploads this customer's site, requiring a one-time shared-group permission
  setup — documented, not automated
- **Artifacts**: `operations/deployment/deployment-plan.md`, `deployment-instructions.md`,
  `rollback-plan.md`

### Database Provider Migration — SQL Server → MariaDB (2026-07-29)

Discovered while finalizing Deployment Setup: the target Pi only runs MariaDB, and Microsoft SQL
Server has **no ARM64 build at all** (the `mcr.microsoft.com/mssql/server` image is `linux/amd64`
only; Azure SQL Edge, the former ARM answer, is retired). This invalidates ASM-04. Confirmed no
other machine is available, and the eventual production host (`mijnhostingpartner.nl`) will also
run MariaDB, plus the workload is small enough that MariaDB's performance is not a concern — user
decided: switch the database provider, not the deployment target.

**What changed** (application code, not just Operations docs):
- `SlpModularCms.Core.csproj`: `Microsoft.EntityFrameworkCore.SqlServer` → `MySql.EntityFrameworkCore`
  10.0.7 (Oracle's official provider)
- `UseSqlServer(...)` → `UseMySQL(...)` in `ServiceCollectionExtensions.cs`, `AvailabilityModule.cs`,
  `MasterModule.cs`
- `DatabaseMigrationExtensions.cs` + its test: `Microsoft.Data.SqlClient.SqlException` →
  `MySql.Data.MySqlClient.MySqlException` for the transient-failure classifier
- All three DbContexts' migrations deleted and regenerated (`ApplicationDbContext`,
  `AvailabilityDbContext`, `MasterDbContext`) — no MySQL/MariaDB model-compatibility issues surfaced
  (no index-length problems, no raw SQL anywhere in the codebase to translate)
- Connection strings updated across `appsettings.json` (Api + Api.Slave, all three tiers) from
  SQL Server format to MySQL format
- `README.md` dev setup: MariaDB container command replacing the SQL Server one, with a migration
  note for anyone returning to old instructions
- `deployment-instructions.md` / `rollback-plan.md`: connection string format, backup script
  rewritten around `mariadb-dump` (was `sqlcmd`/`BACKUP DATABASE`), restore procedure rewritten

**Provider selection — two failed attempts before the working one, both reproduced against a real
MariaDB instance, not just reasoned about:**
1. **Pomelo.EntityFrameworkCore.MySql** (the usual first choice, explicit first-class MariaDB
   support) — caps at EF Core 9.x, no EF Core 10 release exists. A Pomelo maintainer states
   ([PR #2017](https://github.com/PomeloFoundation/Pomelo.EntityFrameworkCore.MySql/pull/2017))
   that Pomelo 9 / EF Core 9 packages work fine on a net10.0 TFM — confirmed true only when nothing
   else forces EF Core 10 packages. This project's `Microsoft.AspNetCore.Identity.EntityFrameworkCore`
   and `Microsoft.AspNetCore.DataProtection.EntityFrameworkCore` are versioned in lockstep with the
   .NET 10 runtime and hard-require EF Core >= 10.0.9, so the resolved `Microsoft.EntityFrameworkCore.Abstractions`
   ends up at 10.0.9 regardless. Restore only warns (NU1608), and it builds — but fails at runtime
   with `MissingMethodException: AbstractionsStrings.ArgumentIsEmpty` the moment EF tooling touches
   a DbContext: Pomelo's compiled assembly calls an internal EF Core 9 helper that no longer exists
   in the 10.0.9 assembly actually loaded.
2. **MySql.EntityFrameworkCore 10.0.7** (Oracle's official provider) — its net10.0 dependency group
   targets EF Core 10.0.7, compatible with 10.0.9. Builds and migrates cleanly, but
   `dotnet ef database update` against the real MariaDB throws
   `InvalidCastException: Unable to cast object of type 'System.DBNull' to type 'System.Int64'` in
   `MySQLHistoryRepository.AcquireDatabaseLock()` — a confirmed MariaDB-incompatibility bug (MariaDB's
   `GET_LOCK()` apparently returns `NULL` in a case Oracle's code doesn't handle, and Oracle's
   provider is tested against real MySQL Server, not MariaDB). This isn't limited to CLI tooling —
   the same code path runs on every application startup via `MigrateCoreDatabase()`.

**Working solution**: kept Oracle's `MySql.EntityFrameworkCore` 10.0.7 (otherwise fully compatible)
and added `NonLockingMySQLHistoryRepository` (`SlpModularCms.Core/Hosting/`), wired in via
`options.ReplaceService<IHistoryRepository, NonLockingMySQLHistoryRepository>()` on all three
`AddDbContext` registrations. Oracle's internal `MySQLHistoryRepository` class can't be subclassed
(it's `internal`, only its constructor is public), so the workaround constructs a real instance of
it via reflection and forwards every `IHistoryRepository` member to it **except**
`AcquireDatabaseLock`/`AcquireDatabaseLockAsync`, which return a no-op lock instead of ever reaching
the broken `GET_LOCK` call. Accepted as safe because this deployment model never runs migrations
from more than one place at a time (`MigrateCoreDatabase()` at startup, one deploy at a time via the
atomic-release sequence) — a genuinely concurrent multi-instance migration race is not a scenario
this architecture produces.

**Verified end to end**: all three migrations applied successfully to the user's real local
MariaDB (`dotnet ef database update`, all expected tables present including `DataProtectionKeys`
and the renamed Identity tables); both `SlpModularCms.Api` and `SlpModularCms.Api.Slave` start
cleanly against it (`/health` → 200, `MigrateCoreDatabase()` logs "already up to date" on the
second run); full backend suite re-confirmed at 372/372 passed, 0 build errors.

### Reverse Proxy Topology Correction (2026-07-29)

Infrastructure Design's Q10 (`infrastructure-design.md` § 1) established that an nginx reverse
proxy exists — right about *that*, wrong about *where*: it runs on a **separate, dedicated Pi**
("the proxy Pi"), not on pi-main (where this deployment's release directories and systemd units
live). The proxy Pi terminates TLS and forwards plain HTTP to pi-main over the LAN.

**Corrected**:
- `ASPNETCORE_URLS` binds `0.0.0.0`, not `localhost` (`deployment-instructions.md` § 1.5) — the
  proxy Pi must reach Kestrel over the network, not loopback
- pi-main runs **no nginx and holds no certificates** for these domains at all — the entire
  nginx/certbot procedure in `deployment-instructions.md` § 1.7 happens on the proxy Pi instead
- Added a **firewall requirement on pi-main** (§ 1.7.1 step 4): since Kestrel now listens on all
  interfaces, the backend ports must be restricted to just the proxy Pi's address, or the TLS
  termination the whole design depends on is trivially bypassable by anything else on the LAN
  hitting pi-main directly

Also corrected in `infrastructure-design.md` § 1 (erratum note, history preserved rather than
rewritten). No code changes — this is host topology and Operations documentation only, the
application itself has no opinion on where TLS terminates.

## Scope Decisions (from feature-selection.md)
- **Public website**: documentation/instructions only — where the website build lands in `wwwroot/`, how it coexists with `wwwroot/admin/`, and what a per-website workspace must deliver. The website's own build/deploy workflow stays out of scope (Q4 = A).
- **Environments**: local, test, production only.
- **Observability stack**: UptimeRobot (uptime), Umami (analytics), console logging + Sentry (logging/errors).
- **Deployment constraint**: upload as a published .NET application; no server configuration may be required.
- **Reference**: existing working Gitea Actions setup at `K:\Development\SlpSoftware\Projects\SlpSoftware` (React/Vite) is the starting point.
- **Health check endpoint**: IN SCOPE (decided 2026-07-27). **Liveness only** — `AddHealthChecks()` + `MapHealthChecks("/health")`, no package needed and **no database check** (Q17 = A / D-21, superseding the earlier note that `AddDbContextCheck` might be included). `/health` must be added to `AvailabilityMiddleware._bypassPrefixes` so the availability gate cannot return 503 for it. Health = infrastructure liveness; Availability/capabilities = CMS domain state — these stay strictly separate.

> **Note**: this section records the earliest scope decisions. The authoritative and complete decision set is `inception/requirements/requirements.md` § 3 (D-01…D-32) — in particular, Q4 = C changed the public website from living directly in `wwwroot/` to `wwwroot/web/`.

## Stage Progress

### INCEPTION
- [x] Workspace Detection — Complete
- [x] Reverse Engineering — Complete, approved 2026-07-27 (full rerun of all 8 `_shared/` artifacts)
- [x] Requirements Analysis — Complete, approved 2026-07-27. 24 FRs (FR-24 added at Application Design), 10 NFRs, 32 decisions, 7 assumptions, 4 open items, 4 documented security deviations. Two question rounds: `requirement-verification-questions.md` (25 Q) and `requirement-clarification-questions.md` (5 Q).
- [x] User Stories — **SKIP** (infrastructure/operations work; no new end-user functionality or persona. Offered at Requirements Analysis approval, not requested.)
- [x] Workflow Planning — Complete, approved 2026-07-27. Artifact: `inception/plans/execution-plan.md`
- [x] Application Design — Complete, approved 2026-07-27. 14 code components (9 new, 5 modified) + 2 workflow components. Artifacts in `inception/application-design/`. Two composition conflicts found and carried to Unit 2. Added FR-24, closed OPEN-02.
- [x] Units Generation — Complete (awaiting approval). 7 units in 4 execution rounds. Artifacts: `unit-of-work.md`, `unit-of-work-dependency.md`, `unit-of-work-story-map.md`

### CONSTRUCTION
Units finalised at Units Generation (see `inception/application-design/unit-of-work.md`):
U1 Hosting & Serving · U2 Data Durability · U3 Security Headers & CSP · U4 Observability · U5 CI Workflow & Gates · U6 Deploy Workflow · U7 Documentation

Execution rounds (Q4 = B): **R1** = U1 + U2 · **R2** = U3 + U4 · **R3** = U5 + U6 · **R4** = U7. One commit per unit; single PR at the end (Q6 = A).

- [x] Functional Design — **EXECUTE for U1, U2, U3, U4**; SKIP for U5, U6, U7. **U1 ✅ U2 ✅** approved 2026-07-27 · **U3 ✅ U4 ✅** 2026-07-28
- [ ] NFR Requirements — **SKIP (all units)** — already comprehensively captured in `requirements.md` § 5 and § 6
- [x] NFR Design — **EXECUTE for U3, U4**; SKIP for the rest. *Deliberate deviation from the default NFR-Requirements/NFR-Design coupling — rationale in the execution plan.* **U3 ✅ U4 ✅** 2026-07-28 — 11 patterns for U3, 10 for U4. Closed OPEN-01; raised REF-U3-01
- [x] Infrastructure Design — **EXECUTE for U6, U7 per the original plan; SKIP for the rest**. **U6 ✅** 2026-07-28 — single Pi, directory-only environment split, `systemd --user` (no sudo), releases/current/shared layout, 2-release retention, health check via public URL. Raised INFRA-U6-01 (linger requirement, carried to Operations). **U7 did not need it in practice**: by Units Generation, U7's scope had narrowed to documentation-only (Q8 = A — operational/infrastructure decisions moved to Operations), so it went straight to Code Generation with no infrastructure to design
- [x] Code Generation — **EXECUTE** (all 7 units, each built and tested before its completion message). **U1 ✅ U2 ✅** 2026-07-27 (253 backend tests). **U3 ✅** 2026-07-28 (315). **U4 ✅** 2026-07-28 (366 backend + 237 frontend). **U6 ✅ U5 ✅** 2026-07-28 — Round 3: `deploy-scp.yaml` + `continuous_integration.yaml`, 372 backend + 237 frontend tests (unchanged from Round 2, confirming no regressions from FR-21/FR-22 fixes), 0 vulnerable packages, lint clean. Raised REF-U5-01 (Umami-origin gate needs a parallel Gitea variable, since the backend side is a host env var per D-16). **U7 ✅** 2026-07-28 — Round 4: `WEBSITE_WORKSPACE.md`, README.md and `.env.example` updated, all claims re-verified against actual U1–U6 source. **All 7 units complete.**
- [x] Build and Test — **EXECUTE** — Complete 2026-07-28. 609 unit tests (372 backend + 237 frontend), 0 vulnerable packages, 0 build errors. Plus live-host integration verification: static content/SPA-fallback/header-scoping, real master↔slave communication proving the persistent key ring survives a process restart, and W3C trace-id correlation in real log output. Artifacts in `construction/build-and-test/`

### OPERATIONS
- [ ] Deployment Setup — **EXECUTE**
- [ ] Monitoring Setup — **EXECUTE**
- [ ] Production Readiness Validation — **EXECUTE** (includes the `dotnet-appsettings` compliance gate)

## Execution Plan Summary
- **Risk Level**: High — three destructive-and-silent failure modes (customer website loss, Data Protection key-ring loss, automatic migration against production)
- **Stages to Execute**: Functional Design (×4: U1–U4), NFR Design (×2: U3, U4), Infrastructure Design (×2: U6, U7), Code Generation (×7), Build and Test, Deployment Setup, Monitoring Setup, Production Readiness Validation
- **Stages to Skip**: User Stories (no end-user functionality), NFR Requirements (already captured), plus per-unit skips as listed above

## Current Status
- **Lifecycle Phase**: OPERATIONS
- **Current Stage**: Build and Test **complete** 2026-07-28 (all 7 units, full-suite + live-host integration verification). CONSTRUCTION phase is now closed
- **Next Stage**: Deployment Setup (Operations Configuration = Yes, decided at Requirements Analysis)
- **Status**: Rounds 1–4 all done, nothing pushed. Entering Operations phase

## Round 2 Design Record (2026-07-28)
- Functional Design U3 + U4 complete and committed (`357d395`)
- NFR Design U3 — `construction/u3-security-headers/nfr-design/` — 11 patterns. All new types in `Core/Hosting/Security/`, so `Core.Tests` can reach them (avoids repeating U1's Step 11 deviation)
- NFR Design U4 — `construction/u4-observability/nfr-design/` — 10 patterns. `Sentry.AspNetCore` 6.8.0 into `Core`; `@sentry/react` ^10.68.0 into `frontend`
- **OPEN-01 CLOSED**: correlation ID = W3C trace ID from the ambient `Activity`, `TraceIdentifier` as fallback. Rationale: propagates master→slave via `traceparent`, and equals the `traceId` ASP.NET Core's `ProblemDetails` already returns
- **REF-U3-01 raised**: BR-U3-22's Umami-origin startup warning is **not implementable** — the backend cannot read `VITE_UMAMI_WEBSITE_ID`. Withdrawn from U3 and replaced by a **blocking U5 CI gate** comparing the frontend build variable against that environment's `SecurityHeaders:AllowedScriptOrigins`
- **Additions beyond the functional design**, each with rationale in the pattern docs: `Set-Cookie` added to the scrub list; a `sentry-tunnel` rate limiter; `OnRejected` on the existing rate limiter (today a `429` leaves no trace anywhere); `SentrySdk.FlushAsync` before the migration-failure rethrow (otherwise the one `Critical` event dies with the process)
- **Three defaults chosen rather than escalated** (each one line to change, listed at the end of U4's pattern doc): JSON console outside Development, `TracesSampleRate` 0.1, tunnel cap 200 KB
- U4 modifies two files from already-committed units — `DatabaseMigrationExtensions` (U2) and `AdminTokenValidator` (U1). Both additive; to be named in the U4 commit message

## Round 1 Verification Record (2026-07-27)
- `dotnet build SlpModularCms.sln -c Release` — 0 errors
- Backend tests — **253 passed, 0 failed** (Core 83, Availability 82, Identity 37, Master 51); baseline was 219
- New EF migration `20260727203036_AddDataProtectionKeys` — verified purely additive
- Embedded placeholder resource name verified against the compiled assembly manifest
- **Carried to phase-level Build and Test**: composed-startup behaviour that needs a running host and a real database — `/admin` trailing-slash redirect, 404-vs-HTML for missing assets, SPA fallback and placeholder resolution, `/health` while availability-disabled, `MigrateCoreDatabase` against SQL Server, and both hosts starting
- **Deviation**: U1 plan Step 11 (`StaticContentTests`) not implemented — the code lives in `SlpModularCms.Api`, which has no test project by convention; behaviour carried to Build and Test instead. Recorded in the unit's `generation-summary.md`

## Round 2 Verification Record (2026-07-28)
- `dotnet build SlpModularCms.sln -c Release` — 0 errors (70 warnings, all pre-existing package advisories)
- Backend tests — **372 passed, 0 failed** at stage close (Core 196, Availability 82, Master 57, Identity 37); was 253 after Round 1, 366 after U4, +6 from the integrity-check fix
- Frontend tests — **237 passed, 0 failed**; baseline 213
- `npx tsc -b` clean; eslint on every changed frontend file reports 0 problems; full `pnpm run lint` unchanged at the pre-existing 5 errors / 1 warning (FR-21, U5)
- `Sentry.AspNetCore` 6.8.0 ships a native **`net10.0`** asset — the carried-forward compatibility question is closed
- `@sentry/react` 10.68.0; `pnpm-lock.yaml` diff is additions only
- **Two findings**: `z.string().url()` accepts `htp://` in Zod 4 (URL constructor accepts any scheme), so the pre-existing frontend validation never caught the typo BR-U4-24 names — now `z.url({ protocol: /^https?$/ })`. And `appsettings.json` comments are verified by `DeployedConfigurationTests` against the real provider rather than assumed, because the failure mode is both hosts refusing to start
- **One deviation**: `IAdminTokenValidator` collapsed to a single `Validate` → `AdminTokenResult` instead of adding an overload. Two methods with an invisible difference at the call site let a substitute silently invert the access decision while both compiled — see U4's `generation-summary.md`
- **Two defects found in local testing after Round 2, both fixed in this branch** rather than filed, per the standing rule that tech debt is for large or high-impact changes only:
  1. Ciphertext written before U2 cannot be decrypted by the database key ring (`980dc80`). Recorded as ASM-08; local rows cleared and re-registered
  2. `VerifyIntegrityAsync` could not tell an unreachable slave from one that does not recognise the master, so the only recoverable state was never repaired (`6957ec7`). Now four distinct outcomes; automatic registration on a rejected key is safe because the slave refuses any key that does not match an existing registration
- **Note**: fix 2 is master/slave **domain** behaviour, not deployment work. It sits in this branch by explicit decision, not because it belongs to the feature
- **Carried to phase-level Build and Test**: trace-ID propagation master → slave, `TraceId` present in rendered console output, tunnel status codes, the `security_event` tag on a real Sentry event, threshold behaviour end to end, and CSP/HSTS header presence on real static assets and error responses