ScadaBridge/docs/plans/2026-06-19-sms-notifications.md

SMS Notifications (T9 pivot + T10) Implementation Plan

For Claude: REQUIRED SUB-SKILL: Use superpowers-extended-cc:subagent-driven-development to implement this plan task-by-task.

Goal: Add NotificationType.Sms + a Twilio-REST SmsNotificationDeliveryAdapter behind the existing INotificationDeliveryAdapter seam, plus the T10 enum/UI/CLI Type-selector plumbing, so notification lists can deliver to ZB team members by SMS. Email is unchanged.

Architecture: Mirror the Email/SMTP stack. A list's existing NotificationList.Type decides the channel; Notify.To stays type-agnostic; central stamps the Notification's Type from the list at ingest; the outbox actor already routes Dictionary<NotificationType, adapter> and parks on a missing adapter. Twilio called directly over REST (no SDK). Secrets encrypted via the existing Data-Protection EncryptedStringConverter.

Tech Stack: C#/.NET 10, Akka.NET, EF Core (MS SQL), Blazor Server, System.CommandLine, IHttpClientFactory, ASP.NET Data Protection. No new NuGet packages (Microsoft.Extensions.Http is already centrally managed).

Design doc: docs/plans/2026-06-19-sms-notifications-design.md (committed 28cab6e8).

Execution rules: dedicated worktree feat/sms-notifications off main c72d7b79. Implementers do NOT create worktrees. Pathspec commits only (git commit -m "msg" -- <paths>, -m before --, never git add -A; git add <explicit path> for new files; retry on index.lock). ≤2-3 concurrent committers per wave + post-wave HEAD-presence check (git merge-base --is-ancestor <sha> HEAD). Targeted builds/tests per task; full-solution build + docker rebuild + Playwright + live smoke only at INT (S11). TreatWarningsAsErrors=true.

---

Wave / dependency map

• Wave 1: S1 (Commons foundation) — blocks all.
• Wave 2: S2 (Config-DB migration) ∥ S5 (Management commands+handlers). Both ⟵ S1.
• Wave 3: S3 (adapter) ⟵ S1,S2 ∥ S4 (ingest stamping) ⟵ S1 ∥ S6 (CLI) ⟵ S5.
• Wave 4: S7 (list form) ∥ S8 (list page Type column) ∥ S9 (SMS config page) ∥ S10 (Transport). All ⟵ S1/S5 (S9,S10 also ⟵ S2). Cap at 3 concurrent; queue the 4th.
• Wave 5: S11 (INT) ⟵ all.

---

Task S1: Commons foundation — NotificationType.Sms, recipient phone, SmsConfiguration entity, repo interface

Classification: standard Estimated implement time: ~5 min Parallelizable with: none (foundational)

Files:

• Modify: src/ZB.MOM.WW.ScadaBridge.Commons/Types/Enums/NotificationType.cs
• Modify: src/ZB.MOM.WW.ScadaBridge.Commons/Entities/Notifications/NotificationRecipient.cs
• Create: src/ZB.MOM.WW.ScadaBridge.Commons/Entities/Notifications/SmsConfiguration.cs
• Modify: src/ZB.MOM.WW.ScadaBridge.Commons/Interfaces/Repositories/INotificationRepository.cs
• Test: tests/ZB.MOM.WW.ScadaBridge.Commons.Tests/ (add a recipient-factory + SmsConfiguration shape test if a suitable test class exists; else a small new test file)

Steps:

