feat: optional AI salience layer (self-hosted)

.env.example

@@ -42,6 +42,11 @@ SLACK_BOT_TOKEN=xoxb-replace-me
 # route is not registered.
 # SLACK_SIGNING_SECRET=
 
+# --- AI layer (optional) ---
+# Model-provider API key for the optional AI layer (docs/ai.md). Required for
+# ai.provider: gemini; optional for openai_compatible (keyless local endpoints).
+# AI_API_KEY=
+
 # --- Reverse proxy (docker compose) ---
 # Public DNS name that points at this host. Caddy uses it as the virtual-host name and obtains a
 # Let's Encrypt certificate via the HTTP-01 challenge. Required when using compose.yaml.

.github/workflows/ci.yml

@@ -10,7 +10,7 @@ permissions:
   contents: read
 
 env:
-  GO_VERSION: "1.25.11"
+  GO_VERSION: "1.25.12"
   GOVULNCHECK_VERSION: "v1.3.0"
 
 jobs:

.golangci.yml

@@ -113,21 +113,42 @@ linters:
             - github.com/mptooling/notifycat/internal/kernel
             - github.com/mptooling/notifycat/internal/digest/domain
             - github.com/mptooling/notifycat/internal/routing/domain
+            - github.com/mptooling/notifycat/internal/salience/domain
           deny:
             - pkg: github.com/mptooling/notifycat/internal
-              desc: digest/domain imports only the shared kernel, the routing domain, and the standard library — never application, infrastructure, store, slack, or github
+              desc: digest/domain imports only the shared kernel, the routing and salience domains, and the standard library — never application, infrastructure, store, slack, or github
+        # digest/application production may reference the salience domain (the
+        # Advisor port), but only tests may import salience/application — the
+        # fakes delegate to the deterministic advisor; production advisor
+        # construction belongs to the composition root.
         digest-application:
           list-mode: lax
           files:
             - "**/internal/digest/application/**"
+            - "!**/internal/digest/application/**_test.go"
           allow:
             - github.com/mptooling/notifycat/internal/kernel
             - github.com/mptooling/notifycat/internal/digest/domain
             - github.com/mptooling/notifycat/internal/digest/application
             - github.com/mptooling/notifycat/internal/routing/domain
+            - github.com/mptooling/notifycat/internal/salience/domain
           deny:
             - pkg: github.com/mptooling/notifycat/internal
-              desc: digest/application imports only its own domain layer, the routing domain, and the shared kernel — never infrastructure, store, slack, or github
+              desc: digest/application imports only its own domain layer, the routing and salience domains, and the shared kernel — never infrastructure, store, slack, or github
+        digest-application-tests:
+          list-mode: lax
+          files:
+            - "**/internal/digest/application/**_test.go"
+          allow:
+            - github.com/mptooling/notifycat/internal/kernel
+            - github.com/mptooling/notifycat/internal/digest/domain
+            - github.com/mptooling/notifycat/internal/digest/application
+            - github.com/mptooling/notifycat/internal/routing/domain
+            - github.com/mptooling/notifycat/internal/salience/domain
+            - github.com/mptooling/notifycat/internal/salience/application
+          deny:
+            - pkg: github.com/mptooling/notifycat/internal
+              desc: digest/application tests may additionally use salience/application for the deterministic-advisor fakes
         notification-domain:
           list-mode: lax
           files:
@@ -136,21 +157,40 @@ linters:
             - github.com/mptooling/notifycat/internal/kernel
             - github.com/mptooling/notifycat/internal/notification/domain
             - github.com/mptooling/notifycat/internal/routing/domain
+            - github.com/mptooling/notifycat/internal/salience/domain
           deny:
             - pkg: github.com/mptooling/notifycat/internal
-              desc: notification/domain imports only the shared kernel, the routing domain, and the standard library — never application, infrastructure, store, slack, or github
+              desc: notification/domain imports only the shared kernel, the routing and salience domains, and the standard library — never application, infrastructure, store, slack, or github
+        # Same test carve-out as digest-application: only tests may import
+        # salience/application (deterministic-advisor fakes).
         notification-application:
           list-mode: lax
           files:
             - "**/internal/notification/application/**"
