add evidence-grounded ai assistance

docs/OPERATIONS.md

@@ -172,6 +172,18 @@ Do not run `docker compose down -v` on a data-bearing environment: it removes th
 
 Before production, complete a migration from SQLite to a reviewed production database, add schema/indexes for jobs/idempotency/events, domain observations, and scan history/cache, implement transactional sequence assignment and tenant authorization, and prove cancellation/retry/lease recovery under concurrency. Add durable queue/worker and scanner-isolation operations, bounded DNS/PSL/website processing, TTL/freshness-aware cache invalidation, SSRF/DNS-rebinding/redirect-chain tests, hard size/time/crawl budgets, uncertainty and association-review workflows, and a separately approved availability provider. Add metrics and alerts for queue age, failures, retries, cancellation latency, event lag/gaps, DNS/scanner status/error rates, cache freshness, blocked destinations, crawl-budget exhaustion, provider rate limits/circuit state, and SSE connections; define backup/restore and event-retention drills. Redis, Celery, Postgres, schedulers, discovery adapters, and production scanners are possible future components—not implicit Compose dependencies. No automated discovery, domain acquisition, ownership assertion, or outreach may be inferred from the scaling path.
 
+## Phase 13 optional AI assistance operations
+
+Keep AI disabled unless the provider registry, tenant scope, purpose, data class, redaction policy, retention class, rate/token/cost budgets, approval expiry, and operational enablement have been reviewed and recorded. The current Compose stack has no configured provider; do not enable one by adding an arbitrary URL or secret. Store credentials only in the deployment secret manager. A fallback must be pre-approved for the same purpose and input class and must inherit the primary provider's tenant, citation, redaction, retention, and authority constraints.
+
+Before an AI request, verify the authenticated tenant and permission, active provider/policy version, suppression state, and bounded evidence selection. Minimize and redact inputs; exclude secrets, credentials, session data, raw page bodies, unrelated personal data, and unnecessary full contact values. Monitor request/response size, latency, provider health, fallback rate, quota/rate/cost usage, redaction failures, policy/approval denials, and `unknown`/`unavailable`/partial outcomes. Provider failure, stale or conflicting evidence, prompt-injection indicators, or hash/citation mismatch is a safe non-result—not a retry reason and never permission to present invented facts.
+
+Review every suggestion as **AI draft — human review required**. Confirm citations resolve within the same tenant, the evidence hash still matches the cited snapshot, observed times/freshness are acceptable, suppression remains clear, and the provider/policy approval is current. An approval must be explicit, reasoned, audited, and read back; changed evidence or policy invalidates the proposal. Rejection, expiry, failed approval, and fallback events must remain auditable. Never report generation or approval request acceptance as persistence or completion.
+
+The operational path must not alter pipeline/interactions/outcomes as if communication occurred, send outreach, probe SMTP, create campaigns, schedule follow-ups, merge records, acquire domains, or otherwise act autonomously in CRM. Suppressed/do-not-contact records remain visible for safety review and blocked from contact-related actions. Retain only the approved minimum AI lineage (redacted fingerprint, output, citations/hash, versions, approval and audit metadata); apply deletion/legal-hold rules to prompts, outputs, evidence snapshots, caches, and logs and verify deletion without removing required suppression/audit history.
+
+On suspected provider misuse, data leakage, hallucinated/invented facts, prompt injection, cross-tenant exposure, unexpected outbound traffic, cost runaway, or suppression bypass: disable the AI capability/kill switch, stop affected jobs, preserve redacted evidence and audit metadata, revoke/rotate provider credentials, determine affected tenants and retention obligations, and require security/product/legal review before re-enabling. Production remains blocked until provider contracts/DPA, tenant-isolation, redaction, citation/hash, approval/rollback, evaluation, retention/deletion, monitoring, and recovery tests pass.
+
 ## Incident checklist
 
 1. Record time, affected service, image/config revision, and observed health state.

docs/SECURITY.md

@@ -136,4 +136,16 @@ Treat manually supplied business information, notes, and source references as po
 
 Pin or review base-image and dependency updates, scan images before release, use least-privilege GitHub tokens, and avoid printing environment values. CI may validate Compose with empty optional bootstrap variables and call unauthenticated health checks; it is not a substitute for authorization/tenant-isolation tests, provenance policy review, Argon2id parameter review, MFA testing, or a security assessment.
 
+## Phase 13 optional AI assistance security controls
+
+- AI is an optional, deny-by-default review aid. It may summarize or classify tenant-held evidence, but it is not an authority for facts, identity, ownership, deliverability, score/eligibility, CRM state, or contact permission. No AI path may send messages, probe SMTP, create campaigns, schedule follow-ups, merge records, acquire domains, or take autonomous CRM/outreach actions.
+- Provider configuration must use a server-side allowlist. Each primary or fallback provider requires an approved purpose/capability, model/version, tenant and data-class scope, processing/retention terms, region/egress policy, timeout/token/rate/cost budgets, health/circuit state, approval owner/expiry, and explicit operational enablement. Fallback may only preserve the same purpose, scope, redaction policy, evidence set, and authority; it must not silently broaden processing. Missing/expired approval, outage, quota, timeout, or policy failure fails closed to `unknown`/`unavailable`.
+- Keep provider credentials in a secret manager; never expose them to the browser or store them in prompts, responses, Compose, source, committed `.env`, logs, audit details, or error messages. Disable provider access immediately on suspected misuse or data leakage.
+- Minimize before transmission: send only bounded fields/evidence needed for the approved task; redact credentials, tokens, session data, secrets, raw page bodies, unnecessary personal/contact data, and unrelated tenant data. Enforce input/output size limits and log only a redacted request/policy fingerprint. Treat retrieved evidence and model output as untrusted input, including prompt-injection instructions; never invent facts or present invented facts as supported claims.
+- Every suggestion must cite tenant-scoped evidence IDs/source references and bind to a cryptographic evidence hash of the exact evidence snapshot, with observed time, uncertainty/conflict state, provider/model/version, and policy version. Hashing proves lineage to a snapshot, not source truth. Verify citations and hash equality server-side; a changed, missing, suppressed, stale, blocked, or conflicting input invalidates approval and requires re-review.
+- Approval is an explicit authorized human action, never an AI or retry side effect. Re-check tenant scope, suppression, permissions, evidence freshness/hash, provider approval, and policy version at approval time. Record proposal, citations/hash, actor, reason, before/after value, version, timestamp, rejection/expiry, and correlation/idempotency data in an append-oriented audit trail. Approval cannot create a verified fact or outreach authorization.
+- AI prompts/fingerprints, outputs, evidence snapshots/citations, approvals, caches, and audit events need separate retention classes, redaction rules, deletion/legal-hold semantics, tenant-keyed access, and readback/deletion verification. Retain only the minimum lineage needed to explain an approved result; do not retain full prompts or source content when a hash/reference suffices.
+- Suppression/do-not-contact is evaluated before AI input, generation, persistence, response, export, cache, queueing, and approval. Suppressed records remain visible as safety state, are never silently deleted, and cannot be revived by confidence, fallback, human approval, or later pipeline/outcome data.
+- Production requires provider/DPA/legal review, tenant-isolation and citation/hash tests, redaction and prompt-injection/hallucination evaluations, human-review and rollback semantics, immutable/tamper-evident audit, cost/rate monitoring, incident kill switch, retention/deletion jobs, and durable worker/retry idempotency. The current Compose stack has no configured AI provider and is not production-ready for AI processing.
+
 Report vulnerabilities privately to the repository maintainers; do not include live credentials or personal data in an issue.