1. Add Sms to NotificationType (after Email). Update the enum's XML doc to "Email and SMS supported." NOTE: Commons.Tests may have an enum-count assertion — if so, update it (this is the known enum-count-drift pattern).
2. NotificationRecipient: add public string? PhoneNumber { get; set; }; relax EmailAddress to string?. Keep the existing NotificationRecipient(string name, string emailAddress) ctor (email path). Add static factories ForEmail(string name, string email) and ForSms(string name, string phoneNumber) (set the appropriate field, leave the other null; validate name non-empty). Keep a parameterless-friendly path for EF.
3. Create SmsConfiguration POCO (persistence-ignorant): int Id, string AccountSid, string? AuthToken, string FromNumber, string? MessagingServiceSid, string? ApiBaseUrl, int ConnectionTimeoutSeconds, int MaxRetries, TimeSpan RetryDelay. Mirror SmtpConfiguration constructor/validation style.
4. INotificationRepository: add Task<SmsConfiguration?> GetSmsConfigurationAsync(CancellationToken=default), Task<IReadOnlyList<SmsConfiguration>> GetAllSmsConfigurationsAsync(CancellationToken=default), Task AddSmsConfigurationAsync(SmsConfiguration, CancellationToken=default), Task UpdateSmsConfigurationAsync(SmsConfiguration, CancellationToken=default) (match the SMTP method shapes already present).
5. Build dotnet build src/ZB.MOM.WW.ScadaBridge.Commons/...; run any touched Commons tests.
6. Commit (pathspec; git add the new SmsConfiguration.cs).

Acceptance: Commons builds 0/0; NotificationType.Sms exists; recipient carries nullable phone + factories; SmsConfiguration + repo methods defined.

---

Task S2: Configuration Database — EF mappings, encryption, idempotent migration

Classification: high-risk Estimated implement time: ~5 min Parallelizable with: S5

Files:

• Modify: src/ZB.MOM.WW.ScadaBridge.ConfigurationDatabase/Configurations/NotificationConfiguration.cs
• Modify: src/ZB.MOM.WW.ScadaBridge.ConfigurationDatabase/ScadaBridgeDbContext.cs
• Modify: src/ZB.MOM.WW.ScadaBridge.ConfigurationDatabase/NotificationRepository.cs (or wherever INotificationRepository is implemented — locate it)
• Create: new EF migration under src/ZB.MOM.WW.ScadaBridge.ConfigurationDatabase/Migrations/
• Test: tests/ZB.MOM.WW.ScadaBridge.ConfigurationDatabase.Tests/ (mapping/round-trip + encryption test)

Steps:

1. NotificationRecipientConfiguration: EmailAddress → .IsRequired(false); add PhoneNumber .HasMaxLength(32) (nullable).
2. Add SmsConfigurationConfiguration : IEntityTypeConfiguration<SmsConfiguration> (key, AccountSid required maxlen, FromNumber required, AuthToken/MessagingServiceSid/ApiBaseUrl nullable, sensible maxlens). Add DbSet<SmsConfiguration> + apply config.
3. ScadaBridgeDbContext.ApplySecretColumnEncryption: add modelBuilder.Entity<SmsConfiguration>().Property(s => s.AuthToken).HasConversion(converter);.
4. Implement the four INotificationRepository SMS-config methods (mirror SMTP impls exactly).
5. Generate the migration (dotnet ef migrations add AddSmsNotifications ...). Then make it idempotent per repo convention (guard column add / table create / column-alter the way prior migrations in this repo do — match an existing idempotent migration as reference). Migration must: add NotificationRecipients.PhoneNumber (nullable), alter NotificationRecipients.EmailAddress to nullable, create SmsConfigurations table.
6. Verify NO PendingModelChangesWarning: dotnet build + a model-drift check (the repo has a pattern/test for this — run it).
7. Build Config-DB + run touched Config-DB tests. Commit (pathspec).

Acceptance: Config-DB builds; migration idempotent + no model drift; encryption applied to AuthToken; recipient phone + nullable email mapped; round-trip test green.

---

Task S3: SmsNotificationDeliveryAdapter (Twilio REST) + classifier + options + DI + adapter tests

Classification: high-risk Estimated implement time: ~5 min Parallelizable with: S4, S6

Files:

• Create: src/ZB.MOM.WW.ScadaBridge.NotificationOutbox/Delivery/SmsNotificationDeliveryAdapter.cs
• Create: src/ZB.MOM.WW.ScadaBridge.NotificationOutbox/Delivery/SmsErrorClassifier.cs
• Create: src/ZB.MOM.WW.ScadaBridge.NotificationOutbox/SmsOptions.cs
• Modify: src/ZB.MOM.WW.ScadaBridge.NotificationOutbox/ServiceCollectionExtensions.cs
• Modify: src/ZB.MOM.WW.ScadaBridge.NotificationOutbox/ZB.MOM.WW.ScadaBridge.NotificationOutbox.csproj
• Modify (test): tests/ZB.MOM.WW.ScadaBridge.NotificationOutbox.Tests/ServiceRegistrationTests.cs
• Create (test): tests/ZB.MOM.WW.ScadaBridge.NotificationOutbox.Tests/Delivery/SmsNotificationDeliveryAdapterTests.cs

Steps:

1. SmsErrorClassifier: static IsTransient(HttpStatusCode) (5xx/408/429) + IsTransient(Exception, CancellationToken) (HttpRequestException/Timeout/TaskCanceled when not caller-cancelled). Mirror SmtpErrorClassifier's enum+static-method shape.
2. SmsOptions (bind ScadaBridge:Sms): int MaxMessageLength = 1600, int ConnectionTimeoutSeconds = 30 (config-row value overrides). Validate.
3. SmsNotificationDeliveryAdapter : INotificationDeliveryAdapter, Type => NotificationType.Sms. Ctor: INotificationRepository, IHttpClientFactory, ILogger, IOptions<SmsOptions>. DeliverAsync:
   • Load list by notification.ListName → Permanent if missing.
   • Load recipients; filter to non-empty PhoneNumber → Permanent if none.
   • Load GetSmsConfigurationAsync() → Permanent if null/incomplete.
   • Compose body = Subject + "\n" + Body, truncate to MaxMessageLength.
   • For each phone: POST {ApiBaseUrl}/2010-04-01/Accounts/{AccountSid}/Messages.json, Basic auth header AccountSid:AuthToken, form To/From(or MessagingServiceSid)/Body. Classify per response.
   • Roll up per D6 (all-accepted→Success; any-transient→Transient; mix accepted+permanent→Success + LastError note; all-permanent→Permanent). ResolvedTargets = accepted numbers.
   • Scrub AuthToken from any logged error via CredentialRedactor.Scrub.
4. ServiceCollectionExtensions.AddNotificationOutbox: register SmsNotificationDeliveryAdapter as scoped INotificationDeliveryAdapter (alongside Email); services.AddHttpClient("Twilio"); bind SmsOptions.
5. .csproj: add <PackageReference Include="Microsoft.Extensions.Http" /> (version comes from Directory.Packages.props — do NOT add a version attribute).
6. Update ServiceRegistrationTests: the Assert.Single(adapters) test must now assert both Email and SMS adapters are registered (e.g. Assert.Equal(2, adapters.Count) + both types present); keep/add a SmsNotificationDeliveryAdapter.Type == Sms assertion.
7. Adapter unit tests with a fake HttpMessageHandler: 201 success (single + multi recipient), 500/429/timeout → Transient, 400/401 → Permanent, mix accepted+400 → Success with LastError note, no-config/no-recipients/list-missing → Permanent, AuthToken never appears in returned error string.
8. Build NotificationOutbox + run NotificationOutbox.Tests. Commit (pathspec; git add new files).

Acceptance: adapter builds; both adapters registered; all adapter unit tests + the updated ServiceRegistration test green; no AuthToken leakage.

---

Task S4: Ingest type-stamping in NotificationOutboxActor

Classification: standard Estimated implement time: ~3 min Parallelizable with: S3, S6

Files:

• Modify: src/ZB.MOM.WW.ScadaBridge.NotificationOutbox/NotificationOutboxActor.cs (the ingest path that currently hard-codes NotificationType.Email, ~line 1147)
• Test: tests/ZB.MOM.WW.ScadaBridge.NotificationOutbox.Tests/ (ingest type-stamping test)

Steps:

1. At ingest, resolve the target list (GetListByNameAsync(msg.ListName)); stamp Type = list?.Type ?? NotificationType.Email onto the new Notification. Keep the at-least-once insert-if-not-exists semantics intact (do NOT change idempotency). Add a brief comment replacing the old "all notifications are email" comment.
2. Test: ingest for an Email list stamps Email; ingest for an Sms list stamps Sms; ingest for a missing list defaults Email (and later parks at delivery — assert default only).
3. Build + run NotificationOutbox.Tests (filtered). Commit (pathspec).

Acceptance: notifications inherit the list's Type at ingest; idempotency unchanged; tests green.

---

Task S5: Management — list-command Type + SMS-config commands/handlers

Classification: standard Estimated implement time: ~5 min Parallelizable with: S2

Files:

• Modify: src/ZB.MOM.WW.ScadaBridge.Commons/Messages/Management/NotificationCommands.cs
• Modify: src/ZB.MOM.WW.ScadaBridge.ManagementService/ManagementActor.cs
• Test: tests/ZB.MOM.WW.ScadaBridge.ManagementService.Tests/ (handler tests)

Steps:

1. NotificationCommands.cs: add NotificationType Type = NotificationType.Email to CreateNotificationListCommand and UpdateNotificationListCommand (additive trailing param). Add record ListSmsConfigsCommand; and record UpdateSmsConfigCommand(int SmsConfigId, string AccountSid, string FromNumber, string? MessagingServiceSid = null, string? ApiBaseUrl = null, string? AuthToken = null); (mirror UpdateSmtpConfigCommand, preserve-if-null for AuthToken).
2. ManagementActor: in Create/Update list handlers, persist cmd.Type on the NotificationList. Add HandleListSmsConfigs + HandleUpdateSmsConfig (preserve-if-null AuthToken/ApiBaseUrl), role-gate (Designer/Admin per SMTP), and audit via a credential-free SmsConfigPublicShape (mirror SmtpConfigPublicShape — never log/return AuthToken). Wire the command routing entries.
3. Handler tests: create list with Type=Sms persists Sms; update SMS config preserves AuthToken when null, never surfaces AuthToken in audit/response.
4. Build Commons + ManagementService + run ManagementService.Tests (filtered). Commit (pathspec).

Acceptance: list commands carry Type; SMS-config commands/handlers exist, role-gated, secret-safe; tests green.

---

Task S6: CLI — list --type/--phones + notification sms group

Classification: standard Estimated implement time: ~5 min Parallelizable with: S3, S4

Files:

• Modify: src/ZB.MOM.WW.ScadaBridge.CLI/Commands/NotificationCommands.cs
• Modify: src/ZB.MOM.WW.ScadaBridge.CLI/README.md
• Test: tests/ZB.MOM.WW.ScadaBridge.CLI.Tests/

Steps:

1. List create/update: add --type email|sms (default email) and --phones (comma-separated E.164). Validate: email type requires --emails; sms type requires --phones; reject mismatch. Build Create/UpdateNotificationListCommand with Type + the right recipient set. (Recipients for SMS map to phone numbers — coordinate with how recipients are submitted; if recipients are added via a separate command, set Type on the list and feed phones through the recipient path.)
2. Add notification sms list (→ ListSmsConfigsCommand) and notification sms update --id --account-sid --from-number [--messaging-service-sid] [--api-base-url] [--auth-token] (→ UpdateSmsConfigCommand), mirroring the notification smtp group. Render JSON/table; never print AuthToken.
3. Update CLI README (notification section: --type/--phones, sms group).
4. Build CLI + run CLI.Tests (filtered). Commit (pathspec).

