release: promote develop to main — Collaboration service, .NET 10, audit hardening & branch-timeline UX

.env.production.example

@@ -36,11 +36,19 @@ JwtSettings__Secret=<same-value-as-JWT_SECRET>
 JwtSettings__Issuer=Planora.Auth
 JwtSettings__Audience=Planora.Clients
 
-# Direct connection strings for non-Compose production deployments
-ConnectionStrings__AuthDatabase=Host=<postgres-host>;Port=5432;Database=planora_auth_db;Username=<user>;Password=<password>;SSL Mode=Require;Trust Server Certificate=false;
-ConnectionStrings__TodoDatabase=Host=<postgres-host>;Port=5432;Database=planora_todo;Username=<user>;Password=<password>;SSL Mode=Require;Trust Server Certificate=false;
-ConnectionStrings__CategoryDatabase=Host=<postgres-host>;Port=5432;Database=planora_category;Username=<user>;Password=<password>;SSL Mode=Require;Trust Server Certificate=false;
-ConnectionStrings__MessagingDatabase=Host=<postgres-host>;Port=5432;Database=planora_messaging;Username=<user>;Password=<password>;SSL Mode=Require;Trust Server Certificate=false;
+# Direct connection strings for non-Compose production deployments.
+#
+# Pool sizing (T4.4):
+#   Maximum Pool Size=10 per service × 6 services × N replicas = total connections
+#   against your managed Postgres. Tune up if you scale replicas, but stay
+#   well below the provider's max_connections (Neon free = 100, Fly Postgres
+#   shared = 64) to leave headroom for the migrator and autovacuum.
+#   Connection Idle Lifetime=60 evicts idle connections after a minute so a
+#   restarted Postgres does not hand back stale sockets on the next request.
+ConnectionStrings__AuthDatabase=Host=<postgres-host>;Port=5432;Database=planora_auth_db;Username=<user>;Password=<password>;SSL Mode=Require;Trust Server Certificate=false;Maximum Pool Size=10;Connection Idle Lifetime=60;
+ConnectionStrings__TodoDatabase=Host=<postgres-host>;Port=5432;Database=planora_todo;Username=<user>;Password=<password>;SSL Mode=Require;Trust Server Certificate=false;Maximum Pool Size=10;Connection Idle Lifetime=60;
+ConnectionStrings__CategoryDatabase=Host=<postgres-host>;Port=5432;Database=planora_category;Username=<user>;Password=<password>;SSL Mode=Require;Trust Server Certificate=false;Maximum Pool Size=10;Connection Idle Lifetime=60;
+ConnectionStrings__MessagingDatabase=Host=<postgres-host>;Port=5432;Database=planora_messaging;Username=<user>;Password=<password>;SSL Mode=Require;Trust Server Certificate=false;Maximum Pool Size=10;Connection Idle Lifetime=60;
 ConnectionStrings__Redis=<redis-host>:6379,password=<password>,ssl=True,abortConnect=false
 
 # RabbitMQ service credentials for non-Compose deployments

.githooks/pre-commit