+            - "!**/internal/notification/application/**_test.go"
           allow:
             - github.com/mptooling/notifycat/internal/kernel
             - github.com/mptooling/notifycat/internal/notification/domain
             - github.com/mptooling/notifycat/internal/notification/application
             - github.com/mptooling/notifycat/internal/routing/domain
+            - github.com/mptooling/notifycat/internal/salience/domain
           deny:
             - pkg: github.com/mptooling/notifycat/internal
-              desc: notification/application imports only its own domain layer, the routing domain, and the shared kernel — never infrastructure, store, slack, or github
+              desc: notification/application imports only its own domain layer, the routing and salience domains, and the shared kernel — never infrastructure, store, slack, or github
+        notification-application-tests:
+          list-mode: lax
+          files:
+            - "**/internal/notification/application/**_test.go"
+          allow:
+            - github.com/mptooling/notifycat/internal/kernel
+            - github.com/mptooling/notifycat/internal/notification/domain
+            - github.com/mptooling/notifycat/internal/notification/application
+            - github.com/mptooling/notifycat/internal/routing/domain
+            - github.com/mptooling/notifycat/internal/salience/domain
+            - github.com/mptooling/notifycat/internal/salience/application
+          deny:
+            - pkg: github.com/mptooling/notifycat/internal
+              desc: notification/application tests may additionally use salience/application for the deterministic-advisor fakes
         review-domain:
           list-mode: lax
           files:
@@ -198,6 +238,49 @@ linters:
           deny:
             - pkg: github.com/mptooling/notifycat/internal
               desc: diagnostics/application imports its own domain, the validation domain/application, and the routing domain — never infrastructure, config, store, slack, http, or security
+        salience-domain:
+          list-mode: lax
+          files:
+            - "**/internal/salience/domain/**"
+          allow:
+            - github.com/mptooling/notifycat/internal/kernel
+            - github.com/mptooling/notifycat/internal/salience/domain
+          deny:
+            - pkg: github.com/mptooling/notifycat/internal
+              desc: salience/domain imports only the shared kernel and the standard library — never application, infrastructure, store, slack, or a provider client
+        salience-application:
+          list-mode: lax
+          files:
+            - "**/internal/salience/application/**"
+          allow:
+            - github.com/mptooling/notifycat/internal/kernel
+            - github.com/mptooling/notifycat/internal/salience/domain
+            - github.com/mptooling/notifycat/internal/salience/application
+          deny:
+            - pkg: github.com/mptooling/notifycat/internal
+              desc: salience/application imports only its own domain layer and the shared kernel — never infrastructure, a provider SDK, or the network
+        # Provider sibling independence is a spec guarantee: gemini and
+        # openaicompat must not share code, so neither may import the other.
+        salience-infrastructure-gemini:
+          list-mode: lax
+          files:
+            - "**/internal/salience/infrastructure/gemini/**"
+          allow:
+            - github.com/mptooling/notifycat/internal/salience/domain
+            - github.com/mptooling/notifycat/internal/salience/infrastructure/gemini
+          deny:
+            - pkg: github.com/mptooling/notifycat/internal
+              desc: the gemini provider imports only the salience domain and the standard library — never its openaicompat sibling or another domain
+        salience-infrastructure-openaicompat:
+          list-mode: lax
+          files:
+            - "**/internal/salience/infrastructure/openaicompat/**"
+          allow:
+            - github.com/mptooling/notifycat/internal/salience/domain
+            - github.com/mptooling/notifycat/internal/salience/infrastructure/openaicompat
+          deny:
+            - pkg: github.com/mptooling/notifycat/internal
+              desc: the openaicompat provider imports only the salience domain and the standard library — never its gemini sibling or another domain
     errcheck:
       exclude-functions:
         - fmt.Fprint
@@ -231,6 +314,15 @@ linters:
         linters:
           - gosec
           - unparam
+      # The composition-root package is deliberately named "runtime"
+      # (referenced as runtime.Module); it is never imported alongside the
+      # stdlib runtime package. Excluded here rather than via //nolint because
+      # revive attributes the package-name finding to an arbitrary file in the
+      # package, so a per-file directive breaks when files are added.
+      - path: internal/runtime/
+        linters:
+          - revive
+        text: "avoid package names that conflict"
 
 formatters:
   enable:

ARCHITECTURE.md