Acceptance: CLI creates SMS lists + manages SMS config; validation enforced; secret never printed; tests + README updated.

---

Task S7: Central UI — NotificationListForm Type selector + per-type recipient input

Classification: standard Estimated implement time: ~5 min Parallelizable with: S8, S9, S10

Files:

• Modify: src/ZB.MOM.WW.ScadaBridge.CentralUI/Components/Pages/Notifications/NotificationListForm.razor
• Test: tests/ZB.MOM.WW.ScadaBridge.CentralUI.Tests/Pages/ (NotificationListForm tests)

Steps:

1. Add an adapter-gated Type selector: source the options from the registered INotificationDeliveryAdapter Types (inject the adapter set or a small accessor; if injecting the adapters into the UI is awkward, expose a server-side accessor that returns the registered NotificationType set). Today renders Email + SMS. Selector enabled on create; read-only on edit (Id.HasValue) to prevent recipient-kind mismatch.
2. Recipient editor: when Type=Email show the Email input + validate email; when Type=Sms show a Phone input + validate E.164. Build the recipient via NotificationRecipient.ForEmail/ForSms. Update the recipients table to show Email or Phone per type.
3. On save, pass Type to the create command / new list.
4. bUnit tests: selector renders Email+SMS; choosing SMS shows phone input + validation; create persists Type; edit shows Type read-only. Razor hygiene: any @* *@ comment must sit OUTSIDE element start tags (the recurring circuit-crash landmine).
5. Build CentralUI + run the NotificationListForm tests (filtered). Commit (pathspec).

Acceptance: Type selector adapter-gated + create-only; per-type recipient input + validation; tests green; no Razor start-tag comments.

---

Task S8: Central UI — NotificationLists Type column

Classification: small Estimated implement time: ~3 min Parallelizable with: S7, S9, S10

Files:

• Modify: src/ZB.MOM.WW.ScadaBridge.CentralUI/Components/Pages/Notifications/NotificationLists.razor
• Test: tests/ZB.MOM.WW.ScadaBridge.CentralUI.Tests/Pages/NotificationListsPageTests.cs

Steps:

1. Add a Type column to the lists table (render NotificationType). Keep markup tokenized/consistent with the M10 table conventions.
2. Update/extend NotificationListsPageTests to assert the Type column renders (e.g. an SMS list shows "Sms").
3. Build CentralUI + run NotificationListsPageTests. Commit (pathspec).

Acceptance: Type column renders; test green.

---

Task S9: Central UI — SMS configuration page

Classification: standard Estimated implement time: ~5 min Parallelizable with: S7, S8, S10

Files:

• Create: src/ZB.MOM.WW.ScadaBridge.CentralUI/Components/Pages/Notifications/SmsConfiguration.razor
• Modify: the nav/menu component that lists /notifications/smtp (add /notifications/sms)
• Test: tests/ZB.MOM.WW.ScadaBridge.CentralUI.Tests/Pages/ (SmsConfiguration page test)

Steps:

1. New page /notifications/sms (Admin-only, mirror SmtpConfiguration.razor): list SMS configs, create/edit form (AccountSid, FromNumber, MessagingServiceSid, ApiBaseUrl, AuthToken — AuthToken write-only/masked, preserve-if-blank on edit), save via repository/management. Never render the stored AuthToken back.
2. Add the nav entry next to the SMTP settings entry.
3. bUnit: page renders config rows; AuthToken input is masked/not pre-filled; save calls the repository. Razor start-tag comment hygiene.
4. Build CentralUI + run the page test. Commit (pathspec; git add new file).

Acceptance: SMS config page works + Admin-gated + secret-safe; nav entry added; test green.

---

Task S10: Transport — recipient PhoneNumber DTO + SmsConfigDto round-trip

Classification: standard Estimated implement time: ~5 min Parallelizable with: S7, S8, S9

Files:

• Modify: src/ZB.MOM.WW.ScadaBridge.Transport/Serialization/EntityDtos.cs
• Modify: src/ZB.MOM.WW.ScadaBridge.Transport/Serialization/EntitySerializer.cs
• Test: tests/ZB.MOM.WW.ScadaBridge.Transport.*Tests/

Steps:

1. NotificationRecipientDto: add string? PhoneNumber (trailing, nullable → backward-compatible). SmsConfigDto mirroring SmtpConfigDto (secret in SecretsBlock). Add IReadOnlyList<SmsConfigDto> SmsConfigs to BundleContentDto and IReadOnlyList<SmsConfiguration> SmsConfigurations to EntityAggregate.
2. EntitySerializer: map recipient PhoneNumber both directions; map SMS configs export/import (mirror SMTP, including SecretsBlock handling). Keep schemaVersion evolution additive per repo convention.
3. Tests: recipient phone round-trips; SMS config round-trips with secret in SecretsBlock; old bundle without PhoneNumber deserializes to null.
4. Build Transport + run Transport tests (filtered). Commit (pathspec).

Acceptance: SMS recipient phone + SMS config travel in bundles; backward-compatible; tests green.

---

Task S11: Integration — build, migration drift, docker, Playwright, live smoke, docs, review

Classification: high-risk Estimated implement time: ~10 min (+ docker rebuild wall-time) Parallelizable with: none

Files:

• Modify: docs/requirements/Component-NotificationService.md, docs/requirements/Component-NotificationOutbox.md
• Modify: CLAUDE.md (NotificationType = Email+Sms; T9/T10 delivered as SMS — flip the M6 deferral note; add the SMS-adapter decision bullet)
• Modify: README.md (component table / notes if needed)
• Create (test): tests/ZB.MOM.WW.ScadaBridge.CentralUI.PlaywrightTests/Notifications/SmsNotificationListTests.cs (or extend existing notification Playwright)

Steps:

1. Full-solution build: dotnet build ZB.MOM.WW.ScadaBridge.slnx — 0 warnings/errors.
2. EF model-drift check (no PendingModelChangesWarning).
3. Full unfiltered managed test run dotnet test ZB.MOM.WW.ScadaBridge.slnx (run 2–3× for load-flake surfacing per the integration memory). Triage any red: prove pre-existing via git diff --stat c72d7b79..HEAD -- <target files> before attributing.
4. Docker rebuild: bash docker/deploy.sh; /health/ready 200 on the active node.
5. Live smoke via CLI against the cluster: set an SMS config (fake AccountSid + --api-base-url pointed at a mock, OR document Twilio sandbox), create an --type sms list with a phone recipient, submit a notification, verify it routes to the SMS adapter and parks-with-reason when the fake returns an error (proves routing + classification end-to-end). Also verify an Email list still delivers (no regression).
6. Playwright: SMS-list create flow (Type selector → SMS → phone recipient → save) against the freshly-rebuilt cluster; broad notification-page smoke. Razor circuit-crash check: load /notifications/lists/create + /notifications/sms in a real browser (the bUnit-invisible render-crash gate).
7. Docs reconciliation: Component docs + CLAUDE.md + README + CLI README synced; confirm the M6 deferral note is flipped to "delivered (SMS pivot)."
8. Whole-branch integration review over git diff c72d7b79..HEAD (Bash-capable reviewer): end-to-end trace of the new NotificationType.Sms path (submit → ingest stamp → adapter dispatch → Twilio POST → park/retry), shared-component injection regressions (any new ctor/[Inject] dep → grep every fixture across ALL test projects), and secret-leak audit (AuthToken never logged/returned/rendered).
9. Commit docs (pathspec). Then hand to finishing-a-development-branch.

Acceptance: full build + full managed tests green; docker healthy; live smoke proves SMS routing + Email no-regression; Playwright + render-crash gate green; docs synced; whole-branch review INTEGRATION-CLEAN.