qa iteration 2

AGENTS.md

@@ -107,7 +107,19 @@ Whenever a new dependency, container image, tool, or vendored asset is added:
 - If compatibility is unclear, mark the sprint task `BLOCKED` and record the
   risk in `Decisions & Risks`.
 
-### 2.7 Web tool policy (security constraint)
+### 2.7 Database auto-migration requirement (non-negotiable)
+Every service that owns a PostgreSQL schema MUST auto-migrate on startup. Manual init scripts (`postgres-init/`) are only bootstrap fallbacks for first-run, NOT the migration authority.
+
+Rules:
+- Wire `AddStartupMigrations(schemaName, moduleName, migrationsAssembly)` from `StellaOps.Infrastructure.Postgres.Migrations` in the service's persistence registration or `Program.cs`.
+- SQL migration files MUST be embedded resources in the persistence library (`.csproj`: `<EmbeddedResource Include="Migrations\**\*.sql" />`).
+- For EF Core services without the Infrastructure.Postgres dependency, use `EnsureCreatedAsync()` or a custom `IHostedService` that applies schema on startup.
+- The service MUST converge to the correct schema on any fresh database — volume resets, CI environments, and new installs must work without manual `psql` or external scripts.
+- Pattern references: `src/Signals/__Libraries/StellaOps.Signals.Persistence/Extensions/`, `src/Scanner/__Libraries/StellaOps.Scanner.Storage/Extensions/`.
+
+Rationale: Missing database tables are the #1 cause of 500 errors in QA. Relying on external init scripts creates a fragile dependency chain that breaks on volume resets and CI.
+
+### 2.8 Web tool policy (security constraint)
 AI agents with web access (WebFetch, WebSearch, or similar) must follow these rules:
 
 1. **Default: no external web fetching** – Prefer local docs (`docs/**`), codebase search, and existing fixtures. External fetches introduce prompt-injection risk, non-determinism, and violate the offline-first posture.