@@ -50,11 +50,11 @@ A hexagonal Go app needs two pieces of connective tissue that are deliberately *
 
 Notifycat has **no user accounts, sessions, logins, roles, or permissions**, so there is no authentication or authorization *domain* — modelling them as domains would produce empty, ruleless folders. The only authentication that exists today is **inbound webhook message authentication**: proving, by HMAC signature, that a request genuinely came from GitHub or Slack. That is a cross-cutting security concern, so it lives in **`platform/security`** as an explicit `SignatureVerifier` port with one adapter per provider scheme — not inside a business domain. The inbound adapters in `notification` and `review` consume that port and only parse the verified body; they never re-implement verification. Outbound credentials (the Slack bot token, the GitHub token) are `Secret`s from `platform/config`, passed to the `platform/slack` / `platform/github` clients.
 
-**Authorization does not exist today** — single tenant, no access control beyond "is this webhook authentic." If the multi-tenant SaaS direction lands (see the productization plan), *then* authentication (tenant/user identity, GitHub-App OAuth installs, API keys) and authorization (tenant isolation, who may configure which mappings) become genuine bounded contexts — new `internal/identity` and `internal/access` domains alongside these seven, owning their ports in the domain layer and plugging into the same fx composition. That is deliberately out of scope for this refactor.
+**Authorization does not exist today** — single tenant, no access control beyond "is this webhook authentic." If the multi-tenant SaaS direction lands (see the productization plan), *then* authentication (tenant/user identity, GitHub-App OAuth installs, API keys) and authorization (tenant isolation, who may configure which mappings) become genuine bounded contexts — new `internal/identity` and `internal/access` domains alongside these eight, owning their ports in the domain layer and plugging into the same fx composition. That is deliberately out of scope for this refactor.
 
 ## Domain map
 