@@ -0,0 +1,72 @@
+#!/usr/bin/env bash
+# Planora pre-commit hook. Runs only on the files staged for the current commit.
+# Activate per-clone with `scripts/install-hooks.sh` (sets core.hooksPath = .githooks).
+#
+# Two cheap, locally-runnable gates:
+#   1. Frontend: ESLint on staged .ts/.tsx/.js/.jsx (errors only, no auto-fix).
+#   2. Backend:  dotnet format --verify-no-changes on the touched solution.
+#
+# Both gates pass quickly on a no-op commit. Skip the hook for emergency commits
+# with `git commit --no-verify`.
+
+set -euo pipefail
+
+repo_root="$(git rev-parse --show-toplevel)"
+cd "$repo_root"
+
+# Files staged for commit (added, copied, modified, renamed — not deleted).
+mapfile -t staged < <(git diff --cached --name-only --diff-filter=ACMR)
+if [[ ${#staged[@]} -eq 0 ]]; then
+  exit 0
+fi
+
+# --- Frontend ----------------------------------------------------------------
+
+frontend_files=()
+for f in "${staged[@]}"; do
+  case "$f" in
+    frontend/*.ts|frontend/*.tsx|frontend/*.js|frontend/*.jsx|\
+    frontend/**/*.ts|frontend/**/*.tsx|frontend/**/*.js|frontend/**/*.jsx)
+      frontend_files+=("$f")
+      ;;
+  esac
+done
+
+if [[ ${#frontend_files[@]} -gt 0 ]]; then
+  if [[ -x frontend/node_modules/.bin/eslint ]]; then
+    # ESLint accepts paths relative to its CWD; strip the "frontend/" prefix.
+    eslint_targets=()
+    for f in "${frontend_files[@]}"; do
+      eslint_targets+=("${f#frontend/}")
+    done
+    echo "[pre-commit] eslint ${#eslint_targets[@]} staged frontend file(s)…"
+    ( cd frontend && ./node_modules/.bin/eslint --max-warnings=0 "${eslint_targets[@]}" )
+  else
+    echo "[pre-commit] frontend/node_modules/.bin/eslint missing — run 'npm --prefix frontend install' to enable the gate. Skipping for now."
+  fi
+fi
+
+# --- Backend -----------------------------------------------------------------
+
+backend_files=()
+for f in "${staged[@]}"; do
+  case "$f" in
+    *.cs|*.csproj|*.props|*.sln)
+      backend_files+=("$f")
+      ;;
+  esac
+done
+
+if [[ ${#backend_files[@]} -gt 0 ]]; then
+  if command -v dotnet >/dev/null 2>&1; then
+    echo "[pre-commit] dotnet format --verify-no-changes on Planora.sln…"
+    dotnet format Planora.sln --verify-no-changes --severity warn --no-restore || {
+      echo "[pre-commit] dotnet format reported issues. Run 'dotnet format Planora.sln' to apply, then re-stage."
+      exit 1
+    }
+  else
+    echo "[pre-commit] dotnet CLI not on PATH — skipping the backend format check."
+  fi
+fi
+
+exit 0

.github/CODEOWNERS

@@ -0,0 +1,49 @@
+# Code-ownership policy for Planora. Until additional contributors land,
+# the maintainer reviews every PR; the entries below codify which surfaces are
+# *especially* sensitive (security primitives, observability pipeline, schema
+# migrations, deployment manifests) so a future multi-reviewer setup keeps the
+# right eyes on the right diffs.
+
+# Default owner for everything not matched below.
+*                                                       @4Keyy
+
+# Security primitives — auth flows, JWT, CSRF, gRPC interceptors, security stamp.
+BuildingBlocks/Planora.BuildingBlocks.Infrastructure/Security/     @4Keyy
+BuildingBlocks/Planora.BuildingBlocks.Infrastructure/Middleware/   @4Keyy
+BuildingBlocks/Planora.BuildingBlocks.Infrastructure/Grpc/         @4Keyy
+BuildingBlocks/Planora.BuildingBlocks.Infrastructure/Extensions/JwtAuthenticationExtensions.cs @4Keyy
+Services/AuthApi/Planora.Auth.Infrastructure/Services/Security/    @4Keyy
+Services/AuthApi/Planora.Auth.Api/Filters/                         @4Keyy
+SECURITY.md                                                        @4Keyy
+docs/auth-security.md                                              @4Keyy
+docs/secrets-management.md                                         @4Keyy
+
+# Observability pipeline — INV-OBS-* invariants enforced here.
+BuildingBlocks/Planora.BuildingBlocks.Infrastructure/Logging/      @4Keyy
+BuildingBlocks/Planora.BuildingBlocks.Infrastructure/Observability/ @4Keyy
+
+# Outbox / inbox state machines — at-least-once delivery and idempotency.
+BuildingBlocks/Planora.BuildingBlocks.Infrastructure/Outbox/       @4Keyy
+BuildingBlocks/Planora.BuildingBlocks.Infrastructure/Inbox/        @4Keyy
+BuildingBlocks/Planora.BuildingBlocks.Application/Outbox/          @4Keyy
+BuildingBlocks/Planora.BuildingBlocks.Infrastructure/IdempotentConsumer/ @4Keyy
+
+# Migrator + EF schema — wrong move here corrupts production __EFMigrationsHistory.
+tools/Planora.Migrator/                                            @4Keyy
+**/Migrations/                                                     @4Keyy
+
+# CI/CD + deployment manifests + Dockerfiles — supply-chain blast radius.
+.github/workflows/                                                 @4Keyy
+.github/dependabot.yml                                             @4Keyy
+deploy/                                                            @4Keyy
+**/Dockerfile                                                      @4Keyy
+docker-compose.yml                                                 @4Keyy
+
+# Architectural truth.
+docs/INVARIANTS.md                                                 @4Keyy
+docs/DECISIONS/                                                    @4Keyy
+docs/ROADMAP.md                                                    @4Keyy
+ARCHITECTURE.md                                                    @4Keyy
+
+# Gateway — the only public HTTP edge.
+Planora.ApiGateway/                                                @4Keyy

.github/workflows/cd.yml

@@ -70,7 +70,7 @@ jobs:
     runs-on: ubuntu-latest
     timeout-minutes: 5
     steps:
-      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
           ref: ${{ inputs.ref || github.ref }}
 
@@ -83,11 +83,7 @@ jobs:
           fi
 
       - name: Install flyctl
-        # TODO(security): pin this action to a SHA before relying on this
-        # workflow in production. Run:
-        #   gh api /repos/superfly/flyctl-actions/git/refs/heads/master --jq .object.sha
-        # and replace `@master` with `@<sha>  # master at <date>`.
-        uses: superfly/flyctl-actions/setup-flyctl@master
+        uses: superfly/flyctl-actions/setup-flyctl@ed8efb33836e8b2096c7fd3ba1c8afe303ebbff1 # 1.6
 
       - name: Validate every fly.toml parses
         shell: bash
@@ -106,12 +102,12 @@ jobs:
     runs-on: ubuntu-latest
     timeout-minutes: 15
     steps:
-      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
           ref: ${{ inputs.ref || github.ref }}
 
       - name: Install flyctl
-        uses: superfly/flyctl-actions/setup-flyctl@master
+        uses: superfly/flyctl-actions/setup-flyctl@ed8efb33836e8b2096c7fd3ba1c8afe303ebbff1 # 1.6
 
       - name: Run Planora.Migrator one-shot
         shell: bash
@@ -159,12 +155,12 @@ jobs:
             config: deploy/fly/realtime.fly.toml
             dockerfile: Services/RealtimeApi/Planora.Realtime.Api/Dockerfile
     steps:
-      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
           ref: ${{ inputs.ref || github.ref }}
 
       - name: Install flyctl
-        uses: superfly/flyctl-actions/setup-flyctl@master
+        uses: superfly/flyctl-actions/setup-flyctl@ed8efb33836e8b2096c7fd3ba1c8afe303ebbff1 # 1.6
 
       - name: Deploy ${{ matrix.app }}
         shell: bash
@@ -184,12 +180,12 @@ jobs:
     runs-on: ubuntu-latest
     timeout-minutes: 15
     steps:
-      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
           ref: ${{ inputs.ref || github.ref }}
 
       - name: Install flyctl
-        uses: superfly/flyctl-actions/setup-flyctl@master
+        uses: superfly/flyctl-actions/setup-flyctl@ed8efb33836e8b2096c7fd3ba1c8afe303ebbff1 # 1.6
 
       - name: Deploy planora-gateway
         shell: bash
@@ -217,6 +213,27 @@ jobs:
         run: |
           echo "url=https://planora-gateway.fly.dev" >> "$GITHUB_OUTPUT"
 
+      - name: Probe /health/live (liveness)
+        shell: bash
+        # Liveness must succeed within a tight window. If the gateway process is
+        # alive but readiness is delayed (e.g. a slow Postgres warm-up), readiness
+        # polling below handles that — but if /health/live itself does not respond,
+        # the deploy is unhealthy and we surface immediately rather than burning
+        # two minutes on readiness retries.
+        run: |
+          set -e
+          live="${{ steps.gateway.outputs.url }}/health/live"
+          for attempt in {1..15}; do
+            if curl --fail --silent --show-error --max-time 3 "${live}" > /dev/null; then
+              echo "::notice::Gateway /health/live is OK"
+              exit 0
+            fi
+            echo "Liveness attempt ${attempt}/15 — gateway process not responding"
+            sleep 2
+          done
+          echo "::error::Gateway /health/live did not return 200 within 30 s — deploy is broken"
+          exit 1
+
       - name: Wait for /health/ready
         shell: bash
         run: |

.github/workflows/ci.yml

@@ -1,9 +1,9 @@
 name: CI
 on:
   push:
-    branches: [main, 'audit/**', 'fix/**', 'claude/**']
+    branches: [main, develop, 'audit/**', 'fix/**']
   pull_request:
-    branches: [main]
+    branches: [main, develop]
 
 # Minimum permissions. Each job only receives what it needs.
 permissions:
@@ -19,9 +19,9 @@ jobs:
     runs-on: ubuntu-latest
     timeout-minutes: 10
     steps:
-      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
       - name: Lint Markdown
-        uses: DavidAnson/markdownlint-cli2-action@992badcdf24e3b8eb7e87ff9287fe931bcb00c6e # v20
+        uses: DavidAnson/markdownlint-cli2-action@ded1f9488f68a970bc66ea5619e13e9b52e601cd # v23.2.0
       - name: Check Markdown links
         uses: lycheeverse/lychee-action@8646ba30535128ac92d33dfc9133794bfdd9b411 # v2
         with:
@@ -32,14 +32,22 @@ jobs:
     runs-on: ubuntu-latest
     timeout-minutes: 20
     steps:
-      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
       - uses: actions/setup-dotnet@c2fa09f4bde5ebb9d1777cf28262a3eb3db3ced7 # v5
         with:
-          dotnet-version: '9.0.x'
+          dotnet-version: '10.0.x'
+          # CPM: hash every input that can change the restore graph (csproj graph
+          # + central package versions + build props). No packages.lock.json yet,
+          # so the action hashes these files to derive the cache key.
+          cache: true
+          cache-dependency-path: |
+            **/*.csproj
+            Directory.Packages.props
+            Directory.Build.props
       - run: dotnet restore Planora.sln
       - run: dotnet build Planora.sln --no-restore --configuration Release -warnaserror
       - run: dotnet test Planora.sln --no-build --configuration Release --collect:"XPlat Code Coverage" --settings coverage.runsettings --results-directory ./coverage/backend
-      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: backend-coverage-report
           path: ./coverage/backend
@@ -51,7 +59,7 @@ jobs:
       run:
         working-directory: frontend
     steps:
-      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
       - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
         with:
           node-version: '20'
@@ -62,7 +70,7 @@ jobs:
       - run: npm run type-check
       - run: npm run test:coverage
       - run: npm run build
-      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: frontend-coverage-report
           path: frontend/coverage

.github/workflows/e2e.yml

@@ -3,7 +3,7 @@ name: E2E
 on:
   workflow_dispatch:
   pull_request:
-    branches: [main]
+    branches: [main, develop]
     paths:
       - '.github/workflows/e2e.yml'
       - 'BuildingBlocks/**'
@@ -26,7 +26,7 @@ jobs:
     runs-on: ubuntu-latest
     timeout-minutes: 30
     steps:
-      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
 
       - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
         with:
@@ -83,16 +83,61 @@ jobs:
         run: npm ci
         working-directory: frontend
 
-      - name: Run Playwright e2e
+      # T2.6 — install Chromium for browser-rendered UI specs. The chromium
+      # binary is cached by setup-node along with the npm cache; first run
+      # downloads it (~150 MB), subsequent runs hit the cache.
+      - name: Install Playwright browsers (chromium)
+        run: npx playwright install --with-deps chromium
+        working-directory: frontend
+
+      # T2.6 — build + start the Next.js frontend so the `ui` project can
+      # drive a real browser against it. The dev server is intentionally not
+      # used: dev mode has different hydration timing and Webpack overlays
+      # that interfere with Playwright.
+      - name: Build frontend
+        run: npm run build
+        working-directory: frontend
+        env:
+          NEXT_PUBLIC_API_URL: http://127.0.0.1:5132
+
+      - name: Start frontend (background) and wait for readiness
+        shell: bash
+        working-directory: frontend
+        run: |
+          NEXT_PUBLIC_API_URL=http://127.0.0.1:5132 \
+            nohup npm run start -- -p 3000 > ../frontend-server.log 2>&1 &
+          echo $! > ../frontend.pid
+          for attempt in {1..60}; do
+            if curl --fail --silent --show-error "http://127.0.0.1:3000" > /dev/null; then
+              echo "Frontend ready after ${attempt} attempts"
+              exit 0
+            fi
+            sleep 2
+          done
+          echo "Frontend failed to start; tailing log:"
+          tail -200 ../frontend-server.log
+          exit 1
+
+      - name: Run Playwright e2e (api + ui projects)
         run: npm run e2e
         working-directory: frontend
         env:
           E2E_API_URL: http://127.0.0.1:5132
+          E2E_FRONTEND_URL: http://127.0.0.1:3000
           E2E_AUTH_LOG_CONTAINER: planora-auth-api
 
+      - name: Stop frontend
+        if: always()
+        shell: bash
+        run: |
+          if [ -f frontend.pid ]; then
+            pid=$(cat frontend.pid)
+            kill "$pid" 2>/dev/null || true
+          fi
+
       - name: Upload Playwright report
         if: always()
-        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: playwright-report
           path: |