-Seven domains over the shared kernel and platform. The core domain is **notification**; everything else supports it.
+Eight domains over the shared kernel and platform. The core domain is **notification**; everything else supports it.
 
 ```mermaid
 flowchart TB
@@ -86,13 +86,14 @@ flowchart TB
 
 | Domain | Business capability | Absorbs today's packages |
 | --- | --- | --- |
-| **notification** | Receive a GitHub PR event and keep one Slack message per (PR, channel) in sync — post on open, update/react on state change, delete on draft. Includes bot-PR classification/formatting and AI-reviewer suppression. | `pullrequest` (dispatcher, open/close/draft + reaction handlers), `botpr`, `aireview`, `githubhook` parsing (verification → `platform/security`), the messages repository from `store` |
+| **notification** | Receive a GitHub PR event and keep one Slack message per (PR, channel) in sync — post on open, update/react on state change, delete on draft. Includes bot-PR classification/formatting and AI-reviewer suppression. OpenHandler, CloseHandler, and the reaction handlers (ApproveHandler, CommentedHandler, RequestChangeHandler) consult `saliencedomain.Advisor` when AI is enabled. | `pullrequest` (dispatcher, open/close/draft + reaction handlers), `botpr`, `aireview`, `githubhook` parsing (verification → `platform/security`), the messages repository from `store` |
 | **review** | The interactive "Start review" flow: a Slack button click records a reviewer and appends an in-review marker; a submitted GitHub review finishes sessions and clears the in-review state; reviewers are shown on close. | `startreview`, `slackhook` parsing (verification → `platform/security`), the `code_reviews` repository from `store`, the review-session logic in `pullrequest` |
 | **routing** | Resolve a repo (and optionally a PR's changed files) to the Slack channel(s) and behavioral config that apply, across global/org/repo tiers and monorepo path rules. | `mappings` (provider, parsing, tiers, defaults, lock), the per-PR `Router` from `pullrequest`, the changed-files reader over `platform/github` |
 | **validation** | Validate mapping entries against Slack (channel exists, bot present) and GitHub (repo exists); cache results in `config.lock`. Powers the startup gate, the doctor, and `notifycat-config validate`. | `validate` |
-| **digest** | Periodically post a digest of stuck (stale) PRs per the enabled cron schedules. | `digest` |
+| **digest** | Periodically post a digest of stuck (stale) PRs per the enabled cron schedules. The digest reporter consults `saliencedomain.Advisor` when AI is enabled. | `digest` |
 | **maintenance** | Background housekeeping: delete stale message rows past their TTL; reconcile closed PRs. | `cleanup`, `reconcile` |
 | **diagnostics** | Operator tooling: the preflight doctor, the `notifycat-config` CLI (list/validate), and the smoke-test delivery. | `doctor`, `mappingcli`, `smoke` |
+| **salience** | Optional AI decision layer: decides notification salience — per-channel loudness, mentions subset, emoji, format, emphasis, bounded notes, digest ordering — behind a no-error `Advisor` port with deterministic fallback; operator-facing name is "AI". Providers under `salience/infrastructure/{gemini,openaicompat}`. | `salience` (new) |
 
 `internal/app` (the old hand-written composition root) has been deleted: its wiring is per-domain fx modules, and its lifecycle orchestration is `fx.Lifecycle` hooks composed in `internal/runtime` and each `cmd/*/main.go`.
 

CLAUDE.md

@@ -29,13 +29,13 @@ underlying `go ...` invocations work without `just` if needed.
 | Single test | `go test -race ./internal/notification/... -run TestApproveHandler` |
 | Single package | `go test -race ./internal/notification/...` |
 | Lint only | `just lint` (requires `golangci-lint` locally) |
-| Vuln scan | `just vuln` (runs in Docker against the pinned `golang:1.25.10-alpine` — slower; CI also runs this) |
+| Vuln scan | `just vuln` (runs in Docker against the pinned `golang:1.25.12-alpine` — slower; CI also runs this) |
 | Build all binaries | `just build` |
 | Run server locally | `just serve` |
 | Apply migrations | `just migrate` (or `just docker-migrate` against `./data`) |
 | Build & run Docker image | `just docker-build` then `just docker-serve` |
 
-Go toolchain is pinned at **1.25.10**. CI runs all of the
+Go toolchain is pinned at **1.25.12**. CI runs all of the
 `just check` steps (`go vet`, `golangci-lint`, `govulncheck`,
 `go test -race`, `go build`). `just` is dev-only — it is not in the
 runtime image or Go modules.
@@ -46,7 +46,7 @@ Notifycat is a single-process HTTP server with a SQLite sidecar. It receives Git
 
 ### Domain structure
 
-Seven domains live under `internal/<domain>/`, each with three layers (`domain/`, `application/`, `infrastructure/`) and a `module.go` exporting an `fx.Module`:
+Eight domains live under `internal/<domain>/`, each with three layers (`domain/`, `application/`, `infrastructure/`) and a `module.go` exporting an `fx.Module`:
 
 | Domain | Responsibility |
 | --- | --- |
@@ -57,6 +57,7 @@ Seven domains live under `internal/<domain>/`, each with three layers (`domain/`
 | `digest` | Periodic stuck-PR digest per cron schedule |
 | `maintenance` | Background housekeeping: delete stale message rows; reconcile closed PRs |
 | `diagnostics` | Operator tooling: `notifycat-doctor`, `notifycat-config`, smoke test |
+| `salience` | Optional AI decision layer: decides notification salience — per-channel loudness, mentions subset, emoji, format, emphasis, bounded notes, digest ordering — behind a no-error `Advisor` port with deterministic fallback; operator-facing name is "AI" |
 
 The shared kernel (`internal/kernel`) holds pure value objects (`PR`, `Event`, `Sender`, `Review`) and GitHub event/action/review-state enums — stdlib only. The shared platform (`internal/platform/`) holds domain-agnostic clients: `config`, `persistence` (GORM/SQLite), `slack`, `github`, `httpx`, and `security` (HMAC `SignatureVerifier` with `GitHubVerifier`/`SlackVerifier` adapters).
 
@@ -85,6 +86,8 @@ POST /webhook/slack/interactions
   → review/application start-review use case
 ```
 
+When AI is enabled, OpenHandler, CloseHandler, and the reaction handlers (ApproveHandler, CommentedHandler, RequestChangeHandler) consult `saliencedomain.Advisor` before sending to the Messenger port; the digest reporter does the same.
+
 Every silent no-op logs `ignored webhook event` with a `reason` field (`no_handler`, `no_mapping`, `no_stored_message`, `already_sent`). The operations doc has the full reason table — that contract matters for debugging deliveries that return 200 but don't update Slack.
 
 ### Mappings & startup validation