source: .forge/design/architecture.md · generated — edit the markdown, not this file

Empire Teas CRM — System Architecture

Status: approved at Gate 2 Run 2 (2026-08-06, passed-with-risks-and-spikes — verdict: Dinil). See .forge/engagement-gate-runs.md § Gate 2 Run 2. Last updated: 2026-10-27 (Rev 79 — see §Revisions) Related: .forge/project-prd.md, .forge/project-prd-signals.md, .claude/CLAUDE.md Revision log: see ## Revisions at the foot of this document

Overview

A single-tenant, custom-built B2B sales CRM for Empire Teas’ front-office tea-export sales process (bulk + private-label), replacing Pipedrive. A React single-page app (Vite — AD #21) talks to a Java/Spring Boot backend API backed by PostgreSQL; the backend owns two-way email and calendar sync with reps’ Microsoft 365 mailboxes, reads their contacts one way into the CRM (F22), runs the human-in-the-loop AI layer on Claude via Amazon Bedrock (in-account — AD #19), maintains the weekly bulk-pricing record the Tea Room publishes, and produces (V1: manual, later: API) handoff to the ERP once a deal is Won.

System Context

flowchart LR
  rep((Sales Rep / Manager / Taster / Tea Room / Exec / Admin)) -->|HTTPS| frontend[Frontend — React SPA<br/>S3 + CloudFront]
  frontend -->|REST, session cookie| backend[Backend API — Spring Boot]
  capture[Trade-show capture app — React PWA<br/>own repo + own URL, S3 + CloudFront] -->|HTTPS, capture API slice → F11 intake| backend
  backend -->|system mail| notify[[Amazon SES]]
  backend -->|JDBC| db[(PostgreSQL — RDS)]
  backend -->|AWS SDK, in-account| claude[AI — AD 19:<br/>Claude via Amazon Bedrock<br/>Haiku 4.5 + Sonnet 5.5]
  backend <-->|OAuth2 + Microsoft Graph API| mailbox[Microsoft 365 mailboxes<br/>per-user]
  backend -->|S3 API| files[(S3 — file attachments)]
  worker[Background Worker — same codebase, async] -->|consumes| queue[[AWS SQS]]
  backend -->|enqueues jobs| queue
  sched[[EventBridge Scheduler]] -->|timed triggers| queue
  worker --> db
  worker <--> mailbox
  worker -->|batch AI calls| claude
  backend -.->|V1: generates manual doc; follow-on: IFS API| erp[ERP — IFS today, new ERP ~2027]
  backend -.->|follow-on: reference prices only| auction[Tea-auction public API]

Components

Component Responsibility Stack Repo
Frontend Web App Renders dashboard, pipeline (Kanban), accounts, samples, quotes, activities/calendar, pricing screens, admin config; calls backend REST API TypeScript, React SPA (Vite — AD #21); static bundle on S3 + CloudFront (AD #22) <frontend-repo> = forge-et-fe
Backend API Domain logic, RBAC, REST endpoints, orchestrates AI calls behind a provider interface, enqueues background jobs, ERP handoff document generation Java 21, Spring Boot (Web, Security, Data JPA), Flyway <backend-repo> = forge-et-be
Background Worker Email/calendar/contact sync, Graph subscription renewal, AI batch triage (200-lead backlog + ongoing), scheduled rotting/stale/dormancy/quote-aging computation, weekly price-expiry roll (list exports are not a job: each is built in its request, up to 10,000 rows — F23-d FR-E7) Same Spring Boot codebase, @Async + SQS consumer (not a separate microservice) <backend-repo>
Scheduler Fires all time-based work onto SQS. Not in-process @Scheduled — see §Cross-Cutting > Scheduling AWS EventBridge Scheduler managed
Relational Database System of record for all domain entities (single-tenant schema) PostgreSQL (AWS RDS) managed
File Storage Attachments — artwork, POs, spec sheets, certification PDFs (F33-a on accounts, contacts and leads; F33-b on deals, quotes, samples and briefs), type- and size-validated on upload, and recorded as not scanned while virus scanning is switched off (PRD Rev 58) AWS S3, versioned (the GuardDuty scan step is built and not enabled — AD-O-4, Rev 52) managed
Job Queue Decouples webhook/poll ingestion, scheduled work, and batch AI from the request path (the Pipedrive migration’s runs answer in the request, each in one transaction — PRD Rev 70, F4-d FR-R5) AWS SQS (standard queue, idempotent consumers) managed
AI Provider Client Isolates all provider-specific request/response shape behind an AIProvider interface; routes per feature via {model, enabled} runtime config (single top-level provider — Bedrock) Haiku 4.5 (high-volume/simple; Haiku 5.5 once on Bedrock) / Sonnet 5.5 (complex synthesis; replaced Sonnet 5 on 2026-09-30), served via Amazon Bedrock inside the project’s AWS account (AD #19 — one bill, in-account processing); on failure the circuit breaker degrades to the manual path <backend-repo>
Trade-show capture app Exhibition lead capture — camera/QR, business-card read (Haiku 4.5 vision), company research + scoring, in-app notifications (no email — AD #42), feeds the F11 lead intake once a person converts each captured lead (PRD Rev 95) TypeScript, React PWA (Vite — AD #21) in its own repository (forge-et-pwa); static bundle on S3 + CloudFront at its own domain + ACM (AD #22), + a capture API slice on the backend forge-et-pwa + forge-et-be
System Mail Sender Sends automation/system mail from a shared authenticated domain (the stated improvement over Pipedrive’s per-mailbox-only sending); the capture app’s lead notifications are in-app, not mail (AD #42) AWS SES (AD-O-3 — decided) <backend-repo>

Data Flow

  • Synchronous path (interactive AI + all CRUD): frontend → backend REST → Postgres (and, for AI-touched screens, backend → Claude → back to caller) within the PRD’s <2s page / <10s AI-call budget.
  • Asynchronous path (SQS-backed), three producers:
    1. Mailbox push notifications — Microsoft Graph webhooks land on the queue; the worker reads each new message’s headers and stores and links only the messages that match a record by participant email address or thread (§ Mailbox integration).
    2. Scheduled triggers — EventBridge Scheduler enqueues timed work (stale/rotting recomputation, dormancy detection, quote aging, weekly price expiry, Graph subscription renewal). Spring Session’s expired-session cleanup stays in-process (AD #12).
    3. User-initiated batches — the 200+ lead AI-triage backlog (F11). List exports (F23) are not one: an export is built and returned in its request, up to 10,000 rows, with no stored file (F23-d FR-E7, the lead’s decision of 2026-11-15); a list that outgrows the limit is the trigger for a background export (owed.md). The Pipedrive migration (F4) is not one: its dry run and its write runs answer in the request, each write run in one transaction, while they fit the load balancer’s idle timeout (PRD Rev 70, F4-a FR-R1, F4-d FR-R5).
  • All queue consumers are idempotent — see §Cross-Cutting > Idempotency. SQS standard queues are at-least-once; duplicate delivery is normal, not exceptional.
  • Detailed request/sequence diagrams belong in <backend-repo>/docs/ once the repo exists — this section stays at the boundary-crossing level only.

Deployment Topology

  • Running cost is a design constraint (the lead, 2026-10-18; Rev 66). Empire Teas pays the AWS bill, and the cost annexe (.forge/client/sow-cost-annexe.md) is the estimate it was given. Billing settings — budgets, their alerts, cost allocation tags — are Shyamin Ayesh’s, Kavindu Anthony’s, Malinda Wellalage’s and Thilina Abeyrathna’s; keeping the bill low is the delivery team’s, through the design and through daily use. A design choice that adds a running cost (an always-on resource, a second Availability Zone, a NAT gateway, a larger model or instance, a resource left on in dev) is justified by a requirement and named in the spec; the cheaper option that meets the requirement is the default. The decisions already taken this way are in this section (no NAT, single-AZ, static frontends, one Fargate service, dev without the full account baseline) and in environments-and-identity.md §4 “What dev costs”.
  • AWS — two environments, not three (corrected 2026-08-06 against the costed proposal). One AWS account per environment (development, production) under an AWS Organization — account isolation so development can never reach production data. UAT rounds run in a temporary environment — one instance from Phase 1’s acceptance round to the end of Phase 2’s, then torn down (AD #23, revised 2026-11-18) — or in production before go-live with test data cleared afterwards — the development environment stays the build environment (revised from the earlier dev-doubles-as-UAT reading of proposal § A.2.1; the per-phase UAT rounds in client/project-timeline.md §2 are what changed it). The temporary UAT environment runs in the development account and reads dev’s Entra secrets, SES identity, backend image repository and Exa key (AD #4 as refined 2026-10-23; F38 OQ-A, F38-h; Rev 72). The proposal schedules development off outside working hours (A.2.1); while development is under way it runs around the clock instead, and after development it is scaled down, scheduled off or decommissioned (Rev 57). A separate staging environment is a priced add-on (+$45/mo, A.2.3) that has not been purchased; A.2.4 explicitly frames the three-environment configuration as the rejected ~$520/mo conventional option. This document previously assumed three environments.

    ⚠️ The proposal contradicts itself here — needs a client answer, not a doc edit. § 11 Deliverables promises Empire Teas “running development, staging, and production environments” at handover, while A.1/A.2 fund and cost only two. Tracked as OQ-49. This architecture follows the costed appendix until that is settled; if §11 wins, add the staging environment and its cost.

  • Compute: the backend is the only container service — one ECS Fargate service for the Spring Boot app (incl. the async worker, same task definition, separate scaling) behind an Application Load Balancer with TLS via ACM. Both frontends are static (AD #21/#22): the CRM SPA and the capture PWA each deploy as a built bundle to S3 behind CloudFront at their own domains (ACM certificates) — an SPA needs no server, so this replaces the Fargate frontend service the proposal costed (A.2), at lower cost. The capture PWA’s only server dependency is the backend capture API slice. The apps call the backend cross-site (AD #33, 2026-09-24): the backend keeps its own api.<env> address; the CRM and capture app call it with credentials, the backend’s CORS list names that environment’s two app origins, and the XSRF-TOKEN cookie is shared with the app hosts through a Domain attribute, under a cookie name that differs per environment. Runtime contexts (2026-08-18): three — local (developer machine: Docker Compose Postgres + LocalStack, stubbed seams, no real secrets), dev (AWS; build-only — UAT runs in the temporary acceptance environment), prod (AWS) — development and production have the same shape (identical topology, smaller sizes in dev) and run the identical image and single application.yml; all per-environment values come from the task definition (Spring profiles exist only for local/test bean wiring), with typed fail-fast configuration; conventions in coding-standards.md §5.
  • Network (lead decision, 2026-09-27 — F38 spec, Context decision 3): no NAT gateway, per proposal § A.2.1. The backend tasks and the database each run in a single Availability Zone. The backend tasks run in a public subnet with a public IPv4 address, behind a security group that admits traffic only from the load balancer’s security group, and reach AWS APIs (Bedrock, SES, Secrets Manager, ECR, SQS, KMS, CloudWatch Logs) over that address. The database sits in private subnets, is not publicly accessible, and admits only the tasks’ security group (and a rotation Lambda’s, if F38’s OQ-K chooses one). (Optional in development — F38 Rev 18: dev’s database is in the public subnets, not publicly accessible, with port 5432 open inside the VPC.) This is the cheapest shape that keeps §A.2.1 — a public IPv4 address is $0.005 an hour, against $0.01 an hour per Availability Zone for each interface endpoint (AWS list prices, us-east-1, read 2026-09-27). One consequence: anything that runs in the VPC without a public IP, such as a Secrets Manager rotation Lambda, needs its own interface endpoint (F38 spec FR-10, OQ-K).
  • Data: RDS PostgreSQL — single-AZ across all environments in the costed baseline, per proposal § A.2/A.5. This document previously said “Multi-AZ prod”, which the proposal does not fund: Multi-AZ is a priced add-on (+$30/mo, A.2.3) that the proposal recommends adding once the system carries real business, and it is the single most cost-effective availability improvement available. Adopting it changes the AZ-failure recovery target from 1–2 hours to under five minutes, automatic. Flyway-managed migrations run as part of deploy.
  • Backup & recovery: fully specified in proposal § A.5 — RDS automated backups with point-in-time recovery at 5-minute granularity, retained 14 days production / 3 days development (development’s optional since Rev 58), daily snapshots, S3 versioning on attachments, and a documented restore rehearsal before go-live plus a quarterly restore test thereafter. Recovery targets: 5 min data loss / 1–2 hr restore for user error or AZ failure; ≤24 hr / 4–8 hr for loss of the region, if cross-region copy is enabled. Empire Teas must confirm these targets are acceptable, since they follow from the single-AZ baseline.
  • Async: SQS standard queue feeding the worker; EventBridge Scheduler for all timed work. No separate message broker needed at this scale.
  • Storage: S3 for file attachments, versioned, access via signed URLs scoped to the requesting user’s record visibility; each file names its one record (attachment.owner_type and owner_id; entity-map D-6). Uploads are type- and size-validated, and recorded as not scanned while virus scanning is switched off in every environment (PRD Rev 58; Rev 52). A file is listed on its record from upload; one whose scan has not cleared (Being checked) or that a scan refused is listed and cannot be downloaded (FS-11 FR-D2; F33-a).
  • Secrets: AWS Secrets Manager holds the backend’s runtime secrets — DB credentials (managed by RDS and not rotated on a schedule; changed by hand with a redeploy when needed — Rev 61, F38 Rev 14; its automatic rotation is turned off in Terraform, in dev since F38-b’s forge-et-iaac#3 was applied on 2026-10-20), the Entra certificate private key for that environment — production has its own, and dev and UAT share one non-prod key (the sole login provider — AD #28; Empire’s tenant blocks client secrets, so login signs with a certificate — environments-and-identity.md §2.3), and the session-encryption key — injected as task-definition secrets references (valueFrom), so values never appear in git, images, task-definition JSON, or the console. AWS-service access uses the task IAM role — no static access keys anywhere. No Anthropic API key exists in this account — the AI layer authenticates to Bedrock via that same task role (AD #19); the evaluation keys for the one-time provider comparison are Altrium-held and never deployed. The frontends carry no secrets at all — build-time GitHub Actions variables inject only public config (the API base URL and, under AD #33, the CSRF cookie name for that environment). Connected-mailbox OAuth refresh tokens are envelope-encrypted at rest in Postgres (not Secrets Manager — those are per-user, not per-deployment).
  • Infrastructure as code (AD #23): every AWS resource is Terraform-managed — environment-parameterized modules instantiated per account, state in S3 locked by S3’s own lock file (use_lockfile; no DynamoDB table — AD #23, revised 2026-10-02), living in its own repository, forge-et-iaac, where DevOps does all the infrastructure work (AD #23’s location, revised 2026-09-29 from forge-et-be/terraform/). This is what makes the per-round temporary UAT environment practical rather than a promise: the Phase 1 UAT round runs while Phase 2 builds in dev (so dev cannot host it), and production would need a test-data purge before real go-live data arrives (so it shouldn’t) — instead a terraform apply of a uat instance on the production shape is seeded for Phase 1’s round, handed to the client, kept through Phase 2’s round, and terraform destroyed after it (AD #23, revised 2026-11-18).
  • CI/CD (GitHub Actions): two deploy shapes. Backend: build → test → dependency-vulnerability scan (Trivy — AD #27) → container build → push to ECR → register a new task-definition revision → update the ECS service (rolling). Frontends: build the Vite bundle (build-time config from GitHub Actions repository variables/secrets — non-sensitive values only, the bundle is public) → aws s3 sync → CloudFront invalidation. Auto-deploy to development on merge to main; UAT and production deploy an annotated release tag (vX.Y.Z), never a branch — a manual promotion gate straight to production, with no staging tier to promote through (see the two-environment note above). UAT rounds deploy their tag to a temporary environment (or pre-go-live production), so build promotions never collide with an active acceptance window. Because a delivery phase may go live ahead of V1 sign-off, fixes to a live release are cut from that release’s release/vX.Y.Z branch and merged back to main — branching, tagging and protection rules in .claude/rules/git-conventions.md (AD #24). Per-repo workflows, triggers and the cross-cutting rules (CI’s AWS credentials, Environments, concurrency) are in §CI/CD Pipelines.
  • Observability: CloudWatch Logs (structured JSON) + CloudWatch Alarms for error-rate/latency; Micrometer Tracing stamps traceId/spanId into every log line (the correlation id on every request and its continuation across async and queue hops — coding-standards.md §8). Additionally alarmed: lapsed Graph subscriptions, AI spend against budget, queue depth and dead-letter arrivals, and failed scheduled jobs — each is a silent-failure mode where the feature stops working with no user-visible error. Alarm delivery: CloudWatch Alarms publish to an Amazon SNS topic that emails the delivery team — an alarm nobody hears is not an alarm. Which alarms each environment carries is decided per environment (the lead, 2026-10-23; F38 Rev 23). Dev has the topic and an EventBridge email when a backend deploy fails, and no alarm. UAT and production choose from the list above (F38-h, F38-i; .forge/owed.md). AI spend against budget is an AWS Budgets alert belonging to the billing owners. There is no span exporter and no frontend error destination in V1: a request is followed by its traceId in the logs (F38 W-9).

CI/CD Pipelines

GitHub Actions in every repo, wired at Foundation slice 4 (Build & CI). Branching, tagging and protection rules are in .claude/rules/git-conventions.md (AD #24); this section is what runs.

Bootstrapped ahead of Foundation: each app repo carries pr-validation.yml with both §7.1 lane jobs, Fast lane and Slow lane (their history is in Revs 55 and 56). The pr-validation rows below describe the content those jobs run; a job name never changes without the ruleset changing with it (release-and-branch-protection.md § Branch protection rulesets lists the required checks).

The two artifacts promote differently, and that shapes the workflows. The backend image is environment-agnostic — one image and one application.yml, with every per-environment value supplied by the task definition (§Deployment Topology > Compute), so the same image that ran in dev is the one promoted to production. The frontend and capture bundles are not: Vite bakes build-time config into the bundle at build time (AD #22), so a UAT bundle and a production bundle are different artifacts built from the same commit. A frontend build is therefore always per-environment, and a single deploy workflow parameterised across environments would be a correctness hazard, not just untidy.

Per repo

forge-et-be

Workflow Trigger Runs
pr-validation every PR (any base — hotfix PRs to release/* included) · push → release/* · weekly on main, Sunday 19:30 UTC (skipped when main has not moved; kept to refresh main’s caches) · on demand (on main, -f tests=false runs the Fast lane only) Fast lane: compile, lint, the source checks. Slow lane — ./gradlew build -x spotlessCheck (Spock T1+T2) — runs on demand only, and is skipped on a push to release/* and on the weekly run (a suite runs in one place: every night on the lead’s Mac, and in the local records, .forge/design/harness/test-run-cost.md N-3, N-5) and on every PR, a Dependabot PR included, whose local build record — the required Test record commit status — stands in for it (coding-standards §7.1) · ArchUnit hygiene guards (web → service → repository layering, feature-package acyclicity, @NullMarked presence, no schema qualifier, fixture reachability) · Flyway migration validation · Trivy dependency scan (HIGH/CRITICAL ≡ CVSS ≥ 7.0, report-only: it never fails a PR or a dev deploy; a UAT or production release stops on an open finding without an exception — AD #9/AD #27/AD #38). (FS-14 removed the former module-boundary, banned-vocabulary and cross-schema FK checks.)
deploy-dev push → main · manual workflow_dispatch Build image → ECR → register task-definition revision → ECS rolling update. The manual trigger re-deploys dev without an empty commit — same artifact flow, no special path
deploy-prod — built by F38-i (tracked in Phase 1); not built yet manual workflow_dispatch on a release tag with no -rc<N> suffix, by a named deployer; pushing a tag deploys nothing (Rev 81; F38-i decisions 2 and 5 — the tag-push trigger first designed here would have sent Phase 1’s v0.1.0 to production) (Rev 82: the push of a plain vX.Y.Z tag (v*, not v*-rc*), a trigger added on the day production is created; every UAT candidate is an -rc tag, so a plain tag means production — F38-i decisions 12, 19, 32; the image is read from dev with dev’s svc-github key, decision 20) Copies the image dev built for the tagged commit, by digest, from dev’s crm/backend (with a dev-account pull user Rev 82: with dev’s svc-github key) into production’s own repository, never rebuilding (F38 NFR-4); the release vulnerability check first (AD #38); then deploys it behind the production Environment and waits for a stable service, failing the run on a rollback (F38-i FR-6)
deploy-uat — built by F38-h manual workflow_dispatch with a required release tag (Rev 82: the push of a vX.Y.Z-rc<N> tag; it stops at its first step while no UAT environment is applied — F38-i decision 32) (§ UAT deploys are deferred, deliberately) Promotes the image built for the tagged commit, never rebuilding; the release vulnerability check first (AD #38)
terraform — moves to forge-et-iaac (AD #23 revised 2026-09-29; the backend repository will not carry it) PR in forge-et-iaac fmt -check, validate, plan posted to the PR; apply on merge behind an Environment approval (AD #23). Its exact shape is set with Shyamin Ayesh once his setup is finished

forge-et-fe

Workflow Trigger Runs
pr-validation every PR (any base) · push → release/* · weekly on main, Sunday 19:30 UTC (skipped when main has not moved; kept to refresh main’s caches) · on demand (on main, -f tests=false runs the Fast lane only) Typecheck · Biome (format + lint) · dependency-cruiser (the src/{app,features,ui,lib} folder rules — ui/lib leaves, features don’t import each other, only main/app reach app) · pnpm build · dependency scan (full toolchain: coding-standards.md §7), in the Fast lane job · Vitest in the Slow lane job, on demand only — skipped on a push to release/* and on the weekly run (a suite runs in one place: every night on the lead’s Mac, and in the local records, test-run-cost.md N-3, N-5), and on every PR, a Dependabot PR included, the job is skipped, and the local test record (pnpm test:record), the required Test record commit status, stands in for it (coding-standards §7.1; a PR into a wave branch needs neither) · last step of the Fast lane’s full run (if: steps.scope.outputs.full == 'true', so a draft skips it): the Browser gate: description check, which passes at once unless the PR’s base is release/* (Rev 83: a PR into main runs no browser gate; a workflow_dispatch or push run applies the same rule to each open PR on its commit), node scripts/browser-gate.mjs ci-check, which reads the PR’s current description with pull-requests: read and runs no browser — it passes on a Browser gate: passed line whose commit covers the head, a Browser gate: skipped — <reason> line, or a PR that changes no gate input (F40; the local gate is pnpm e2e:gate, test-strategy.md § Browsers & Viewports)
deploy-dev push → main · manual workflow_dispatch Vite build with the dev build-time config → aws s3 sync → CloudFront invalidation
deploy-prod — built by F38-i (tracked in Phase 1); not built yet manual workflow_dispatch on a release tag by a named deployer, after the backend’s run, as for the backend (Rev 81) (Rev 82: the push of a plain release tag, as for the backend; it waits up to 20 minutes for the backend to report the tag’s version and uploads no source maps — F38-i decisions 19, 22, 25) Vite build with the production build-time config → S3 sync → CloudFront invalidation, behind the production Environment, after the release vulnerability check (AD #38) and a check that the backend reports the tag’s version; no browser tier runs inside it — a person runs the smoke suite against production afterwards (Rev 81; F38-i FR-7, FR-12). The capture app’s deploy-prod has the same shape
deploy-uat — built by F38-h manual workflow_dispatch with a required release tag (Rev 82: the push of a vX.Y.Z-rc<N> tag — F38-i decision 32) Vite build of the tagged commit with the UAT build-time config → S3 sync → CloudFront invalidation, after the release vulnerability check; forge-et-fe’s run is dispatched after the backend’s and (Rev 82: starts with the backend’s on the tag push, waits for it, and) checks the backend’s version before it deploys; no browser tier runs inside it — a person runs the smoke suite against uat afterwards (Rev 72)

forge-et-pwa — the same workflows as the frontend, minus the module-boundary rule, plus service-worker and manifest validation on the build. Its Fast lane also ends, on its full run, with the same Browser gate: description check (node scripts/browser-gate.mjs ci-check), which runs no browser and passes at once unless the PR goes into release/*.

forge-et-harness — repo-hygiene.yml only (gitleaks secret scan, front-matter parse, tracker.yaml parse, shellcheck, the doc-site and reference-graph generators running clean). No deploy target beyond the Cloudflare Pages dashboard build (.claude/lib/pages-build.sh).

How dev is deployed today (as built by the DevOps team, changed by F38-d; read 26 Oct 2026)

The tables above are the design. What runs on dev was built by the DevOps team ahead of F38-d, and differs from it in the places noted. Re-read the workflows with git -C ../<repo> log origin/<trunk> -- .github/workflows .aws before relying on this.

  • The four repositories never call each other. Each deploys its own part. They are joined only by fixed AWS names — Terraform creates the ECS cluster et-dev and service backend, the ECR repository crm/backend, the bucket et-dev-spa and the CRM’s CloudFront distribution, the bucket et-dev-capture and the capture app’s CloudFront distribution, and the app workflows have those names written into them — and by the one shared CI key, svc-github (F38 Rev 9).
  • Backend (forge-et-be build.yaml, jobs build and deploy, since F38-d’s forge-et-be#275 and #286): on a push to main that is not workflow-only, or by hand, the build job (no AWS credentials) builds the jar on the runner; the deploy job, on GitHub’s arm64 runner, builds the ARM64 runtime image around it, pushes it to ECR as crm/backend:build-<full sha> (or skips the build when ECR already holds that tag), writes the image’s digest into .aws/td.dev.json (the task definition lives in the backend repository, not in Terraform), registers a new task-definition revision and points the ECS service at it; ECS then starts the new task and stops the old one. Nothing goes through forge-et-iaac. Two things the dev deploy does not do (F38-d spec Rev 3, Rev 69 below): the job ends without waiting for the rollout, so a deploy that the ECS circuit breaker rolls back leaves the run green and dev on the previous task; and it runs no image scan, because ECR scans each image on push. Its commented-out release job for tags is still in the file (.forge/owed.md). Its build-* image tags are immutable since forge-et-iaac#6 (F38-d WI-3.1, applied 2026-10-23; environments-and-identity.md §4, “Checked against F38” row 8). The task definition carries every value register §D lists for dev — the attachments bucket, the mailbox key and ingest queue (forge-et-be#300), stopTimeout 60, JAVA_TOOL_OPTIONS and ET_DATASOURCE_SSL_MODE=verify-full (forge-et-be#306) — and the ECS circuit breaker rolls a task that cannot start back to the previous one, shown on dev on 2026-10-26 by two deliberate failed deploys (F38-d WI-6.1; environments-and-identity.md §4, “F38-d — the dev deploy pipelines, checked”, AC-2, AC-7 and AC-8).
  • CRM frontend (forge-et-fe build.yaml, jobs build and deploy, since F38-d’s forge-et-fe#298): on a push to main that is not workflow-only, or by hand, the build job (no AWS credentials) first checks that the dev build-time settings (VITE_API_BASE_URL, VITE_CSRF_COOKIE_NAME) are not blank, then builds and uploads the bundle as the artifact web-dist; the deploy job downloads it and uploads it to et-dev-spa in stages — the hashed assets first with a one-year immutable cache, then the other files and the HTML last with max-age=0, must-revalidate — removes files the build no longer has, and invalidates the CloudFront cache for /*. One deploy runs at a time (BUG-136).
  • Infrastructure (forge-et-iaac dev.yaml): creates and changes the AWS resources; it deploys no application code. Since F38-b’s forge-et-iaac#3 merged on 2026-10-20 (d230b133) it runs only on a push to dev or by hand, checks fmt, plans, and applies only on dev; a manual run on another branch only plans, and a branch pushed for review runs nothing. Unlike the design table above, it posts no plan to the PR and has no Environment approval: a reviewer plans a branch by hand before merging. Terraform’s ECS service names the task-definition family backend, so it follows whichever revision the backend pipeline registered last.
  • Capture app (forge-et-pwa build.yaml, jobs build and deploy, since F38-d wave 5, forge-et-pwa#91, first run 2026-10-25): on a push to main that is not workflow-only, or by hand, the build job (no AWS credentials) checks that the two dev build-time settings are not blank and builds the bundle; the deploy job uploads it to et-dev-capture in the same stages as the CRM (with manifest.webmanifest sent as application/manifest+json) and invalidates the capture app’s own CloudFront distribution.
  • No GitHub Environment has a branch rule in dev. For forge-et-be, forge-et-fe and forge-et-pwa that is decided (F38 Rev 18); forge-et-iaac’s is the DevOps team’s call (.forge/owed.md, “DevOps follow-ups…”). The app repos’ push triggers are trunk-only, and so is forge-et-iaac’s dev.yaml. A manual run can use any branch (forge-et-be, forge-et-fe, forge-et-pwa and forge-et-iaac have one; forge-et-iaac’s applies only on dev). UAT and production pipelines are not built (F38-h, F38-i).

Browser E2E runs in two post-deploy tiers (AD-O-11)

The full browser suite is not run on every merge. /forge-deliver already runs it live on the wave branch before the wave PR opens, so a merge-time repeat tests the same commit twice. Two tiers cover what a local run structurally cannot — cross-wave integration on main, and deployed-environment failures — both with their suites in forge-et-fe:

Tier Trigger Scope Target
Smoke after each deploy-dev finishes, run by hand from the machine of the delivery-team member whose merge or manual dispatch started it — no CI job (F38-g) Login plus one critical path per pipeline; budget under 5 minutes The development environment
Full suite inside deploy-prod once F38-i builds it, before the environment is released, if F38-i decides how it signs in (F38 OQ-D). Not inside deploy-uat (Rev 72) or deploy-prod (Rev 81): the suite depends on the local seed and the stub login, so UAT and production each get a smoke run by hand after the deploys (production’s with a role that reaches no records — F38-i FR-12), and the release track’s regression cycle on UAT is the full check The whole T-E2E suite + @axe-core/playwright scans The deploy’s own environment (Rev 81: none — the tier runs in no deploy)

The tag-time full run is the one that matters most: it verifies the exact artifact the client is about to test, which is the last point a regression is cheap to catch. (Rev 81: no tag-time full run exists — neither deploy-uat nor deploy-prod runs a browser tier; the release track’s regression cycle on UAT checks the assembled product before a release reaches production.)

The smoke tier is run by hand, not in CI (the lead, 2026-10-19; F38 Rev 21). It signs in through Microsoft as a test account, which a person does in a browser the smoke command opens; the saved session is deleted when the run ends. Dev deploys about nine times a working day, so a CI smoke run would have cost about 800 billed Actions minutes a month with a browser and a password held as a CI secret, or about 200 as an HTTP-only check with no sign-in; the manual run costs none. A failing run is raised as a bug and dev is fixed before new work merges (F38-g spec FR-3).

The smoke tier must be read-mostly. It runs against the shared development environment while developers are using it, so it creates only uniquely-named records and cleans them up. It must never reseed — test-strategy.md § Test Data & Isolation requires E2E to reset and reseed between files, and that behaviour is incompatible with a shared environment mid-workday. Write the smoke specs to that constraint rather than reusing wave-scoped specs unchanged. F38-g goes further: its smoke account’s role holds only view keys (and all keys that widen them), so the tier cannot write at all.

A nightly full run in CI was considered and deliberately dropped: it duplicates the tag run without adding a distinct failure class, and GitHub Actions minutes come from an org-wide shared pool. The nightly full run of all three app repos runs off CI instead, on the lead’s Mac (.forge/design/harness/test-run-cost.md N-3, Rev 78).

The browser matrix runs every night on main, on the lead’s Mac (F40, Rev 83; PRD Rev 81): the nightly full run runs pnpm e2e:gate’s full profile in both frontends. A PR into main runs no browser gate; a forge-et-fe or forge-et-pwa PR into release/* runs it on the developer’s machine before it is ready, and the Fast lane’s last step reads its Browser gate: line from the PR description. AD-O-11’s two tiers above are unchanged.

UAT deploys are deferred, deliberately

There is no deploy-uat workflow until the first UAT round needs one. The UAT environment is temporary — a terraform apply/destroy of the uat instance, one instance kept from Phase 1’s acceptance round to the end of Phase 2’s (AD #23) — so a standing workflow would point at infrastructure that does not exist for most of the engagement.

F38-h builds deploy-uat before deploy-prod exists (F38-i, tracked in Phase 1), so it is written from the dev workflows as F38-d reviews them, not copied from deploy-prod. F38 FR-35 sets its shape: a manual run with a required release tag, because the Phase 1 candidate v0.1.0 has no -rc suffix and no tag pattern separates a UAT release from a production one (Rev 82: the push of a vX.Y.Z-rc<N> tag, since every UAT candidate is an -rc tag; an existing tag is redeployed to a freshly applied instance by re-running its workflow run); the backend image already in ECR for the tagged commit is promoted, never rebuilt, and a commit with no image stops the run; the release vulnerability check (AD #38) runs before anything is deployed. In Phase 1’s round deploy-uat exists in forge-et-be, forge-et-fe and forge-et-pwa (the capture app’s, since 2026-11-19 — F38-h FR-13, Rev 92), and forge-et-fe’s run, dispatched after the backend’s (Rev 82: started with the backend’s, waiting up to 20 minutes for it), checks that the backend reports the tag’s version before it deploys (Rev 92: and, once forge-et-fe#582 merges, that the capture app does too). No browser tier runs inside it: a person runs the smoke suite against uat after the deploys, and the release track’s regression cycle is the full check (Rev 72; F38 Rev 24). deploy-prod is kept apart from deploy-uat the same way: it too is started by manual dispatch, on a release tag with no -rc<N> suffix, under the production Environment (Rev 81; F38-i decision 2). (Rev 82: the tag format now keeps them apart, and pushing the tag deploys: vX.Y.Z-rc<N> to UAT, a plain vX.Y.Z to production; every UAT candidate, Phase 1’s included, is an -rc tag, which settles the “no tag pattern separates” problem this paragraph describes; merging to main deploys dev and a branch deploys nothing — F38-i decision 32.)

Settle-by: before the Phase 1 UAT round opens (Mon 30 Nov 2026; it was 2 Nov before the 2026-09-29 schedule revision). Creating it is a task in that round’s setup, not a discovery.

Cross-cutting

  • AWS access by an IAM service user per workload account, with its access key held as a GitHub secret (Rev 50 — Shyamin Ayesh’s setup, replacing GitHub OIDC roles). A deploy user serves the app repositories, with only the deploy permissions; a Terraform user serves forge-et-iaac, and the app repositories never hold its key. Neither has a console password or is used by a person. The keys are created outside Terraform so they never enter the state, are held in the app repositories as secrets of the GitHub Environment that guards the deploy job (never repository-wide), and are rotated at least every 90 days (in dev the shared svc-github key only if it may have leaked — F38 Rev 18). People and the backend still have no static keys (Identity Center and the task role — AD #22). F38 FR-19 is the requirement. Dev exception (Rev 58, F38 Rev 9 and Rev 11): in the dev account one administrator user, svc-github, serves forge-et-iaac, forge-et-be and forge-et-fe, and the team reaches dev through svc-harness’s access key (MFA on its console password optional) instead of personal logins; UAT and production follow the rule above.
  • GitHub Environments — dev and production (plus uat when it exists). The “manual promotion gate” in §Deployment Topology is implemented by three settings, not a convention (Rev 81; F38-i decision 5): production admits only v* tags; the first step of every deploy-prod run stops unless github.actor and github.triggering_actor are named deployers, a list held as a production Environment variable; and a v* tag ruleset in each app repo lets only those deployers create, move or delete a release tag. The organisation’s GitHub Team plan offers no required reviewers on a private repository, so no second person’s approval is enforced. (Rev 82: the named-deployer check and the tag ruleset are removed; the gate is the tag format and each Environment’s ref rule — production admits only v* tags, uat only -rc tags — and anyone with write access may push a tag; the lead accepts that a writer could reach the production key — F38-i decisions 19, 21, 32.)
  • Concurrency groups per environment, and deploys are never cancelled mid-flight — validation workflows set cancel-in-progress: true (a superseded PR run is waste), deploy workflows set it false: cancelling a half-finished deploy leaves a half-synced bucket or a half-rolled service, which is worse than finishing and deploying again.
  • Build-time config is public. Frontend values come from GitHub Actions repository variables/secrets and are baked into a bundle any user can read — non-sensitive values only (AD #22). Backend runtime secrets stay in Secrets Manager, referenced by the task definition.
  • Frontend deploy jobs assert their build-time config before building. A missing or renamed Actions variable evaluates to the empty string — not an error — and Vite inlines it, so the build succeeds and the failure surfaces only in the browser after deploy. Every frontend deploy job therefore runs a guard step that checks each required VITE_* value is non-empty (whitespace-stripped) and exits non-zero otherwise, with the values declared once at job level so the guard and the build read the same expressions and cannot drift.
  • Staged S3 sync for the static bundles: hashed assets first with max-age=31536000, immutable, then other static files, then HTML last with max-age=0, must-revalidate; none of these steps deletes. Uploading HTML last closes the window where a live page references hashed assets that have not landed yet. A final aws s3 sync dist/ <bucket> --delete --size-only then removes what the build no longer has: a filtered sync --delete deletes only what its filter includes, and --size-only re-uploads nothing, so no object loses its header (BUG-136). The deploy runs in a concurrency group that never cancels a run, so one deploy’s prune cannot delete the assets of another’s HTML. The other static files are the ones Vite copies from public/ without a content hash (the favicons, the touch icon, the capture app’s install icons, manifest.webmanifest, sw.js), so they keep their names across releases and must never be immutable: give them max-age=0, must-revalidate, like the HTML, or a changed icon stays in browsers’ caches for a year.
  • Build and deploy are separate jobs, joined by an artifact. The build job (which runs package-manager lifecycle scripts — the supply-chain surface) holds no AWS credentials; only the deploy job that downloads the built artifact does.
  • Deploy triggers carry paths-ignore: .github/workflows/** — a CI-config-only change should not redeploy an environment.
  • Every checkout sets persist-credentials: false unless a later step genuinely pushes; every job declares timeout-minutes (coding-standards.md §7 principle 8).
  • Actions are pinned to the current major at authoring time — the majors the app repos’ workflows already use (read the uses: lines in any app repo’s .github/workflows/pr-validation.yml on main; as of 2026-10-26 they include actions/checkout@v7, actions/setup-node@v7 and actions/setup-java@v6). Don’t author a new workflow against an older major; after authoring, Dependabot’s github-actions ecosystem (coding-standards.md §7.7) keeps the pins moving.
  • PR-validation jobs upload their test/report outputs as artifacts (if: always()) so a red check is diagnosable from the run page without a local re-run.
  • Required status checks are live from the bootstrap (Repo hygiene on the harness; Fast lane, Slow lane, Test record (the local record’s status) and Forge review (the review record’s status) in all three app repos — git-conventions.md § Branch Protection). Slice 4 fills in what the lanes run; it no longer needs to touch the rulesets.

Cross-Cutting Concerns

AuthN / AuthZ

  • Login: Spring Security with one credential path feeding one User entity — Microsoft (Entra ID) OAuth2 login only (AD #28, refining AD #5: Google and local email/password dropped 2026-09-04 — Empire is all-M365 per OQ-24, so every user holds an account; Entra owns credential security and MFA) — server-side sessions via Spring Session JDBC on the same Postgres instance (no Redis needed at 10–20 users; revisit if session-store latency becomes a measured problem). The local/test profiles authenticate via a profile-scoped stub (coding-standards §5), so development needs no Entra registration; further providers are additive-only via client registration + change request.
  • Roles — six recommended, none predefined (PRD §Users and Access, confirmed 2026-08-03; AD #34, 2026-09-24): Sales Rep, Sales Manager, R&D/Sample Owner (Taster), Administrator, Tea Room (Pricing), and Executive/Management (read-only), plus a Managing Director role for sub-floor approval (OQ-40). These are the recommended day-one set, which Empire’s administrator builds from the catalog; nothing but the IT Admin role (below) is seeded. The Managing Director’s approval is the quote.approve_sub_floor key, held by that role by configuration; no code stops the administrator granting it elsewhere, and the grant is audited (AD #34, AD #36).
  • Users (AD #34, refining AD #5 and AD #28’s login half). Sign-in succeeds only when the Microsoft-verified email matches exactly one active, pre-created app_user; there is no auto-provisioning and no invitation email — a holder of settings.users.manage (AD #41) creates the user first, with their one role. Changing a user’s email clears their Microsoft identity link, so the next sign-in re-links by the new address. Users are deactivated and reactivated, never deleted. Deactivation ends the user’s sessions at once: the service deletes the user’s Spring Session JDBC rows through the principal-name index (Spring Session’s FindByIndexNameSessionRepository), so their next request is answered 401, and future sign-ins are refused. Deactivation is refused for oneself, for the last active user holding both settings.users.manage and settings.roles.manage (AD #41), while the user has direct reports (re-parent them first), and while the user owns any lead, account, deal, quote or sample (reassign them first) — the self and last-admin guards by F5-k, the direct-reports and owned-records refusals, the session end and the mailbox release by F5-c. Deactivated users stay in the reporting tree. In-app deactivation is the offboarding control; there is no Entra sync in V1, and Empire disabling the Entra account is a backstop (Microsoft then refuses the sign-in before it reaches the CRM).
  • The permission model — a minimal catalog, configured roles (AD #34, refining AD #30 and AD #32; AD #15 and AD #26 stand). Each module declares its permission keys as code constants; the database stores only (role, permission_key) grants — no scope since AD #37 (the scope column FS-6 shipped is dropped by F5-l). The catalog is minimal: per business entity <entity>.view (read-only) and <entity>.manage (create, edit and every action on it — share, remove a share, reassign the owner, AI-assisted drafting), where manage implies view; plus a short list of special keys — price.publish, quote.approve_sub_floor; each Settings page has its own unscoped key (AD #41, 2026-10-30): settings.users.manage (users, managers, offboarding), settings.roles.manage, and one each for account tags, contact tags, lead tags and email templates; administration is the Users and Roles keys together. Before AD #41 they were one settings.manage, which opened every page of the CRM’s Settings page (AD #34 refined 2026-10-26, signed off by Tharinda, 2026-10-27: it absorbed the separate access.manage, and the migration forge-et-be V54 (forge-et-be#319) moves every access.manage grant onto it), and a user’s own mailbox is email.manage (no role can read another person’s mailbox, as a fixed rule). There is no category axis (the client’s OQ-47 levels are met by view / manage plus the special keys), no AI level (AI the system runs on its own is not a permission; AI a user invokes is covered by the manage or email.manage key it assists), and no key for dashboards, search, tasks, reading reference data or exports, which follow the entity keys. The keys are listed in FS-6 Appendix A. No predefined roles: no templates, no superadmin, no non-deletable system role, no * wildcard grant; a role is renamed by its display name (its generated key never changes), re-permissioned, and deleted only while no user — active or deactivated — holds it. Each user holds exactly one role. The first administrator comes from a migration: one Flyway migration seeds, in every environment, an editable IT Admin role holding the administration key (settings.manage since V54) and one active user holding it; the user’s email is a Flyway placeholder set per environment — the crm01@empire.lk test mailbox on laptops, dev and UAT, and in production the address Empire confirms, a plain task-definition value in td.prod.json (AD #40; built by F5-k, which retires the runtime first-administrator job; .forge/cloud-gated-validation.md §B F5-k). Reach comes from the reporting hierarchy, with no scope to set (AD #37): a key on an entity that has an owner reaches the records owned by, or shared with, the user or anyone below them (app_user.manager_id, a nullable self-reference), and each such entity’s <entity>.all key widens the holder’s view or manage to every record; the full rule, with shares, is the ownership bullet below. (Until AD #37 each grant carried own / team / all.) Still not a flat authority check — every check names a permission key, and who holds it is configuration (AD #26). Consequences the model carries: new keys ship un-granted (fail closed), so “update roles” is a release step; a renamed key orphans grants, so an orphan-grant check runs at startup; and at least one active user always holds settings.manage — deactivating a holder, changing a holder’s role, editing a role to drop the key, and deleting a role are each refused when they would leave none (the last admin may move to another role that also holds it). Self-escalation is unlimited and no separation of duties is coded; the audit trail (§ Audit trail, AD #36) is the control.
  • Permission changes take effect on the next request (AD #34). The backend re-reads the user’s grants on every request — there is no grant cache — so a role or permission change applies to the affected users’ very next request, with no forced sign-out. The frontend re-reads GET /api/v1/me after any 403 and when the window regains focus, so the navigation and the permission guard catch up without a reload (design/ui/design-system.md §9). Only deactivation ends sessions.
  • Ownership, sharing and one visibility rule (AD #35). Each lead, account, deal and quote has one owner (owner_id, NOT NULL except on leads, where it is nullable only for import edge cases) and can be shared through one record_share table (one nullable foreign key per record type, exactly one set; shared-with, shared-by, shared-at; unique per record and user). Reach (AD #37 as refining AD #35): by default = records owned by, or shared with, me or anyone below me in the reporting tree, all levels down (shares roll up to managers) — for a user with nobody below them, the records they own or that are shared with them; with the entity’s all key = every record, unowned ones included — so an unowned record is visible only to all-key holders. A user acts on a record only when their role holds the needed key and the record is in reach: a share widens reach, never authority. Sharing is transitive; sharing, removing a share and reassigning the owner need the entity’s manage; the share picker offers only active users whose role holds the entity’s view key and who do not already reach the record. Children — contacts, notes, tasks, attachments, the timeline and record-linked email — follow their parent record’s reach. One visibility rule (the reporting tree, the all key and shares), exposed through auth.access, serves both the list queries and the per-record checks, so a list and a record page can never disagree; it is built once by F5-f, before any lead, account or deal list read-path, on the scope-free grants F5-l delivers. Design record: .forge/design/data/record-sharing-model.md.
  • A minimal user directory — every active user’s display name and role name — is readable by any signed-in user, for the pickers that need people (share, owner, “reports to”). The administration user list, with everything else about a user, stays behind settings.users.manage. Built by F5-f.
  • Enforcement is at the service layer, not just route guards — critical for the quote gross-profit-floor gate and for the surfaces gated by the Settings pages’ keys (AD #41), buying_standard.manage and price.publish.

CSRF and session hardening

Session cookies are sent automatically by browsers, so a cookie-authenticated API requires CSRF protection — a direct consequence of AD #5 (sessions over JWT). Spring Security’s CSRF token repository must be explicitly wired for the SPA case: the SESSION cookie is HttpOnly, SameSite=Lax and Secure; the XSRF-TOKEN cookie is SameSite=Lax and Secure but deliberately not HttpOnly (CookieCsrfTokenRepository.withHttpOnlyFalse()), because the SPA must read it to echo X-XSRF-TOKEN. Because the apps call the backend cross-site (AD #33), the XSRF-TOKEN cookie also carries Domain= the environment’s CRM host and a name that differs per environment — built by F5-j. Expired session rows are reaped on a schedule. Deactivating a user deletes that user’s session rows through Spring Session’s principal-name index, so an open session ends at once rather than surviving until it expires (AD #34, F5-c); a role or permission change ends no session, because the grants are re-read on every request (§ AuthN / AuthZ).

Mailbox integration (separate from login OAuth)

  • Microsoft Graph is the only mailbox integration in V1 scope. This is a commercial boundary, not just a technical one: project-proposal.md names Microsoft 365 exclusively — §4 (“integration with Microsoft 365”), the §9 architecture diagram, §Client Obligations (“each user connects their own Microsoft 365 mailbox”), and the Appendix A third-party-services table (“Mail, calendar, and contact synchronisation via Microsoft Graph”). Gmail, Exchange-on-prem (EWS) and raw IMAP appear nowhere in the proposal and were never quoted.
  • Gmail, EWS and IMAP are out of V1 scope. Adding any of them is a change request, and for EWS/IMAP specifically it also requires re-scoping SP-ARCH-002 (stood down when OQ-24 confirmed no Empire user is on them) since their sync mechanics — poll-only, no push, non-OAuth auth — were never established.
  • Mailbox access sits behind a MailboxProvider seam — the same pattern as AIProvider (AD #6) and ErpHandoffService (AD #10). Graph is the single implementation in V1. A future provider is a new implementation behind the seam, not a redesign of F20’s call sites. This is why keeping the others out of scope costs nothing architecturally.
  • Each user separately grants mailbox/calendar/contact scopes — login OAuth and Graph consent are different grants with different scopes (AD #28 makes login Microsoft too, but the mailbox consent is still its own grant; since 2026-10-17 the backend runs it straight after sign-in, so the user presses nothing — see the sign-in bullet below). Refresh tokens stored envelope-encrypted, scoped per user. (Client dependency: client/dependencies.md row 4 — one-time admin consent + the test accounts; the provisioned account set is listed in design/environments-and-identity.md §5, which is the authoritative source. The register’s one preferred date for everything is Fri 4 Sep.)
  • Mailboxes are per-user only — no shared mailbox connection in V1 (lead decision, 2026-09-24). info@empire.lk stays an inbound channel (OQ-14), but V1 brings it in by forwarding: whoever reads info@ forwards an inquiry to a rep, the rep’s own synced mailbox brings it into the CRM, and the rep creates the lead by hand or with F12’s extraction. Nothing is built for it, and there is no unowned MailboxConnection, no shared-inbox assignment rule and no separate rate-limiter entry. The shared inquiries inbox (F20-e) has left V1; its stub spec is kept as the record of what was considered. If Empire wants, info@ can be added as an ordinary CRM user — also nothing to build — provided it is a licensed mailbox that can sign in to Microsoft itself, and on the understanding that its actions are recorded as info@, not as the person. The mailbox_connection owner column shipped nullable (F20-a) for the shared inbox; no V1 row needs the null now, and whether to make the column NOT NULL is an open schema question (schema changes are ASK FIRST). This section described a per-user-plus-shared model, with info@ as an unowned connection, until 2026-09-24.
  • Subscription renewal is mandatory. Microsoft Graph mail subscriptions expire in at most seven days — Microsoft documents the ceiling for Outlook message, event and contact subscriptions as 10,080 minutes, and F20-a pins it as MailboxSubscriptions.MAXIMUM_EXPIRY (a subscription carrying resource data is capped far lower, at 1,440 minutes; F20 requests none). This line read “~3 days” until 2026-09-23; F20-a established the real figure from Microsoft’s documentation on 2026-09-22 and the correction was not written back, so F20-b’s spec reproduced the wrong number until its review caught it. Cite the constant, not this sentence, for anything that computes a renewal cadence. A scheduled renewal job keeps them alive, and a lapsed-subscription alarm exists because the failure is silent — sync simply stops with no error surfaced to the rep.
  • Reconciliation poll: a periodic delta query per mailbox catches anything a missed webhook dropped. Push is the primary path; polling is the safety net, not the mechanism.
  • The CRM stores only email linked to a record, and stores it in full (lead decision, 2026-10-17; built by F20-i (the live inbox), F20-f (linking), F20-j (past mail) and F20-k (block lists), which revise F20-b). The inbox is read live from Microsoft, a page at a time (the page size is a setting in application.yml, 50 by default and at most 100), newest first, and an email nobody links is never written to the database. It shows the user’s Inbox, Sent Items, Archive and their own folders and subfolders; Drafts, Junk Email and Deleted Items stay out, as in F20-b; each message shows its Outlook categories, which can also filter the list. Linking is automatic and manual: each new message’s sender and recipients are checked against the addresses of leads and contacts, and an account is reached through its contacts (an account holds no address, so it is not matched by its website’s domain — F20-f D-2), and a reply in a thread already linked follows the thread; a user can link any message from the inbox (a new buyer’s first inquiry, an info@ inquiry forwarded by a colleague, a colleague’s email about a record). A lead or contact created later has its past mail with that address fetched and linked from every connected mailbox, by a background job on the queue (AD #7, AD #13), going back a period set in application.yml (12 months by default) — the same rule auto-linking applies to new mail, so a record’s history does not depend on who created it. The same past-mail link runs from the mailbox side: when a mailbox connects (first connect and reconnect), a background job reads the headers of that mailbox’s mail for the same period and links every message whose sender or recipient matches a lead or a contact (an account through its contacts — F20-f D-2); a bulk import (the Pipedrive migration, or a spreadsheet import) runs that scan once per connected mailbox against the imported addresses, rather than one search per record. Each message keeps its Microsoft id, so linking it again changes nothing. The scan is kept simple on purpose (the lead, 2026-10-17): every connect and reconnect scans the whole period rather than only the gap since a disconnect, because the cost is small — the scan reads headers only (sender, recipients, date, thread), about 20 requests for a year of a busy mailbox, and a message already linked is skipped, so a reconnect fetches only the bodies and attachments of new matches. The job pages through the mailbox resumably, fetches matched bodies in Graph JSON batches, yields to the live inbox within Graph’s four concurrent requests per mailbox, backs off on a 429, and skips attachments above the size limit (linking the message and noting the skipped file). Linked past mail writes timeline rows dated at the message’s own sent or received time, so Last contact and dormancy read it correctly. A linked email is stored whole — headers, body, its attachments (in S3 under the email-attachments/ prefix, each recorded in F20-f’s own email_attachment table, not FS-11’s attachment table, with a size limit — F20-f D-6) and the records it is linked to (F20-f D-1) — because everyone who reaches the record must be able to read it (AD #35), while Microsoft lets only the mailbox owner read their mailbox (F20-a’s scopes are delegated, on the owner’s behalf), and the owner’s connection ends on disconnect or deactivation. Users and the administrator can block addresses and domains so their mail is never linked (F20-k): each user on their own list, for their own mailbox, under email.manage, and the administrator on one list for every mailbox, on its own Settings page under settings.email_block_list.manage (AD #41). A block works per address: a blocked address never causes an automatic link, an email is still linked through its other, unblocked addresses, a thread reply whose outside participants are all blocked gets no thread link, and a link from a CRM send or made by hand is not affected. Nothing is deleted automatically (apart from F20-f’s one-time clear-out of the unlinked rows F20-b stored), and the CRM never deletes anything in Outlook. Unlinking a wrongly linked email removes the stored copy when no other record holds it, which is also the path for a data-protection deletion request; blocking an address applies to new mail only, and email already linked stays until someone unlinks it (the lead, 2026-11-20, F20-k D-5: a bulk removal of a blocked address’s past email was left out, as rarely needed — the organisation list is filled before the first mailbox scans instead). Linking needs the record’s manage and the email to be in the user’s own mailbox; unlinking needs the record’s manage.
  • The mailbox connects itself at sign-in (lead decision, 2026-10-17). When a user whose role holds email.manage signs in with no active connection, the backend sends the browser straight on through the microsoft-mailbox consent flow, which returns without a prompt because Empire’s admin consent covers every delegated permission (environments-and-identity.md §2.4); the user presses nothing for the first connect. It is built on F20-a’s connect flow, and F20-a’s mailbox screen (/email/mailbox) and its button are kept (lead decision, 2026-10-26, after Dinil Gamage asked on 2026-10-19 whether the button should stay): the button reads Try again after a failed automatic connect and Reconnect after a deliberate disconnect or when the connection needs reconnecting. Connecting at sign-in was kept over the button alone because a rep who never pressed it would have no mail linked and no past-mail scan of their mailbox (F20-j). A failed connect never affects sign-in: sign-in completes first, through its own registration with only openid profile email, and the session exists before the connect starts; the connect is a second step through the separate microsoft-mailbox registration, so when it fails the user stays signed in, lands in the CRM and sees Try again. Only the CRM starts the connect: the capture app signs in through the same backend (F36-a) and never starts the mailbox connect. A connection marked reconnect required is retried the same way on the next load of the CRM (once; a failure shows Try again, as below). A user who disconnects on purpose is not reconnected automatically, and offboarding still releases the connection (F20-a FR-7, FR-8). One connection, and one encrypted refresh token, serves mail, calendar and contacts: it asks for Mail.ReadWrite, Mail.Send, Calendars.ReadWrite and Contacts.ReadWrite from the first connect, so F21 and F22 need no reconnect. Sign-in and mailbox access keep separate lifetimes on purpose: the CRM session ends after 8 hours without activity, while the mailbox connection keeps working while the user is signed out, because linking new mail and the background jobs run without them; signing out never disconnects the mailbox. When the connection is checked, and the edge cases (lead decisions, 2026-10-17): the check runs whenever the CRM loads in the browser (after sign-in or a page refresh) and when the Email page opens, not only at sign-in, because a permission change applies on the user’s next request without a new sign-in (AD #34) — so a user given email.manage later is connected the next time they load the CRM, with no button. If the automatic connect fails (for example the account has no Exchange mailbox, or Microsoft needs a fresh sign-in the user abandons), the CRM shows a message with a Try again action and does not redirect again on every page load. Disconnect is kept, tucked away in the user’s settings: a deliberate disconnect is remembered and never undone automatically, and a Reconnect action in the same place and on the Email page reverses it. Losing the permission releases the connection: when the user’s role loses email.manage, or they move to a role without it, the connection is released as a disconnect is (tokens erased, notifications stopped), recorded as caused by the permission rather than by the user, and background jobs never use a connection whose owner lacks the permission; if the permission comes back, the next load connects again automatically. Deactivation releases the connection (F20-a FR-8) and a reactivated user is connected again at their next sign-in. In every case, email already linked to records stays. Whether a role holds email.manage stays configuration: the recommended role set gives it to the roles that write to buyers, not to every user (client/roles-and-permissions.md §4.4), because automatic linking would put, for example, an executive’s private exchanges with a buyer on records others can read.
  • A contact can hold several email addresses, and every one of them is matched (lead decision, 2026-10-26; a schema change, approved by the lead). A contact keeps one main address, contact.email, which is shown first and used for sending, and may hold other addresses; automatic linking (F20-f), the past-mail searches and scans (F20-j) and F11-d’s proposed contact match every address of a contact, and a blocked address is never linked even when a contact holds it (F20-k). The Pipedrive migration keeps every address in a person’s Email - Work and Email - Other cells instead of only the first (246 people in the export have several work addresses in one cell). F20-l builds the other addresses — the table, the contact API and screens, the change to the migration’s mapping (F4-a FR-M2, F4-d) and F11-d’s match — and its spec settles their detail; it lands before the first production run of the migration (.forge/owed.md). F22’s contact sync and F23-b’s spreadsheet import write several addresses the same way. Leads keep one address: the leads export has no email column, and a lead’s address is copied from its contact person’s main address (F4-a).
  • A lead’s email follows it when it converts (lead decision, 2026-10-26; built by F11-e, Phase 2). Converting a lead (entity map D-5) links every email linked to the lead to the account, contact and deal the conversion creates or matches as well — links to the one stored copy, not copies — and the lead keeps its own links. A lead with status converted is never a target of automatic linking, so later mail with that address links to the contact and account, and to the deal by the deal-linking rule F2-c settles.

Scheduling

Timed work runs via EventBridge Scheduler → SQS → worker, not via in-process @Scheduled. With more than one backend task running, @Scheduled fires on every task, producing duplicate alerts and duplicate outbound email. EventBridge enqueues once; one worker consumes.

Scheduled jobs built so far: Graph subscription renewal and the mailbox delta poll (F20-a, F20-b) · the email-upload cleanup (F20-h) · the weekly bulk-price expiry sweep (F26-g) · the lead-triage and lead-research sweeps (F11-d, F11-c). Still to come: the scheduled-email send sweep, every minute (F20-g — one sweep sends every email due, rather than one AWS schedule per email) · stale/rotting recomputation (F18/F24) · dormant-account detection (F18) · quote aging (F7). Spring Session’s expired-session cleanup is the one exception and stays in-process (AD #12; spring.session.jdbc.cleanup-cron in the backend’s application.yml).

(Alternative considered: @Scheduled + ShedLock database locking. EventBridge is preferred as it keeps the scheduling contract outside application code and is already in the AWS estate.)

Idempotency

SQS standard queues deliver at least once — the same message will occasionally be processed twice. Unhandled, this produces duplicate Email records on a deal, double-charged AI triage, and — worst — a sequence step sent to a buyer twice.

Every enqueued job therefore carries a stable idempotency key (e.g. Graph message id, lead:{id}:triage:{run}), and consumers record processed keys and no-op on replay. This is a design requirement for every consumer, not an optional hardening step. One variant is allowed for scheduled sweeps whose effect is idempotent by the state it leaves — a renewed subscription is no longer due, a closed price no longer matches: such a consumer may log its key instead of claiming it, because a replay finds nothing left to do (F20-b’s mailbox renewal; F26-g’s price-expiry sweep).

Rate limiting

A per-mailbox token-bucket limiter in the worker respects provider send/action limits (~40 actions/min/account, per the PRD’s Pipedrive-documented ceiling).

AI provenance, governance, resilience and cost

  • Every AI output is tagged with source + confidence and an “edited by you” flag once a human modifies it. Every AI action requires human approval before it sends or saves (the PRD’s locked governance invariant).
  • The AIProvider interface remains the single seam where a self-hosted model would swap in. Cloud Claude through Bedrock is accepted (2026-07-28; the data-handling arrangements were signed off with the accepted proposal, 2026-08-16; PRD Rev 12), so SP-ARCH-001 stands down; the seam is retained as a safeguard, not as an active investigation. OQ-15 was reopened on 2026-09-30 (PRD Rev 48) for one question only — where requests are processed — and settled on 2026-11-04 (PRD Rev 82): any commercial AWS Region is accepted (project-prd-history.md, ai-provider-strategy.md §4b).
  • Failure policy: the <10s NFR requires an explicit timeout, bounded retry with backoff, and a circuit breaker. Structured outputs are schema-validated; malformed responses retry once then fail cleanly. The UI degrades to the non-AI path — an AI outage must never block a rep from working manually.
  • Provider and model routing (decided 2026-08-18; full detail in ai-provider-strategy.md): all AI calls go to Claude served via Amazon Bedrock, called from the project’s own AWS account — one vendor relationship, one bill (AI usage lands on the AWS invoice; the client holds no separate AI accounts). Where a request is processed depends on the model’s inference profile: neither pinned model runs in-Region on bedrock-runtime; Haiku 4.5 uses its US-only us. profile for the calls a person waits for and Haiku 4.5’s Global profile for the background features (lead triage, lead research and, from F11-j, the summary of a migrated lead’s linked email, where the environment’s task definition sets it — F43, the lead’s direction of 2026-11-02), so each group has a request quota of its own; and Sonnet 5.5 uses the Global profile (ai-provider-strategy.md §4b). Processing in any commercial AWS Region is accepted (OQ-15, settled 2026-11-04, PRD Rev 82). There is no second-provider tier in V1: on failure the retry/circuit-breaker path degrades to the manual path (the standing contract above). The accepted trade-offs: Bedrock can lag brand-new model releases (models are pinned, so this bites only at upgrade time) and quotas need a raise request at account creation — which AWS refuses on a new account until it has a few billing cycles of usage and spend, so until AWS lifts those limits Haiku 4.5 runs every AI feature and the backend paces its Bedrock calls (ai-provider-strategy.md §5 row 10, 2026-10-26). The proposal’s A.3.1 comparison still runs, on anonymised inquiries via evaluation keys. Routing is runtime configuration, not code: each AI feature carries {model, enabled} (shape in coding-standards.md §5), so an administrator can re-point a feature’s model or disable it without a deployment — the per-feature toggle commitment below. A direct-API or second-vendor tier remains a config-level addition behind the AIProvider seam if ever wanted.
  • Cost control — the specific numbers are committed in proposal § A.3.2, not open: budget $50/month with a billing alert at $150. Required controls: per-feature toggles an administrator can switch off without a deployment; the cheaper model on every high-volume path by design; prompt caching on repeated instruction text; per-call logging of cost, tokens, latency and outcome so spend is attributable; and a configurable monthly ceiling that disables AI features rather than allowing an unbounded bill. Model routing (Haiku for high-volume/simple, Sonnet for complex synthesis) is a cost lever, not a cost control. The top tier (Opus) is deliberately unused — ~5× the cost for nothing this workload needs.
  • Provider comparison is a delivery commitment, not just a safeguard. proposal § A.3.1 commits Altrium to “a side-by-side quality comparison on real Empire Teas inquiries during Phase 1b” before the provider is locked, with Google Gemini priced as the named alternative (roughly one third of Claude’s cost per interaction). Architectural consequence: the AIProvider seam will actually be exercised with a second implementation during Phase 2 (the proposal’s Phase 1b), on anonymised inquiries via evaluation keys — it is not merely retained against an OQ-15 reversal. Build it to be genuinely swappable and keep prompt/response shapes provider-neutral behind the interface.

There is no global search: F31 was dropped on 2026-10-11 (PRD Rev 60), and AD-O-2 is closed with it. Each list endpoint carries its own q filter, a case-insensitive contains match over that entity’s own fields, read through the one visibility rule (FS-10 docs/api/; F1-b, F11-b). No tsvector column or search index is built.

API conventions

Pagination, filtering, sorting, error-envelope shape, and versioning are decided once in Foundation and documented in <backend-repo>/docs/api/. Every feature touches these; leaving them per-feature produces an inconsistent API surface that is expensive to unify later. Settled at FS-10: <backend-repo>/docs/api/README.md is the index and carries the adding-an-endpoint checklist; versioning.md, collections.md, errors.md and payloads.md state each rule and its why, with GET /api/v1/buying-standards (BuyingStandardController + BuyingStandardCollectionDefinition, com.empireteas.pricing.web) as the worked example every feature copies — it replaced the products example when FS-15 retired the product entity. The generated OpenAPI document is served by the application at /v3/api-docs.

Audit trail

One audit trail for the whole system (AD #36), built as F39 before the features that write. One append-only audit_event table and one small service record who acted (a user, or SYSTEM for background jobs), what they did, which record it concerns, when, and what changed — for every write, plus the security events: sign-in success and refusal, sign-out, deactivation and reactivation (with the sessions it ended), role and permission changes, sharing, share removal and owner reassignment, and exports. Reads are not recorded, and neither are changes to a user’s own mailbox state in Outlook other than a send — marking a message read or unread, creating or updating the CRM’s All-mail search folder in Outlook; a CRM write that follows such a change, such as recording the folder’s id, is still audited (AD #36, refined 2026-10-28; F20-i D-7). The event is written in the same transaction as the change, so the two commit or roll back together, and a failed audit write fails the change. Rows are kept indefinitely in V1, and there is no viewer screen in V1 — the trail is queried in the database. This covers everything the earlier text listed — stage moves, pricing and margin approvals, weekly price publications, pipeline and reference-data changes, custom-field definition changes and every AI-action approval — as ordinary writes. It is the control that makes unlimited self-escalation (AD #34) and transitive sharing (AD #35) acceptable. Separately, every table carries created_at / modified_at, and created_by / modified_by where a person makes the change; F39 checks every table on main and adds them where missing, and decides how the SYSTEM actor is represented against the created_by foreign key to app_user. Log-class tables reference records loosely (.forge/design/data/entity-map.md D-8).

Data protection and retention

Buyer contact data (including EU persons), commercial pricing/margins, and synced email content are confidential per the PRD. Retention per data class and the deletion-on-request path are specified in proposal § A.6.3 (AD-O-6 — closed); the remaining work is implementing the erasure path across threaded email, not deciding it.

Committed security baseline

Added 2026-08-06. proposal § A.4 commits a specific control set at the baseline cost — this document previously described security more thinly than what has been sold.

Included and costed: AWS Secrets Manager (the Entra certificate private keys — Empire’s tenant blocks client secrets, environments-and-identity.md §2.3 — and DB credentials, managed by RDS and changed by hand rather than on a schedule (Rev 61) — no AI credential exists; Bedrock authenticates via the task IAM role) · GuardDuty (threat detection across account activity, network flow, DNS) not enabled since 2026-10-09 (Rev 52) — a departure from proposal § A.4 that Empire Teas is told about · CloudTrail (immutable audit of every AWS API call, to a central archive; in development, AWS’s free 90-day event history only, Rev 60) · KMS (keys for database, storage, backups; in development only the storage and mailbox token keys, and the database is not encrypted at rest — Rev 64; production’s database encryption is undecided) · IAM Identity Center (SSO with MFA and time-limited roles — no long-lived keys for people; in development the team uses one shared access key instead, Rev 58) · Shield Standard · account isolation (development can never reach production data).

Standing controls: TLS 1.2+ in transit and encryption at rest · database not reachable from the public internet · S3 public access blocked at account level (in development, on each bucket instead, Rev 60) · least-privilege security groups · a UAT or production release stops on any open dependency CVE at CVSS ≥ 7.0, with written justification and an expiry for exceptions; PRs and dev deploys report findings without failing (AD #9, AD #38).

Priced add-ons, not in the baseline: WAF (recommended once the system carries real business), Security Hub, Config, Inspector.

A pre-go-live security review is a committed deliverable at no separate cost (proposal § A.4), covering authentication, session handling, permission enforcement, file upload, and the AI prompt boundary. Treat it as a release gate, not an optional recommendation.

AI data-handling boundary

Added 2026-08-06 from proposal § A.6.1–A.6.2 — these are client-facing commitments that constrain implementation.

Only the minimum a task needs leaves the system. Never sent: credentials or API keys · bulk database exports · payment, banking or letter-of-credit detail · any record outside the specific task. No blanket database upload ever occurs. Two kinds of call exist (AD #32): AI the system runs on its own — lead research, triage and ranking, the summary of a migrated lead from its linked email (F11-j), the morning briefing, duplicate/spam detection — runs as background jobs on that task’s minimum data (AD #32, PRD Rev 30; stated to the proposal as its 27 September 2026 post-issue note, which supersedes §A.6.1’s “only when a person triggers” sentence — for research, the company and contact name go to the search service, per the 16 September second note); AI a user invokes on a record — a draft, the account briefing (moved here from the system-run list on 2026-10-21, AD #32, PRD Rev 76), the quote assistant — runs only when that person triggers it. Either way no AI output is committed until a person acts on it. Calls are server-to-server over TLS 1.2+ (whether F38’s public-subnet tasks still meet the proposal’s “from the private network” is F38’s OQ-G), so the browser never contacts the AI service, and no AI credential exists outside the backend task role — there is nothing to leak to a user’s device.

This forbids one automatic trigger in V1: inquiry extraction on mail arrival. The PRD defers the automated inbound-email trigger, so F12 extracts only when a person asks, however tempting it is to fire extraction on arrival. The background jobs listed above are allowed.

Secrets, i18n, feature flags

  • Secrets: never committed; Secrets Manager + Postgres envelope encryption per above.
  • i18n: not built for V1 (English-only per PRD; multilingual AI deferred) — just keep user-facing strings out of business logic so it isn’t a rewrite later.
  • Feature flags: no external flag platform (in-house-first). AI features are switched per feature, not per role — the {model, enabled} runtime config (AD #19), edited on a Settings page under its own key once that page is built (AD #41); AI is not a grantable permission (AD #34). Any other staged-rollout flag is not built until a concrete need appears.

Weekly Bulk Pricing Subsystem (F26 / F7 / F14)

Added 2026-08-06 — this subsystem was confirmed in the PRD on 2026-08-03, after Gate 2 Run 1, and had no architectural treatment.

The priced unit for bulk tea is a client-specific Buying Standard — and since PRD Rev 27 (2026-09-15) the standard is also the sellable record for bulk and private label alike; there is no catalog product at all. This is the one part of the domain that introduces a modelling technique nothing else in the system needs, and it is the client’s stated priority.

Shape of the problem (PRD §Domain Model, §F26, confirmed OQ-33/37/38/39/40/42/43/44/45):

Property Consequence
A Buying Standard is client-specific, with a unique running number never reused across clients — and, since PRD Rev 27, the sellable record itself (there is no products catalog) BuyingStandard is an entity in its own right, N:1 Account, carrying grade / origin / brand / held certifications, cost and a create → edit → archive lifecycle (archive = is_active flip, history kept, out of quoting and the weekly round). The former N:1 Product/grade edge goes with the catalog — data-model §2 revision, Tharinda (AD #31)
Price changes weekly; one price per standard — it does not vary by customer or destination market (PRD Rev 23, 2026-09-11, revising OQ-38) Price is keyed on (buying_standard, validity) — an effective-dated record per standard, not a column on it; destination market stays a customer attribute and a quote field, never a price key. Before Rev 23 the key carried a market axis; data-model §2.2 has since been revised to drop it (owner: Tharinda, AD #31). Validity is anchored to a numbered auction_sale row, not to a calendar week — sale days shift week to week, so “the next auction” cannot be derived from a weekday or ISO week (SP-ARCH-003 §2.3)
Price history is retained Prices are effective-dated rows (valid_from / valid_to), never updated in place. Every price read is an as-of query
A published price holds until the next weekly Colombo auction, with manual override An expiry roll is a scheduled job; the override is an explicit, audited action
The quote shares that same clock Quote validity derives from the price’s validity — one clock, two consumers
Published price is FOB Colombo in USD; other currencies/Incoterms derive per quote Store one canonical price; derive presentation. Do not store per-currency price rows (OQ-43)
A weekly price is a four-figure build-up, kept whole (PRD Rev 31) The price row stores LKR → + overhead (LKR) → converted USD → + margin → final USD. Only the final USD figure is NOT NULL; the three working figures are nullable. This is not a second currency axis — USD is still the only published currency (OQ-43) — it is the working behind the one canonical price, kept so a past week is reconstructable and the margin is auditable at the figure the Tea Room set. Columns on the append-only row (AD #14), never a mutable side record
Per-standard cost is retained to compute gross profit at quote time Cost is effective-dated too, or margin history becomes unreconstructable
Private-label items are standards too (PRD Rev 27, revising OQ-37); whether they join the weekly round is OQ-61 The standards book serves both pipelines; the weekly-price workflow attaches to whichever standards are weekly-priced. Default until OQ-61 answers: bulk standards weekly, private-label standards priced on the quote — so F7’s unpriced-standard gate must not fire for them
The Tea Room sets and publishes prices — by configuration: publishing is the price.publish key, which the recommended Tea Room role holds (AD #34) Publication is a workflow with a draft→published transition, audited, not a plain edit

Architectural implications:

  • Effective-dated (temporal) modelling is the core technique. Every price and cost row carries a validity period; queries are always “the price for standard X as of date Z” (the market term left the key at PRD Rev 23). This must be established in the data model from the start — retrofitting temporality onto a mutable-row design means rewriting every read path.
  • Publication is a state transition, not an update. Draft prices are invisible to quoting; publishing makes a week’s prices live, stamps the validity window, and writes an audit entry. In-flight quotes retain the price they were built on. A person publishes; the weekly roll does not (F26-f spec D-1): publishing a round closes each replaced price at the new price’s start, never earlier than the day of publishing. A published price that has applied to no day before today can be withdrawn — a third state, withdrawn, kept as history with who, when and why (F26-f spec D-2); a price live since before today is corrected by the manual override.
  • Expiry is scheduled work (see §Scheduling) — a daily sweep (price-expiry-sweep, F26-g) ends, at each sale’s start (never before today), every published price of an earlier sale that no publish replaced, and marks a sale held after its last day; flagging dependent quotes is F7-c’s extension of it. The manual override (OQ-33’s exceptions) is two explicit, audited actions, neither of which makes the sweep skip a price: a price is carried forward by copying it into the new sale’s round as a draft, published with the round; and a price live since before today is corrected by closing it from a date of today or later and publishing corrected figures from that date, with the reason in override_reason (F26-g spec D-4). Warnings on the Pricing page cover a sale calendar that has run out, a round not published by its sale’s start, and a sweep that has stopped running (F26-g FR-14).
  • AuctionPriceProvider seam. A tea-auction public API is confirmed to exist (PRD §Integration Points, 2026-08-03) and is a scoped follow-on. It gets the same treatment as AIProvider and ErpHandoffService: a named interface with a no-op/manual implementation in V1, so the follow-on adds an implementation rather than reworking the pricing workflow. Auction data may only ever suggest a reference price to a human — it must never set a price, mirroring the AI governance invariant.
  • The data model is settled in <backend-repo>/docs/data-model.md §2 — SP-ARCH-003, resolved 2026-08-21, DDL verified against PostgreSQL 17 and re-verified unchanged on 18, the engine chosen for RDS (<backend-repo>/docs/proofs/pricing/; Rev 51). That document is authoritative for the schema; this section states design intent. .forge/discovery/research/bulk-tea-pricing.md remains the domain research input, but its §7 schema is superseded — read the reconciliation table in the data model, which enumerates exactly where, rather than the research DDL.

Core / Domain Separation

⚠️ HISTORICAL RECORD — the split was never extended (AD #29) and is now COLLAPSED (AD #31, 2026-09-09, Rev 32; FS-14). Everything below describes structure that no longer exists. AD #29 (2026-09-07) stopped extending the split — the reuse it was built for (OQ-50) was no longer expected, so FS-12 and FS-13 were dropped, the acceptance test was retired, and the scaffolding was kept only because removal seemed dearer than keeping. AD #31 reversed that last judgment: opened up, the scaffolding proved to be mostly empty shells and the substance moved rather than rewrote, so FS-14 removed it outright — the backend is now one Gradle module with feature-first packages com.empireteas.<capability>, one public schema, and one squashed V1… Flyway sequence; the frontend is one src/{app,features,ui,lib} package (the PWA mirrored with a shared-file drift check). The build-graph boundary, the module-boundary ArchUnit rules, the banned-vocabulary rule, the two-schema partition and the cross-schema FK check are gone; the hygiene guards (layering, feature-package acyclicity, @NullMarked, no schema qualifier, fixture reachability + leak) remain and one was added (feature-cycle). Read this entire section in the past tense, as the record of what was built, why, and that it was removed. F26’s data model (data-model.md §2, now one schema) is owned by Tharinda (AD #31). Live structure: coding-standards.md §1, test-strategy.md § Test Naming & Layout, and the FS-14 backlog row below.

Full analysis was in .forge/design/archive/core-reuse-feasibility.md (banner-superseded). Adopted in full 2026-08-06, stopped 2026-09-07 (AD #29), removed 2026-09-09 (AD #31 / FS-14). This is the record; nothing it describes is live.

What was built (2026-08-06 → FS-2). A two-tree module split — a generic CRM core that carried no knowledge of tea, and a tea-domain tree that extended it — with a build-enforced one-way dependency, a banned-vocabulary rule keeping tea terms out of the core, ten named extension points (typed 1:1 extension tables; a stage-type provider; a checklist/gate engine; tag-set compatibility; round lifecycle; prompt catalog + extraction schema; a metric provider; a price model; a handoff target; and the frontend field-renderer registry), two separate Postgres schemas with a partitioned Flyway version space (generic below, tea above), and four enforcement mechanisms (build graph, ArchUnit boundary + vocabulary rules, dependency-cruiser import rules, and a CI check that no generic table held a foreign key into a tea table). The frontend mirrored it with three workspace packages. Acceptance test: deleting the tea tree left a working generic CRM.

Why it was built. OQ-50 assumed the generic layer would be reused on future projects; the split made that reuse a first-class deliverable. Costed at ~+8–15% of V1 (see R-ARCH-001), accepted as a deliberate investment.

Why it is gone. The assumed reuse was no longer expected (AD #29, 2026-09-07), so the remaining spend (FS-12 extension-point substrate, FS-13 workflow primitives) was cancelled and the acceptance test retired — but the scaffolding FS-1/FS-2 had shipped was kept, on the judgment that removing it cost more than keeping it. Opened up on 2026-09-09 that judgment reversed: 13 of 16 backend modules and 2 of 3 frontend packages were near-empty shells, the substance moved rather than rewrote, and keeping the split taxed every one of ~30 features for a payoff already declared gone. FS-14 (AD #31) collapsed it — one Gradle module with feature-first packages com.empireteas.<capability>, one public schema, one squashed V1… Flyway sequence; one frontend src/{app,features,ui,lib} package (the capture PWA mirrored, with a shared-file drift check). The split’s guards were retired; the hygiene guards (layering, feature-package acyclicity, @NullMarked, no schema qualifier, fixture reachability + leak) stayed, and a feature-cycle rule was added.

What survives the collapse — still live:

  • The AI prompts stay rich and in one place (the ai package once it exists) — P-21, the PRD’s justification for building custom rather than configuring SaaS. The AI layer takes orchestration only (context assembly, schema validation, provenance, the human-approval queue, batching, model routing); “generic AI layer” must never become “generic prompts.”
  • This is not multi-tenancy — single-tenant is a PRD decision; the collapse does not touch it.
  • The entity model’s typed 1:1 extension tables (account / deal / product / quote / lead + the line-item price provenance) survive as the data-model design, now in one schema and unqualified — a feature spec may fold an extension back into its base table, but FS-14 refactored nothing. data-model.md §2 is authoritative and owned by Tharinda (AD #31).
  • Rule of two (coding-standards.md §0) — a new abstraction waits for a second real consumer; a workflow primitive is built and sized by its first consuming feature (AD #29).

Deployment topology was never affected — one ECS service, one worker, one RDS, one hosting shape throughout. The split was source organisation, not runtime.

Live structure lives in coding-standards.md §1 (feature-first placement), test-strategy.md § Test Naming & Layout, and the FS-14 row in the Foundation Backlog below.

Build Feasibility & High-Risk Requirements

Requirement Why high-risk Paper sketch / Spike
Two-way email sync (F20) Materially de-risked. The original R-12 risk was four provider mechanics; the proposal quoted Microsoft 365 via Graph only, and OQ-24 confirmed that is all Empire uses. One OAuth-native API remains. Residual risks are unchanged and unrelated to provider count: deliverability (SPF/DKIM), the shared-sender path, and silent sync failure if Graph subscriptions lapse. Paper sketch: Microsoft Graph as the single push-notified integration (webhook + periodic delta reconciliation poll + mandatory subscription renewal), behind a MailboxProvider seam. Matching engine links inbound/outbound mail to Account/Contact/Deal/Lead by participant email address + thread heuristics. No shared mailbox in V1 — info@ reaches the CRM by forwarding to a rep (2026-09-24; the sketch here once modelled it as an unowned MailboxConnection). SP-ARCH-002 stands down — re-scope it only if a Gmail/EWS/IMAP change request is accepted.
AI layer across F11–F15/F20/F25 (F16 dropped 2026-10-11) De-risked 2026-07-28; resolved 2026-08-19. OQ-15: cloud Claude approved, and the data-handling arrangements were signed off with the accepted proposal. Build the AI layer behind the AIProvider interface (extract → score → summarise → draft). SP-ARCH-001 stands down; the seam is retained as an architectural safeguard. Residual work is resilience + cost control, not the provider question.
Weekly bulk pricing (F26/F7/F14) De-risked 2026-08-21. Was the largest unmodelled area — effective-dated pricing, a (then) three-dimensional price key, a publish workflow, and a shared price/quote expiry clock. Client’s stated priority. SP-ARCH-003 resolved (2026-08-21, owner: Dinil). The model is settled and DDL-verified in <backend-repo>/docs/data-model.md §2 — price keyed on (buying_standard, validity) since PRD Rev 23 (the market axis was dropped 2026-09-11 — Rev 33; §2.2 is revised to match, Tharinda) with validity anchored to a numbered auction_sale row, cost at its own grain, publication as an audited draft→published transition. Spec F26 against §2, not against bulk-tea-pricing.md, whose §7 DDL it supersedes. Residual work is F26’s own, plus the open items §2.14 lists.
CRM→ERP handoff (F19) OQ-2 partial: current ERP confirmed = IFS; V1 ships manual handoff per AD #10; automated IFS integration is a separately-priced follow-on; the new ERP (~2027) is deferred. Paper sketch: ErpHandoffService interface; V1 implementation generates a structured handoff document only. A second implementation slots behind the same seam when IFS API availability is confirmed — no redesign of F19’s call sites.
Certification-mismatch (F9) + export-doc rules engine (F10) Data-driven, since certs/countries/doc rules change. Residual: OQ-9 still open — how the certifications a buying standard holds are stored is unconfirmed (awaiting Kavi Amali / QC documentation; the standard carries them since PRD Rev 27 — there is no product catalog). F9 is gated on that data source. Paper sketch: DocRule reference table (base docs, per-country docs, per-cert docs) seeded from the prototype’s seedDocRules; F9 is a set-difference between account-required and standard-held certification tag sets — no custom engine needed beyond normal relational modeling.
Configurable pipelines coupled to AI/automation (F24, R-14) Admin renames/reorders stages; automations and AI keyed on stage semantics silently break Paper sketch: every Stage carries a stable, non-editable stage_type (e.g. NEW_INQUIRY, QUOTE_SUBMITTED, WON) separate from its editable display name; rotting/probability/AI logic keys off stage_type, never the label. (AD #11)
Admin custom fields (F34) schema flexibility Field sprawl / migration risk if done as dynamic ALTER TABLE Paper sketch: custom field values stored as a JSONB column per entity table, with a CustomFieldDefinition table describing type/options for validation and list/filter rendering — core typed columns stay stable, extension is schema-less. (AD #8)
Duplicate job execution SQS at-least-once delivery + multi-task @Scheduled both produce duplicate side effects, including duplicate buyer-facing email Paper sketch: idempotency keys on every queued job + EventBridge-driven scheduling (see §Cross-Cutting). Design requirement, not hardening.

In-House-First Audit

External dependency In-house alternative considered Rationale for external choice
Claude via Amazon Bedrock Self-hosted open-weight model PRD mandates Claude directly from the backend; OQ-15 resolved (cloud AI accepted 2026-07-28; arrangements signed off with the accepted proposal). Self-hosted remains the fallback only if the client later restricts cloud processing — it adds real inference-hosting cost/ops for a 10–20-user team.
Microsoft 365 OAuth + Graph Mail/Calendar/Contacts APIs Building a generic mail/calendar protocol handler from scratch Reps’ actual mailboxes live on Microsoft 365 today — there is no in-house alternative to “read the mail that already exists there.” A hand-rolled protocol handler would only be needed for raw IMAP/EWS, which is out of V1 scope.
AWS managed services (RDS, SQS, S3, Secrets Manager, ECS, EventBridge, SES, Bedrock, CloudFront, SNS) Self-managed Postgres/queue/object-store/scheduler/SMTP on EC2 Team scale (10–20 users) doesn’t justify the ops burden of self-managing infra a managed service handles for a small cost delta; matches “buy vs. build undifferentiated infrastructure.”
Virus-scanning for uploads Writing a scanner Non-negotiably a solved problem; buyer-supplied artwork/POs are untrusted input. Decided (AD-O-4, 2026-09-12): Amazon GuardDuty Malware Protection for S3 (managed), behind the FS-11 FileScanProvider seam. Not enabled since 2026-10-09 (Rev 52): every environment runs F38-j’s scanning-off setting, and uploads are stored NOT_SCANNED; the GuardDuty scanner stays in the code for when it is added.
Trivy (dependency-vulnerability scan) Building a custom CVE-scan step; OWASP Dependency-Check (the tool AD #9 originally named) Mature, free, one binary that works uniformly across the Java and Node ecosystems — including pnpm lockfiles, which OWASP DC measurably cannot parse (0 npm coordinates; the FS-4 swap, AD #27). No API key, no JRE on frontend runners, governed ignores with tool-enforced expiry.
No third-party CRM engine, no-code automation platform, or integration marketplace (Zapier-style) — PRD explicitly discards these (P-11, P-27) — the valuable automations are domain-specific and built in-house (F18, F6, F9, F24, F25).

Resource & Timeline Reality

Substantially revised 2026-08-06 (Rev 2) and restated 2026-08-18 for the team of 3 and the dated window — see ## Revisions Rev 6.

  • Team capacity: 4 full-stack developers — Tharinda Rajapaksha, Dinil Gamage, Biseni Perera (confirmed 2026-08-18) and Nanndish Satgunarajah (joined 2026-09-29); development, QA, and harness work are shared across the team rather than split by role, so each added developer is real capacity but not a full extra build lane. There are no fixed lanes: each developer takes the next unblocked feature from the tracker (.forge/team-guide.md § Working in Parallel — Four Developers). No backend/frontend ownership split — everyone works both repos, and waves are sliced vertically (Gate-3 standing instruction in CLAUDE.md).
  • Delivery window: committed, in the issued proposal. project-proposal.md § 7 carries an indicative timeline that was already sent to the client — ~11–13 weeks to feature-complete, ~3.5–4 months to signed-off V1 — phased Foundation (2–3 wks) → Phase 0 (2–3) → Phase 1a (2–3) → Phase 1b (2) → Phase 1c (1.5–2) → UAT/stabilisation (3–4). (Delivery now consolidates these for acceptance: Phase 1 = 0 + 1a, Phase 2 = 1b + 1c, with a client UAT round after each — client/project-timeline.md; scope per phase unchanged.) §7 also carries a day-for-day slippage clause for late client dependencies, and §6 defines milestone acceptance with a client review window. This window was previously recorded here as “not supplied” — it was, and nobody had read it. Replaced 2026-09-29 by the revised Statement of Work (SOW-ET-001 v1.1): Foundation incl. cloud environments and pipeline Fri 16 Oct 2026, Phase 1 Fri 27 Nov, Phase 1 UAT Thu 10 Dec, Phase 2 Fri 8 Jan 2027, sign-off Fri 29 Jan 2027, day for day after an AWS environment ready by Fri 2 Oct (.forge/client/project-timeline.md).
  • Skills gaps: none flagged against the chosen stack (Spring Boot is the team’s existing enterprise-backend pattern; the Vite/React SPA + S3/CloudFront shape matches the team’s existing frontend deployments). AWS familiarity should be confirmed, not assumed. Two techniques in this build are new to the team regardless of stack familiarity and are the main estimation risk: effective-dated (temporal) data modelling for pricing, and Microsoft Graph subscription lifecycle management (webhook + renewal + reconciliation).
  • Critical-path estimate vs. that window (/forge-estimate 2026-08-06; restated against Option C and the team of 3 on 2026-08-18): ~68–92 wall-clock cycle-days for 13 Foundation slices (two of them, FS-12/FS-13, since dropped by AD #29 — the band has not been re-run; the drop only lowers it) + 30 in-scope features + the full-scope capture app (prototype-adjusted ~2.5–3.5-week parallel stream), against a 64-working-day build window (kickoff 1 Sep → feature-complete target 27 Nov; one public holiday inside it). On paper the build fits at the low-to-mid estimate; in practice the headroom is thin, because the estimate excludes human queue time and this engagement’s queue is already large and enumerated — the audit-tagged OQs in project-prd-signals.md (the bulk of the open list) blocked on the Pipedrive audit, OQ-9 gating F9, and a day-for-day clause that converts client latency directly into calendar. The risk is not the coding; it is the waiting. Basis: org baselines v0.34.0, zero project samples. Full reasoning and the scope levers are in R-ARCH-001.
  • The trade-show capture app is inside the estimate (full scope per project-proposal.md § 4 / A.7; Option C decided 2026-08-18) as the parallel third work-stream — see ## Trade-Show Capture App below. The record gap is closed: the app is F36 in the PRD (Rev 13, 2026-08-19 — OQ-48 resolved).

Key Technical Decisions

See .claude/CLAUDE.md → “Architecture Decisions (DO NOT REVERSE)” for the authoritative list. This section is a pointer, not a duplicate.

Promoted to CLAUDE.md § Architecture Decisions (CLAUDE.md is authoritative and has since grown further rows; the table below is the Gate-2 Run-2 candidate snapshot, rows 12–17):

Proposed # Decision Why
12 Timed work runs via EventBridge Scheduler → SQS, never in-process @Scheduled Multi-task deployment makes in-process scheduling fire duplicate side effects
13 Every queued job carries an idempotency key; consumers are replay-safe SQS standard queues are at-least-once; duplicate buyer email is unacceptable
14 Bulk prices and costs are effective-dated rows, never updated in place, except that a cost row starting today or later is deleted when a new cost from that date replaces it (F26-b FR-W4), and a published price starting today or later can be withdrawn — its status set to withdrawn, its figures and validity unchanged (F26-f FR-1, FR-10) Price history + as-of quoting are PRD requirements; temporality cannot be retrofitted
15 Authorization resolves as (role, resource, permission-level), not a flat authority check. Refined by AD #30 (2026-09-07) — the grant becomes (role, permission_key, scope) over a code-declared catalog; levels are per-key category metadata; scope gains team on a reporting hierarchy. See § AuthN / AuthZ. Further refined by AD #32 (2026-09-11) — read / edit / execute, no templates, one role per user. Further refined by AD #34 (2026-09-24) — a minimal view / manage catalog with no category axis, no superadmin and no * grant; AD #35 adds per-record shares to scope. Further refined by AD #37 (2026-09-27) — no scope on a grant; reach comes from the reporting hierarchy, and an <entity>.all key widens it to every record OQ-47 requires read-only/edit/AI-use/execute layering across six roles — refined: Empire asked for fully configurable roles, so the six are templates and the level lives on the permission (AD #30)
16 Microsoft Graph is the only mailbox integration in V1, behind a MailboxProvider seam; Gmail/EWS/IMAP are out of scope and additive only via change request The proposal quoted Microsoft 365 via Graph exclusively and OQ-24 confirmed it is all Empire uses. The seam keeps a later provider cheap without paying for one now
17 Full core/domain separation (adopted 2026-08-06; collapsed 2026-09-09 by AD #31/FS-14 — see § Core / Domain Separation). A generic CRM core and a tea-domain tree as separate modules with a build-enforced one-way dependency; tea attributes on typed 1:1 extension tables, never F34 JSONB; ten extension points; two Postgres schemas on a partitioned Flyway version space. Acceptance test: deleting the tea tree left a working generic CRM. Developer decision 2026-08-06 — build a genuinely reusable core, not a partial one. Costs ~+8–15% of V1 (see R-ARCH-001). CLAUDE.md’s AD table (rows 17/29/31) is authoritative for the full supersession chain

Foundation Backlog

Id Slice What it produces (substrate, not instances) Repo
FS-1 App shell All three app repos created (the capture repo included — Rev 21); Spring Boot app boots (one application.yml with task-definition values; local/test profiles only — two cloud environments, not three), the React app boots (Vite dev server), routing skeleton, env config, dev servers run. AD-O-10 working assumption (2026-08-18): Empire-held AWS account, opened at signature (dependency-register row 1) — slice 1’s non-cloud half (repos, module split, profiles, local dev) proceeds during mobilisation week; the cloud half (Terraform bootstrap — state backend, then the dev/prod module instances, AD #23) starts when the account exists. (AD-O-10 was superseded in September by SOW ET-002, which was itself superseded on 2026-09-29 and never signed: the AWS account is Empire Teas’ own, and the cloud half is F38’s — environments-and-identity.md §3.) Also establishes the two-tree module split and its build-graph + ArchUnit enforcement (pre-FS-14 wording; that split was collapsed — Rev 32; see § Core / Domain Separation). Spec: .forge/specs/foundation/001-app-shell-spec.md. <backend-repo>, <frontend-repo>, <capture-repo>
FS-2 Data layer scaffolding PostgreSQL datasource (local Compose + Testcontainers — RDS itself is the FS-1 cloud half), two-schema separation, Flyway configured with per-module migration locations and a partitioned version space, and a CI check that no generic table held an FK into a tea table (pre-FS-14 wording; collapsed to one schema on one version line — Rev 32), Spring Data JPA repository base classes, effective-dated (temporal) row conventions established for the pricing subsystem <backend-repo>
FS-3 Design system primitives three UI workspace packages with Biome + dependency-cruiser import rules enforcing the boundary (coding-standards.md §7.3) (pre-FS-14 wording; collapsed to one src/{app,features,ui,lib} package — Rev 32). Design tokens as a swappable theme layer — components consume semantic tokens, the app supplies Empire’s warm tea palette and Fraunces/Inter per .forge/design/ui/design-system.md (drafted 2026-08-18 from the client-approved prototype; the spec is authoritative over the prototype) — plus atomic components (Button, Input, Layout) and the FieldRenderer registry (extension point 10). Time-critical: near-free now, expensive across hundreds of components later. Scope widened at spec approval (Rev 25): both frontends — <capture-repo> receives its own copies of the token contract + breakpoint module (the shared UI library the named source of truth), the token rename + Empire theme file, the fixture-import dependency-cruiser rule and check-testid-coverage.mjs; the POC screens’ remap onto the tokens stays F36 capture-stream work. “Layout” here reads as the layout/* token family + breakpoint module — the §6 app frame defers to the first screen-shipping feature (spec Q-5). Spec: .forge/specs/foundation/003-design-primitives-spec.md. <frontend-repo>, <capture-repo> (thin half — Rev 25)
FS-4 Build & CI Lint/typecheck/tests/build green on a hello-world commit for both repos; the Trivy dependency-vulnerability scan wired in all three app repos (HIGH/CRITICAL ≡ CVSS ≥ 7.0, report-only — AD #9/AD #27, swapped from OWASP DC at Rev 26; AD #38 replaced the planned clean-baseline flip with a check on UAT and production releases) with per-repo governed .trivyignore.yaml files; the full quality toolchain per coding-standards.md §7 (slice-1 tools proven, slice-4 tools — Error Prone/NullAway, JaCoCo report, wrapper validation, bundle budget, Knip — wired here; every gate proven red-green once) <backend-repo>, <frontend-repo>
FS-5 Observability stubs Structured JSON logging → CloudWatch, error reporting, Micrometer Tracing (traceId/spanId stamped into every log line via MDC — request threads, @Async executors via context-propagating task decorators, and SQS consumer legs via trace context in message attributes; coding-standards.md §8), silent-failure alarms (lapsed Graph subscription, failed scheduled job, DLQ arrival, AI spend) delivering via SNS → team email + SES sending identity (domain verification; SPF/DKIM records land with dependency row 5) <backend-repo>
FS-6 Auth scaffolding SHIPPED 2026-09-15. Spring Security wired for Microsoft (Entra ID) OAuth2 login — the sole path (AD #28), authenticating with a signed assertion (private_key_jwt — spec Rev 6; two certificates, prod and a non-prod one shared by dev, UAT and laptops — spec Rev 13) rather than a client secret, with a profile-scoped local/test stub login; Spring Session JDBC; the configurable permission model — code-declared catalog, (role, permission_key, scope) grants, no templates (only the system superadmin is seeded — AD #32), one role per user, manager_id hierarchy, superadmin / last-admin / role-in-use guard rails and the orphan-grant check that fails startup (AD #30); CSRF + secure-cookie configuration; GET /api/v1/me as the FS-3 seam’s backend half; and AuditorAware discharging FS-2’s debt. No user-facing login or role screens — that is F5. Spec: .forge/specs/foundation/006-auth-scaffolding-spec.md (Rev 6). Plan: .forge/plans/foundation/006-auth-scaffolding-plan.md. Two deployment questions are recorded as owed rather than answered here — the CSRF cookie is host-only while the SPA is on a sibling host, and a fresh cloud environment has no account that can sign in (first-administrator provisioning, no owner yet); both are in forge-et-be/docs/auth/README.md. Realigned by F5-k (AD #34, 2026-09-24; done), and its keys since by AD #41: the superadmin role, the is_system flag and the * grant are removed, the catalog collapses to view / manage per entity plus access.manage and a few special keys, and a Flyway-seeded IT Admin role and user replace the runtime first-administrator job (answering the second deployment question); the cross-host cookie is AD #33’s, built by F5-j. The description above is what FS-6 shipped. <backend-repo>
FS-7 Background job substrate SQS consumer + @Async worker wired end-to-end, idempotency-key handling, dead-letter queue, retry/backoff policy (no real sync/triage/migration logic yet) <backend-repo>
FS-9 Scheduler substrate EventBridge Scheduler → SQS wired end-to-end with one trivial job proving the path; no real scheduled logic yet. F18, F7, F26 price expiry, and Graph subscription renewal all assume this exists <backend-repo>
FS-10 API conventions Pagination, filtering, sorting, error envelope, and versioning decided once and documented in docs/api/; a reference endpoint demonstrating all of them. Two seams are already committed by the design system (design/ui/design-system.md §6 data table + §5 AI provenance, Rev 2–3): pagination must support offset/numbered pages with a total — F32’s 1–25 of 340 UI needs stable page boundaries and a known count, so a cursor-only API cannot serve it — and every AI-produced payload exposes confidence (0–100) and source <backend-repo>
FS-11 File pipeline S3 upload path with type/size validation, virus scan gating visibility, signed-URL download scoped to record visibility <backend-repo>
FS-12 Extension-point substrate — DROPPED (AD #29) Cancelled before start, 2026-09-07. Was: the EntityExtension<T> registry plus the core-side wiring that makes generic machinery — list views, filters, global search, detail shells, import/export — compose domain-registered fields without naming them, and the registration surface for StageTypeProvider, MetricProvider, PromptCatalog, HandoffTarget and PriceModel (extension points 1, 2, 6, 7, 8, 9). The substrate served the reuse goal AD #29 retired; F31/F32/F34 and the import/export work compose the fields they need directly. Row kept as the record; id retired, not reused <backend-repo>
FS-13 Core workflow primitives — DROPPED (AD #29) Cancelled before start, 2026-09-07. Was: ChecklistEngine + GateRule (serving F7/F8/F10/F19 as configurations rather than five implementations), TagSetCompatibility (F9), RoundLifecycle (F6), StaleClock (F18/F24) — extension points 3, 4, 5, generic only. Each primitive is now its first consuming feature’s to build and size (F7 the checklist + gate, F9 the tag comparison, F6 the round lifecycle, F18 the stale clock), in whatever module compiles; whether it generalises to later consumers is that feature’s plan decision, not a foundation commitment. Row kept as the record; id retired, not reused <backend-repo>
FS-14 Single-module structure Collapses the core/domain split outright (AD #31, 2026-09-09). Backend: one Gradle module — a single build.gradle, no buildSrc, one lockfile — with feature-first packages com.empireteas.<capability> (platform, catalog, pricing, then one per feature), one Postgres schema (public), one Flyway location with the shipped migrations squashed into a fresh V1… sequence (nothing deployed or migrated — confirmed 2026-09-09). Frontend: forge-et-fe becomes one package laid out src/{app, features, ui, lib}; the capture app mirrors it and keeps byte-copies of the shared token files behind a drift check. Split guards retired, every hygiene guard kept, FS-10’s layering rule relocated, a feature-cycle rule (FeatureSlicesSpec / cruiser) added. Cascades through the harness (Appendix D of the spec), takes FS-6 to Rev 4, closes OQ-50 and FS-3 findings F-005/F-006. Code freeze on the three code repos while open. Spec: .forge/specs/foundation/014-single-module-spec.md. <backend-repo>, <frontend-repo>, <capture-repo>, harness
FS-15 Retire the product catalog Added 2026-09-16 (PRD Rev 27 — there is no products catalog; the client-specific Buying Standard is the sellable record for bulk and private label). Replaces the substrate’s stand-in entity: a minimal buying_standard (standard no, name, grade, type, origin, brand, the archive flag — no account_id, allocator or certifications join, which stay F1’s / F26’s / F9’s) and GET /api/v1/buying-standards re-home FS-10’s reference endpoint and FS-6’s audit proof; PriceModel defaults to unpriced (resolves nothing, which blocks — AD #14, no list price); the catalog package, the product.* keys and the product table go, and some thirty specs are retargeted rather than rewritten. Order is fixed by the drift check: data-model.md §2 revision first (Tharinda, AD #31), then the code, then the harness annotations of FS-2/FS-6/FS-10. Added after the 2026-09-15 manual foundation review — takes its own lead approval. Spec: .forge/specs/foundation/015-retire-product-catalog-spec.md. <backend-repo>, harness
FS-8 Developer onramp README + “how to add a feature” guide for both repos, including the feature-first package layout and the hygiene guards as facts of the build (AD #31 / FS-14: one package per capability with its layers inside, no dependency cycles between features — no layer doctrine beyond that, no extension-registration guide). Must also state the first-run costs a new machine pays once, so they read as expected rather than as something being broken: docker compose up pulls ~2.5 GB (LocalStack ~2.1 GB, Postgres ~411 MB) and can take a long while on a slow connection, and the first ./gradlew build downloads the Gradle distribution plus the dependency graph. Measured during FS-1 (findings F-005), where the pull looked like a compose misconfiguration until the image list was checked separately from the symptom <backend-repo>, <frontend-repo>

(FS-8 retains its id as the closing slice; new slices were appended as FS-9–FS-14 — FS-12 and FS-13 added by Rev 5’s core/domain adoption and dropped before either started by AD #29 (Rev 29) — their rows stay as the record, their ids are retired, not reused; FS-14 (Rev 31, AD #31) collapses the split those two were meant to extend. FS-<n> is the ticket id for slice work — branches, commits, PRs — per git-conventions.md § Ticket IDs; tracker setup.foundation.slices[].id uses the same ids.)

  • Data model: <backend-repo>/docs/data-model.md — created and authoritative for the schema (§2 is DDL-verified on PostgreSQL 18, the engine chosen for RDS, and §2.10 already reconciles .forge/discovery/research/bulk-tea-pricing.md). Prerequisite for the F26 pricing spec.
  • API contracts: <backend-repo>/docs/api/ — created at Foundation slice 10: README.md (index + the adding-an-endpoint checklist), versioning.md, collections.md, errors.md, payloads.md; each states the rule and its why, with GET /api/v1/buying-standards as the worked example (it replaced the retired products example at FS-15 — PRD Rev 27 / Rev 37). The generated OpenAPI document is served by the application at /v3/api-docs
  • Design system spec: .forge/design/ui/design-system.md (drafted 2026-08-18 from the client-approved prototype) — condensed into <frontend-repo> at Foundation slice 3
  • Coding standards & environment/profile conventions: .forge/design/coding-standards.md (confirmed by the team 2026-08-19; condensed into each app repo’s CLAUDE.md at Foundation slice 1)

Trade-Show Capture App (companion application)

Added 2026-08-18; the companion app is F36 in the PRD since Rev 13 (2026-08-19 — OQ-48 resolved). Scope is full (Option C); the reduced capture-and-feed shape remains a documented descope lever.

  • Its own repository — forge-et-pwa — hosted separately at its own URL (team decision — preferred over an apps/capture workspace app). Hosting: static bundle on S3 + CloudFront with an ACM certificate on the capture domain — no server component beyond the backend’s capture API slice (see §Deployment Topology > Compute). A small installable PWA (manifest + service worker for shell caching, so the app opens with no signal; a capture whose upload fails is kept on the phone and sent again when the app is open with a connection — no background sync, PRD Rev 64) that consumes the slice-3 design tokens and the generated API client as packages/copies rather than living inside <frontend-repo>.
  • Backend surface: a small capture API slice on the existing backend — authenticated upload (card photo / badge QR / voice-note text), which the slice holds, with its card reading and research, until a person in the app converts it into a CRM lead through the standard F11 lead-triage intake or rejects it (a rejected lead stays in the capture app; PRD Rev 95 — how a held capture is stored is F36-a’s spec, and whether research runs through F11-c’s chain before conversion is F36-c’s) — plus the show plan (PRD Rev 96, Phase 1): each campaign’s exhibitors, loaded from an uploaded CSV or Excel list read without AI or added by hand, with their visit notes and visited marks (stored by F36-a), each researched and ranked on the same AIProvider / SearchProvider seams (F36-c, which states how the research runs, its expected time under the Bedrock pacing and its cost) — plus a read lookup of accounts and contacts for the scan-time existing-client check Empire asked for on 2026-09-09 (PRD Rev 23; the app degrades to a “check pending” state offline). Card reading is a Haiku 4.5 vision call, and the research/scoring pipeline (Sonnet 5.5) rides the same AIProvider seam. Full scope is in V1 (decided 2026-08-18, matching proposal §4): adds in-app lead notifications — a notifications bell and an on-screen notice in the app; the capture app sends no email and uses no WhatsApp, so there is no messaging vendor and no SES sender for it (AD #42, 2026-11-12, replacing the SES email decided on 2026-08-18) — and a research source — no longer capture-only: PRD Rev 30 (2026-09-16) makes research a requirement on every F11 lead too, so the SearchProvider seam and its provider serve both features and belong to the AI layer rather than to this section. Options, verified pricing and the quality comparison (SP-ARCH-004 stage 2, run 2026-10-13) are in lead-research-source-options.md. F11-c built the seam on Exa, on its free credit, as the one provider with no fallback; Empire Teas chose Exa on 2026-11-10 (that document’s Rev 11; SP-ARCH-004 closed). A checkpoint descope to capture-and-feed-only exists if the stream runs behind (timeline §2, capture stream) — note that it no longer removes the research dependency, since F11 carries it independently.
  • Infra: same AWS account/pipeline; deployed separately from the CRM — served as a static S3 + CloudFront bundle at its own domain (see §Deployment Topology > Compute) — no container, no SSR need.
  • A working prototype exists (Thilina, confirmed 2026-08-18) — published read-only as the sibling forge-et-pwa-poc repo (2026-08-19; cloned beside the other four per team-guide.md § Repos on This Project): the exported PWA frontend (apps/web — React + Vite + Tailwind) API-integrated (its Python / Supabase / Fly backend is a reference only and does not port — § Stack, L-005), theme to be aligned to the slice-3 token layer; alongside it the POC’s own docs set (concept/spec, backend technical scope, feature breakdown, ADRs) and the clickable pitch prototypes (design/). Build work is therefore wiring + capture path + retheme, not ground-up UI — read the POC and port what’s needed into forge-et-pwa; never write to the POC repo. Its internal decisions are input material only: where they disagree with this document or the proposal, this project wins (e.g. its Tailwind styling and npm-workspaces layout are not adopted — forge-et-pwa is a single Vite app on pnpm per AD #21/#22 and the frontend conventions, themed by the slice-3 tokens; the retheme mapping is design-system open item 5).
  • Scheduling: full scope inside V1 as a parallel third work-stream (prototype-adjusted ~2.5–3.5 weeks), delivered in Phase 1 since 2026-11-11 (PRD Rev 91, AD #20; Gate 3 had placed it in Phase 2 with its scope unchanged) per project-timeline.md §2 (capture stream). The Statement of Work of 2026-09-29 holds the descope checkpoint during Phase 2, and records the confirmed scope; with the app in Phase 1, the checkpoint is proposed for Fri 2026-11-20, to be confirmed with Empire.

Open Decisions

Distinct from PRD open questions (which are client-facing and live in project-prd-signals.md). These are architectural choices this document has not yet made and which should be settled during Foundation:

# Decision Proposed Settle by
AD-O-1 Closed 2026-08-06 — answered by the proposal (frontend on ECS Fargate, costed in A.2 at 0.25 vCPU / 0.5 GB, $9/mo). Superseded 2026-08-18 by AD #21/#22: the frontend is now a React SPA served as a static S3 + CloudFront bundle — below the costed figure, and the SSR session-cookie residual dissolves with SSR itself. — —
AD-O-2 Closed 2026-10-11 — no longer needed: global search (F31) is dropped (PRD Rev 60). The proposed Postgres full-text search (tsvector + GIN), recorded by FS-2 Q-7 and never built, is withdrawn; each list keeps its own q filter — —
AD-O-3 Closed 2026-08-18 — decided: Amazon SES for all system/automation mail (no WhatsApp). It also covered the capture app’s lead-notification email until AD #42 (2026-11-12) made those notifications in-app only. SPF/DKIM setup on the sending domain still has real lead time — DNS records land with dependencies row 5. AWS SES Decided; wire at Foundation slice 5
AD-O-4 Closed 2026-09-12 — decided: Amazon GuardDuty Malware Protection for S3 (managed), enabled by devops via Terraform at environment setup. Chosen over a ClamAV container — it adds no second container (AD #22), the smallest Terraform surface (AD #23), no virus-signature upkeep (AWS owns definitions), and rides the GuardDuty base already in the cost basis (sow-cost-annexe.md); a third-party API was ruled out on the in-account posture (AD #19). Cost is usage-based and bounded to well under $1/mo at Empire’s file volume (25 MB cap) — confirm the current us-east-1 rate and add the annexe line at cloud-half enablement. Sits behind the FileScanProvider seam (FS-11), so ClamAV stays a swap-in. Settled by FS-11 — .forge/specs/foundation/011-file-pipeline-spec.md (OQ-1). 2026-10-09 (Rev 52): not enabled — Altrium management decided to go without GuardDuty until it is needed or Empire Teas asks; scanning is switched off by setting (F38-j) and the scanner code is kept. GuardDuty S3 Malware Protection (built, not enabled) Decided 2026-09-12; not enabled from 2026-10-09
AD-O-5 Closed 2026-08-06 — fully specified in proposal § A.5, not open at all. RPO/RTO per scenario (user error and AZ failure: 5 min loss / 1–2 hr restore; region loss: ≤24 hr / 4–8 hr with cross-region copy). PITR at 5-minute granularity. Retention 14 days production, 3 days development. Daily snapshots. S3 versioning on attachments. Documented restore rehearsal before go-live plus a quarterly restore test. Infrastructure-as-code is what makes the regional target achievable. — —
AD-O-6 Closed 2026-08-06 — fully specified in proposal § A.6.3. CRM records and attachments: life of system, deletion on request under the data-protection process. AI call metadata: life of system (what makes spend auditable). AI prompt and response bodies: never persisted in production logs — development only. Application/infra logs: 30 days. Backups per A.5. — —
AD-O-7 Widened 2026-08-06 — this is two problems, not one. (a) Replay safety: the PRD requires the migration be re-runnable / rollback-safe. (b) Delta reconciliation, newly surfaced: proposal § 8 commits a parallel run in which the new CRM and Pipedrive are both live and “Pipedrive remains the system of record”, followed by “a short, agreed freeze window… to run the final migration.” So F4 is not one import — it is an initial load plus a later reconciling pass that must skip already-migrated records, capture records created in Pipedrive during the parallel run, and never overwrite records created in the CRM. Also needs a rollback-to-Pipedrive position held open until sign-off, and a migration report Empire can verify against before decommissioning. Read side answered 2026-09-28 (F4-a spec): every run’s dry-run report sorts each Pipedrive row as new, already imported and unchanged, changed in Pipedrive since the last run, or already changed in the CRM, keyed on (source, source_ref); what a write run does with each group is F4-d’s and F4-b’s to decide (PRD Rev 44 — notes and activities are no longer migrated). — Before F4 spec — read side answered; write side answered for accounts and contacts (F4-d spec, 2026-10-13) and for leads (F4-b spec, 2026-11-06: a record a person changed on a mapped field is never written, FR-15)
AD-O-8 Seed-data strategy — dev seed data serves developers; each temporary UAT environment gets a presentable, client-facing data load (and a scripted teardown/cleanup if a round runs in pre-go-live production) Answered for the temporary UAT environment, 2026-10-23 (Rev 72; F38-h decision 5): the IT Admin enters the data by hand through the app after each apply, from F38-h’s checklist; no seed or script writes to a cloud database Foundation slice 1
AD-O-9 Closed 2026-08-18: Singapore — revised the same evening to US East (us-east-1) on cost. Singapore was priced 10–25% above the proposal’s mid-cost basis; US East lands at or below it. The original second reason, that every pinned model ran in-Region in us-east-1, no longer holds: neither pinned model is offered in-Region on bedrock-runtime in any US Region (ai-provider-strategy.md §4b). Reconsidered against us-west-2 and confirmed on 2026-10-01 with Shyamin Ayesh: us-east-1 — AgentCore Web Search runs there and CloudFront’s certificates, WAF and billing metrics need it anyway (environments-and-identity.md §3, §4). Accepted trade-off: ~200ms API round-trip from Sri Lanka (the static frontends serve from CloudFront edge regardless); buyer data is stored inside the project’s AWS account (Empire Teas’ own since 2026-09-29; environments-and-identity.md §3) in either region. us-east-1 Decided
AD-O-10 Who holds and pays for the AWS account. proposal § 12/§ 17: “[Who holds and pays the infrastructure account, to be confirmed.]” — Empire-held, or Altrium-held and transferred at engagement close. RESOLVED by SOW ET-002 (2026-09): the managed-cloud-infrastructure SOW (../client/aws-sow.md) has Altrium own and administer the AWS organisation and accounts and bill Empire a fixed USD 650/month (all-inclusive of AWS + admin; separate from the USD 360/month app support under ET-001); accounts are not transferred to Empire on exit. This reverses the earlier working assumption (Empire opens/hands over the account). Concrete environment/identity values: environments-and-identity.md. Re-resolved 2026-09-29 (Rev 47): Empire Teas declined ET-002 and holds the account itself — Kavindu Anthony holds it, Empire Teas’ card pays, AWS bills Empire Teas directly, and Shyamin Ayesh builds the environments with administrator access Empire granted. The account stays with Empire Teas; nothing transfers on exit. SOW ET-002 §2.1/§2.3/§8/§12 (superseded); proposal header note of 2026-09-29 Resolved 2026-09-29
AD-O-11 Closed 2026-08-19 — decided: two CI tiers, smoke-on-merge + full-on-tag; no nightly. The /forge-deliver orchestrator already runs the full live suite on the wave branch before the wave PR opens, so re-running it in CI on every merge tests the same commit twice. CI’s job is the two things a local run structurally cannot do: catch cross-wave integration breakage on main (two waves that pass independently can break each other once both land) and catch deployed-environment failures (migrations, CORS, OAuth redirect URIs, CloudFront/S3 SPA routing) that pass locally by construction. A nightly full run was considered and dropped — it duplicates the tag run without adding a distinct failure class, and Actions minutes are an org-wide shared pool. Constraint on the smoke tier: it runs against the shared development environment, so it must be read-mostly and create only uniquely-named records it cleans up — test-strategy.md § Test Data & Isolation requires E2E to reset and reseed between files, and a destructive reseed against dev mid-workday is not acceptable. Smoke on merge, full on tag Decided; tiers wired at Foundation slice 4, smoke-suite composition chosen with it. Revised 2026-10-19 (Rev 68): the smoke tier is run by hand after each deploy-dev, not in CI (F38 Rev 21, F38-g); the full tier is unchanged and its sign-in is open until F38-h’s plan. Revised 2026-10-23 (Rev 72): no browser tier runs inside deploy-uat — a person runs the smoke suite against uat after the deploys, and the release track’s regression cycle is the full check; the full tier inside deploy-prod is F38-i’s (F38 Rev 24, F38-h). Revised 2026-10-27 (Rev 81): no browser tier runs inside deploy-prod either — a person runs the smoke suite against production after the deploys (F38 Rev 31, F38-i decision 3). Noted 2026-10-27 (Rev 78): “no nightly” is about CI; the nightly full run of all three app repos runs off CI on the lead’s Mac (test-run-cost.md N-3)

(Id-collision note: an early question — whether Gmail is in V1 — was also numbered AD-O-9 before being closed on 2026-08-06 (the proposal quoted Microsoft 365 via Graph exclusively; now AD #16) and the id was reused. The live AD-O-9 is the AWS-region row above. See §Revisions Rev 1b.)

Open Questions

Carried architectural forks, reconciled against project-prd-signals.md on 2026-08-06:

  • OQ-15 (external-AI privacy) — cloud AI accepted 2026-07-28; the data-handling arrangements were signed off with the commercially accepted proposal (2026-08-16; PRD Rev 12). SP-ARCH-001 stands down; the AIProvider seam is retained as a safeguard. Reopened 2026-09-30 (PRD Rev 48) for the processing location only — whether buyer content may be processed outside the account’s Region and outside the US — and settled 2026-11-04 (PRD Rev 82): it may, in any commercial AWS Region (project-prd-history.md; client question Q18 answered and closed).
  • OQ-24 (mailbox providers) — resolved: Microsoft 365 via Microsoft Graph, exclusively. The proposal quoted no other provider, so Gmail/EWS/IMAP are out of V1 scope and additive only via change request. SP-ARCH-002 stands down. (Same tracker note as above.) The OQ-24 resolution wording in project-prd-history.md said Gmail/Exchange/IMAP “remain supported by the build”, which overstated the quoted scope — corrected in PRD Rev 7.
  • OQ-2 (ERP identity/API) — partial: current ERP confirmed as IFS; V1 ships the manual ErpHandoffService path; automated IFS integration is a separately-priced follow-on. No spike.
  • OQ-9 (standard-held certification storage — the buying standard carries its held certifications since PRD Rev 27) — open, and it gates F9. Awaiting QC documentation via Kavi Amali. The cert-mismatch check cannot be specced until the data source is known.

Risk status: R-ARCH-001 (capacity against the Statement of Work window; restated 2026-10-12 in tracker.yaml — Phase 1 fits, with its room going first to Phase 1’s own fixes, feedback, regression testing, release and cloud work; Phase 2 does not fit without a scope conversation with Empire) remains open and is the only open architecture-level risk. Of the Gate 2 spikes, SP-ARCH-001 and SP-ARCH-002 stood down at Run 2 (their triggers never fired) and SP-ARCH-003 was resolved on 2026-08-21; SP-ARCH-004 (the lead-research search provider, PRD Rev 30) closed when Empire Teas chose Exa on 2026-11-10; F11-c is built on Exa (design/ai/lead-research-source-options.md, Rev 11).

Revisions

Rev 96 — 2026-11-20 — F20-k: block lists work per address and look forward only

  • Changed — § Mailbox integration, the bullet “The CRM stores only email linked to a record”: “Users and the administrator can block addresses and domains” now names the two lists and their keys (each user’s own list under email.manage; the organisation list on its own Settings page under settings.email_block_list.manage, AD #41) and the per-address rule (a blocked address never causes an automatic link, an email still links through its other addresses, a thread reply whose outside participants are all blocked gets no thread link, and sends and manual links are not affected); “blocking an address applies to new mail, with an option to unlink its past mail” becomes “applies to new mail only, and email already linked stays until someone unlinks it”.
  • Why: F20-k spec (approved 2026-11-20) D-1, D-3 and D-5 — a block is for the few known people who are leads or contacts but not sales contacts, so a bulk removal of their past email would be rarely used and would need an exception to AD #35’s reach rule; F20-f’s per-email Unlink stays the way to remove a wrongly linked email, and the organisation list is filled before the go-live scans.
  • Decision: Tharinda (lead), with the F20-k spec, 2026-11-20. Rev 95 was taken by F22 (merged first); Rev 96 is the next free number (id-numbering rule 5).

Rev 95 — 2026-11-20 — F22: contacts are read one way into the CRM

  • Changed — the overview paragraph: the backend owns two-way email and calendar sync with reps’ Microsoft 365 mailboxes and reads their contacts one way into the CRM (F22), where it said “two-way email/calendar/contact sync”.
  • Why: the F22 spec (approved 2026-11-20), decisions 1–3 and FR-14: contacts are read from Outlook into a per-user review list, and nothing is written to Outlook (PRD Rev 107). Rev 94 was taken by F11-j (forge-et-harness#1611); Rev 95 is the next free number (id-numbering rule 5).
  • Decision: Tharinda (lead), with the F22 spec, 2026-11-20.

Rev 94 — 2026-11-20 — F11-j: the migrated lead’s email summary is background AI on the Global route

  • Changed — § Provider and model routing and § AI data-handling boundary: the summary of a migrated lead from its linked email (F11-j) joins the background features on Haiku 4.5’s Global profile, and the list of AI the system runs on its own.
  • Why: F11-j spec (approved 2026-11-20) D-3, D-9 and D-11: a background job writes it from the buyer’s linked received emails, paced and routed like triage and research (F43 FR-R3), on the minimum data its NFR-3 lists.
  • Decision: Tharinda (lead), with the F11-j spec, 2026-11-20 (PRD Rev 106).

Rev 93 — 2026-11-19 — F20-f: accounts reached through contacts; received files in their own table

  • Changed — § Mailbox integration, the bullet “The CRM stores only email linked to a record”: automatic linking checks a message’s addresses against leads and contacts, and an account is reached through its contacts, where it said “the addresses of leads, contacts and accounts”; a linked email’s attachments are kept in S3 under the email-attachments/ prefix and recorded in F20-f’s own email_attachment table, not FS-11’s attachment table, where it said only “in S3, with a size limit”. In the same bullet, the past-mail scan’s “matches a lead, contact or account” becomes “a lead or a contact (an account through its contacts)” (F20-f Rev 1), and “the record it belongs to” becomes “the records it is linked to” (D-1).
  • Why: F20-f spec (approved 2026-11-19) D-2 — an account row holds no email address, and matching by the website’s domain would link mail from everyone at a buyer’s company with nobody choosing it — and D-6 — a received file needs none of FS-11’s upload rules and must be deletable without trace.
  • Decision: Tharinda (lead), with the F20-f spec, 2026-11-19.

Rev 92 — 2026-11-19 — the capture app’s deploy-uat exists

  • Changed — § CI/CD Pipelines, “UAT deploys are deferred, deliberately”: deploy-uat exists in forge-et-pwa too, merged on 2026-11-19 (forge-et-pwa#169), and the capture app is hosted on UAT (forge-et-iaac#23); forge-et-fe’s run also checks the capture app’s version once forge-et-fe#582 merges. The paragraph had said the capture app’s was still to be built.
  • Why: F38-h spec Rev 12 (FR-13): the capture app is in Phase 1’s round, as the lead decided on 2026-11-12.
  • Not changed: the per-repo tables. forge-et-pwa’s line says it has the same workflows as the frontend, which now holds for deploy-uat. WI-4.1’s own harness records for § CI/CD Pipelines are still owed (.forge/owed.md).

Rev 91 — 2026-11-16 — the Settings keys named as AD #41 split them

  • Corrected — § AuthN / AuthZ (the Users and user-directory bullets, the enforcement bullet) and § Feature flags: they still named settings.manage, which AD #41 replaced on 2026-10-30 with one key per Settings page. Creating users and the user list are settings.users.manage; the last-admin guard counts users holding both settings.users.manage and settings.roles.manage; the AI switches get their own Settings key when that page is built.
  • Corrected (the same review, 2026-11-17): § AuthN / AuthZ’s permission-model bullet names AD #41’s page keys, and the production admin email is a plain task-definition value (AD #40), not a Secrets Manager secret; the capture-app section and § Open Questions say Empire chose Exa on 2026-11-10 and SP-ARCH-004 is closed; § CI/CD Pipelines says the capture app’s deploy-uat is built for Phase 1’s round, and F38-i is tracked in Phase 1; the FS-6 backlog row says F5-k is done.
  • Why: found by the documentation review of 2026-11-16; AD #41’s change did not reach these lines.
  • Decision: none needed — the text now states AD #41 as decided.

Rev 90 — 2026-11-13 — Dependabot PRs get a local test record

  • Changed — § CI/CD Pipelines: the backend and frontend pr-validation rows: the Slow lane runs on demand only; a Dependabot PR skips it like any other PR, and a delivery-team member’s local record sets its Test record check.
  • Why: the lead’s decision of 2026-11-13 (.forge/design/harness/test-run-cost.md N-5): Dependabot PRs’ Slow lanes took about 560 runner minutes in 30 days, and the backend’s was nearing its 60-minute cap.

Rev 89 — 2026-11-12 — the capture app plans a show

  • Changed — § Trade-Show Capture App, the backend surface: the capture slice also holds each show’s plan — the campaign’s exhibitors, loaded from an uploaded list read without AI or added by hand, with visit notes and visited marks (F36-a) — and each exhibitor is researched and ranked on the same AI and search seams (F36-c). How and where they are stored, and how the research runs, are those specs’.
  • Why: PRD Rev 96 — the lead put planning before a show in Phase 1 on 2026-11-12 (reported by Nanndish). The section’s sizing (about 2.5–3.5 weeks) predates it; re-sizing is the lead’s (.forge/owed.md, “Say whether planning before a show changes the price”).

Rev 88 — 2026-11-12 — a captured lead is reviewed in the app before it reaches the CRM

  • Changed — § Components (the capture-app row) and § Trade-Show Capture App, the backend surface: the capture slice holds each captured lead until a person in the app converts it, which creates the CRM lead through the F11 intake, or rejects it, which keeps it in the capture app; the slice no longer passes an upload straight to the intake. Where a held capture is stored is left to F36-a’s spec, and how its research runs before conversion to F36-c’s.
  • Why: PRD Rev 95 — the capture-app decisions of 2026-11-12, accepted by the lead (Tharinda) with the screens drawn in prototypes/pwa-current/ the same day.

Rev 87 — 2026-11-12 — the capture app sends no email

  • Changed — the system diagram, § Components (the capture-app and System Mail Sender rows), § Trade-Show Capture App and AD-O-3: the capture app’s lead notifications are in-app only (a notifications bell and an on-screen notice); SES carries system mail only.
  • Why: AD #42 (lead sign-off, Tharinda, 2026-11-12; PRD Rev 94): the in-app notifications drawn in prototypes/pwa-current/ tell a rep what an email would, and dropping the email removes F36-c’s sender, recipients and template.

Rev 86 — 2026-11-09 — the scheduled-email send sweep

  • Changed — § Scheduling: the list of jobs still to come gains F20-g’s scheduled-email send sweep, which runs every minute and sends every scheduled email that is due.
  • Why: F20-g spec decision 6 (Dinil, 2026-11-09): one schedule per email would need the backend to create and delete AWS schedules at runtime, with new IAM permissions, for no gain at this scale; the sweep’s invocations stay inside EventBridge Scheduler’s and SQS’s free monthly allowances.

Rev 85 — 2026-11-06 — file attachments: validated, and not scanned while scanning is off

  • Changed — § Components, the File Storage row, and § Deployment Topology, the Storage bullet: uploads are type- and size-validated and recorded as not scanned while virus scanning is switched off, where both said every upload is virus-scanned; the Storage bullet adds that a file names its one record (entity-map D-6, revised by F33-a) and is listed from upload, and the component row names F33-a and F33-b.
  • Why: F33-a spec FR-H2: Rev 52 (GuardDuty not enabled) changed the security baseline and AD-O-4 but left these two statements, which PRD Rev 58 had already overtaken.

Rev 84 — 2026-11-03 — a suite runs in one place

  • Changed — § CI/CD Pipelines: the backend and frontend pr-validation rows: the scheduled run is weekly and runs the Fast lane only, kept to refresh main’s caches; a push to release/* runs the Fast lane only; the test suites run in CI only on Dependabot PRs and on demand (forge-et-be#352, forge-et-fe#387, forge-et-pwa#107).
  • Why: the lead’s decision of 2026-11-03 (.forge/design/harness/test-run-cost.md N-5).

Rev 83 — 2026-11-02 — the browser gate leaves the PR into main

  • Changed — § CI/CD Pipelines: each frontend’s Fast lane last step, the Browser gate: description check, passes at once unless the PR goes into release/* (forge-et-fe#379, forge-et-pwa#105); the browser matrix runs every night on main in the nightly full run, and a PR into main runs no browser gate.
  • Why: the lead’s decision of 2026-11-02 (PRD Rev 81; .forge/design/harness/test-run-cost.md S-4, revision line of 2026-11-02).

Rev 82 — 2026-10-28 — the tag format picks the environment

  • Changed — § CI/CD Pipelines, Per repo: the deploy-prod rows (backend and frontends) and the deploy-uat rows: pushing a vX.Y.Z-rc<N> tag deploys to UAT and pushing a plain vX.Y.Z deploys to production, in place of Rev 81’s manual dispatch by a named deployer; production’s trigger is added on the day production is created; deploy-uat stops at its first step while no UAT environment is applied; the backend reads dev’s image with dev’s svc-github key; each frontend waits for the backend’s version and production uploads no source maps.
  • Changed — § CI/CD Pipelines, UAT deploys: the tag format keeps deploy-uat and deploy-prod apart; every UAT candidate, Phase 1’s included, is an -rc tag.
  • Changed — § CI/CD Pipelines, Cross-cutting, GitHub Environments: the named-deployer check and the tag ruleset are removed; the gate is the tag format and each Environment’s ref rule.
  • Why: the lead’s decisions of 2026-10-28 (F38-i spec Rev 1, decisions 12, 19–22, 25, 32; F38 Rev 32): one tag format per environment, so a person tags without choosing a workflow, and no named lists.
  • Not changed: the release vulnerability check (AD #38), one image never rebuilt (F38 NFR-4), waiting for a stable service (F38 NFR-9), and no browser tier inside either deploy (Rev 81).

Rev 81 — 2026-10-27 — deploy-prod settled by F38-i’s spec

  • Changed — § CI/CD Pipelines, Per repo: the deploy-prod rows of forge-et-be and forge-et-fe replace the tag-push trigger first designed (tags: ['v*', '!v*-rc*']) with a manual dispatch on a release tag by a named deployer; the backend’s row says the image dev built is copied by digest into production’s own repository with a dev-account pull user; the frontend row adds the backend-version check and the smoke run by hand, and says the capture app’s deploy-prod has the same shape.
  • Changed — § CI/CD Pipelines, UAT deploys: the sentence leaving the trigger split to F38-i now states it.
  • Changed — § CI/CD Pipelines, Cross-cutting, GitHub Environments: the “manual promotion gate” is the production Environment’s v* tag rule, a first-step named-deployer check and a v* tag ruleset, in place of required reviewers, which the GitHub Team plan does not offer on a private repository.
  • Changed — the browser-tier table’s full-suite row, the paragraph after it, and § Open Decisions, AD-O-11: no browser tier runs inside deploy-prod; production gets a smoke run by hand after the deploys, and no tag-time full run exists. .claude/CLAUDE.md § Common Commands, test-strategy.md § When Tests Run (its Rev 31) and coding-standards.md §7.1 say the same.
  • Why: the lead’s decisions 2, 3 and 5 at F38-i’s spec, 2026-10-27 (F38 Rev 31). A tag-push trigger would have sent Phase 1’s v0.1.0 to production; the full suite depends on the local seed and the stub login; GitHub’s “Deployments and environments” reference (read 2026-10-27) says required reviewers are not available on the Team plan for private repositories.
  • Not changed: the release vulnerability check (AD #38), one image never rebuilt (F38 NFR-4), and waiting for a stable service (F38 NFR-9).

Rev 80 — 2026-10-28 — changes to a user’s own Outlook mailbox state are not audited

  • Changed — § Audit trail: one sentence added: changes to a user’s own mailbox state in Outlook other than a send (marking a message read or unread, the CRM’s All-mail search folder) are not audited.
  • Why: AD #36 refined by the lead at F20-i’s spec review, 2026-10-28 (.claude/CLAUDE.md AD #36; engagement-log.md § Architecture Decisions — full rationale archive; F20-i spec D-7).

Rev 79 — 2026-10-26 — access.manage folded into settings.manage

  • Changed — § AuthN / AuthZ, the Users, permission-model and user-directory bullets: all user, role and hierarchy administration and all configuration are one key, settings.manage, which opens every page of the CRM’s Settings page; access.manage leaves the catalog. The seeded IT Admin role holds settings.manage (the migration forge-et-be V54 moves every access.manage grant onto it, audited), the last-admin invariant and the deactivation refusal name settings.manage, and the administration user list sits behind it.
  • Why: AD #34 refined by Nanndish on 2026-10-26, signed off by Tharinda, 2026-10-27 (.claude/CLAUDE.md AD #34; engagement-log.md § Architecture Decisions — full rationale archive; PRD Rev 79).

Rev 78 — 2026-10-27 — the nightly full run moves to the lead’s Mac

  • AD-O-11’s “no nightly”: stands for CI. The full browser suite now runs every night off CI, on the lead’s Mac, with the backend and Vitest suites (.forge/design/harness/test-run-cost.md N-3, approved 2026-10-27); AD-O-11’s two reasons — a nightly CI run duplicated the tag run and spent the organisation’s Actions minutes — do not apply to a run off CI. The scheduled PR validation run keeps only its Fast lane and Trivy (AD #38). The AD-O-11 row gains this note.
  • § CI/CD Pipelines: the pr-validation rows of forge-et-be and forge-et-fe say the Slow lane is skipped on the nightly run, and the paragraph on the dropped nightly run says it was dropped from CI and now runs on the Mac.

Rev 77 — 2026-10-26 — F38-d’s closing sweep

  • Checked — § CI/CD Pipelines › How dev is deployed today: compared with the four deploy files on the trunks on 2026-10-26 (F38-d WI-7.1, AC-10); the bullets match. The heading’s read date is now 26 Oct, and the Environments bullet names forge-et-pwa with forge-et-be and forge-et-fe (its dev Environment has no branch rule either; environments-and-identity.md §4, “F38-d — the dev deploy pipelines, checked”, AC-1).

Rev 76 — 2026-10-26 — the backend’s dev deploy after F38-d’s deliberate checks

  • Changed — § CI/CD Pipelines › How dev is deployed today: the backend bullet now says the task definition carries every register §D value for dev (forge-et-be#300, forge-et-be#306, verify-full included) and that the circuit breaker’s rollback of a task that cannot start was shown on dev by F38-d WI-6.1’s two deliberate failed deploys on 2026-10-26.

Rev 75 — 2026-10-26 — corrections from the harness review of 2026-10-26

  • Corrected — § CI/CD Pipelines, “How dev is deployed today”: the capture app’s bullet read “no deploy yet”; it now describes forge-et-pwa’s build.yaml (F38-d wave 5, forge-et-pwa#91, first run 2026-10-25). The joining bullet now says four repositories and names the capture app’s bucket et-dev-capture and its CloudFront distribution, and the manual-run sentence lists forge-et-pwa. The backend bullet said the build-* tags stay mutable until F38-d WI-3.1; they are immutable since forge-et-iaac#6, applied 2026-10-23, and the pointer now names “Checked against F38” row 8 instead of §4 item 6.
  • Corrected — § CI/CD Pipelines, the action-pinning rule: the dated list of majors (as of 2026-08) was older than what the app repos’ workflows use, which the same rule forbids; it now points at the uses: lines in the app repos’ workflows, with the majors read on 2026-10-26.
  • Corrected — § Data Flow and § Cross-Cutting Concerns › Scheduling: both put Spring Session’s expired-session cleanup on EventBridge Scheduler, which AD #12 keeps in-process; the list now names the scheduled jobs the backend runs (F20-a/F20-b, F20-h, F26-g, F11-d, F11-c) and those still to come.
  • Corrected — § Trade-Show Capture App and the risk status under § Open Questions: the search provider read “not yet chosen”, with SP-ARCH-004 triggered before the F11-c spec; F11-c is built on Exa, provisionally until Empire Teas answers (design/ai/lead-research-source-options.md, header update of 2026-10-20, §13).
  • Removed — § Deployment Topology, the CI/CD bullet: the note asking to confirm GitHub Actions for the app repos at Foundation slice 1; Foundation sealed on 2026-09-16 and § CI/CD Pipelines describes each repository’s workflows.
  • Corrected — the header’s “Last updated” line, which still named Rev 73.

Rev 74 — 2026-10-26 — the connect button kept; several addresses per contact; email on lead conversion

  • Changed — § Mailbox integration, the sign-in bullet: the mailbox still connects itself at sign-in, built on F20-a’s connect flow, and F20-a’s mailbox screen and button are kept as Try again (after a failed automatic connect) and Reconnect (after a disconnect, or when the connection needs reconnecting); the bullet read “there is no Connect button to press”. The bullet now also states that a failed connect never affects sign-in, and why, and that the capture app’s sign-in never starts the connect.
  • Added — § Mailbox integration, two bullets: a contact can hold several email addresses, one of them the main address, and matching uses all of them, with the Pipedrive migration keeping every address and F20-l (split from F20-f by the reslice of 2026-10-26, project-prd-history.md Rev 77) building the change; and converting a lead links its emails to the new account, contact and deal, and a converted lead is no longer a target of automatic linking.
  • Why: the lead’s decisions of 2026-10-26 on the three open email questions (.forge/owed.md, raised on 2026-10-19 when Dinil Gamage questioned the sign-in connect). Connecting at sign-in stays because a button alone leaves reps whose mail never links and whose mailbox is never scanned; the button already exists, so keeping it for the failure and reconnect cases costs nothing. 246 people in the Pipedrive people export have several work addresses in one cell, and keeping only the first would leave mail from the others unlinked. Linking a converted lead’s email to its new records keeps the buyer’s history on the account and deal where the work continues.

Rev 73 — 2026-10-23 — the dev deploy pipelines after F38-d’s wave 2

  • Changed — § CI/CD Pipelines › How dev is deployed today: read on 23 Oct; the CRM bullet now describes forge-et-fe’s workflow as forge-et-fe#298 leaves it (a build job with the guard and no AWS credentials, a deploy job joined to it by the web-dist artifact, no deploy for a workflow-only push); the last bullet no longer says forge-et-be runs on v*.*.* tags and says all three repositories have a manual run. The backend bullet, rewritten in Rev 69, was checked against forge-et-be main at 06062de8 and left as it is.
  • Why: F38-d’s wave 2 merged on 2026-10-19 (forge-et-be#275, forge-et-fe#298), and its runs on dev are recorded in environments-and-identity.md §4 “F38-d — the dev deploy pipelines, checked” (F38-d WI-4.2); this section is the one place in this file that describes the dev workflows as they run.
  • Not changed: the capture-app and infrastructure bullets.

Rev 72 — 2026-10-23 — no browser tier inside deploy-uat; the UAT data entered by hand

  • Changed — § Open Decisions, AD-O-11: for deploy-uat, the full tier on the tag becomes a smoke run by hand against uat after the deploys, with the release track’s regression cycle as the full check of the assembled product; no browser tier runs inside deploy-uat. The full tier inside deploy-prod stays F38-i’s question.
  • Changed — § CI/CD Pipelines: the browser-tier table’s full-suite row and forge-et-fe’s deploy-uat row say the same; forge-et-fe’s run checks the backend’s version before it deploys. In Phase 1’s round deploy-uat exists in forge-et-be and forge-et-fe only.
  • Changed — § Deployment Topology, the “AWS — two environments, not three” bullet: the temporary UAT environment runs in the development account and reads dev’s Entra secrets, SES identity, backend image repository and Exa key, as AD #4 now says (refined 2026-10-23; engagement-log.md § AD #4).
  • Changed — § Open Decisions, AD-O-8: answered for the temporary UAT environment: its data is entered by hand through the app by the IT Admin after each apply, from a checklist; no seed or script writes to a cloud database.
  • Why: the lead’s decisions of 2026-10-23 while F38-h’s spec was drafted (F38-h spec decisions 1, 5 and 6 for the browser tier and the data; decisions 2–4 and 10 and Q-5 for the Deployment Topology sentence; F38 Rev 24). The full suite depends on the local seed and the stub login throughout (F38-g spec decision 4), so it cannot run against a cloud target, and coding-standards.md §5 keeps seeds out of cloud databases.
  • Changed — § CI/CD Pipelines › “UAT deploys are deferred, deliberately”: its last sentence now says the same: backend and CRM only in Phase 1’s round, forge-et-fe’s run checks the backend’s version before it deploys, and a smoke run by hand against uat follows, with the regression cycle as the full check.
  • Not changed: the backend’s deploy-uat row. F38-h’s implementation PRs check that row and the paragraph against the workflows they build (F38-h FR-12).

Rev 71 — 2026-10-23 — alarms decided per environment; no exporter or error destination in V1

  • Changed — § Deployment Topology › Observability: which alarms an environment carries is decided per environment. Dev has the alert topic and an EventBridge email when a backend deploy fails, and no alarm. UAT and production choose from the list in the bullet. AI spend against budget is the billing owners’ AWS Budgets alert. There is no span exporter and no frontend error destination in V1.
  • Why: the lead’s decisions in the F38-e spec session (F38 Rev 23, F38 W-9): in dev the alarms would mostly report the team’s own work in progress, at a monthly cost for little benefit; and a request’s traceId in the CloudWatch logs is enough to follow it at this system’s size.
  • Not changed: CloudWatch Logs with structured JSON, Micrometer Tracing stamping traceId/spanId into every log line, and SNS email as the delivery path for every alarm that is built.

Rev 70 — 2026-10-21 — the account briefing is AI a person asks for

  • Changed — § AI data-handling boundary: the account briefing moves from the AI the system runs on its own in the background to the AI a user invokes on a record; the morning briefing stays where it was.
  • Why: the lead moved it within AD #32 on 2026-10-21 (F13 spec decisions 2 and 3, PRD Rev 76): a briefing is made when a person whose role holds account.manage asks for it, as the Phase 1 acceptance criterion E6 says, and a view-only role never starts AI work.
  • Not changed: the minimum-data rule and the never-sent list.

Rev 69 — 2026-10-20 — the dev deploy neither waits for the rollout nor scans the image

  • Changed — § CI/CD Pipelines › How dev is deployed today: the backend bullet now describes the workflow as F38-d’s forge-et-be#275 and #286 leave it: two jobs, the ARM64 image tagged by full SHA, no rollout wait and no image scan in dev.
  • Why: the lead’s decision of 2026-10-20 (F38-d spec Rev 3, F38 Rev 22, AD #38 restated). The wait and the scan were most of each dev deploy’s billed minutes (6–15 a run, against 2–3 without them) and changed nothing in dev: the circuit breaker restores the previous task, and ECR scans each image on push.
  • Not changed: deploy-uat and deploy-prod still wait for a healthy service and still scan the image they release, stopping on a finding (F38 FR-35, NFR-9).

Rev 68 — 2026-10-19 — the smoke tier is run by hand

  • Changed — § CI/CD Pipelines: “Browser E2E runs in two CI tiers” is renamed “Browser E2E runs in two post-deploy tiers”. The smoke tier’s trigger is a manual run by the delivery-team member whose merge or manual dispatch started the deploy-dev, from their own machine, with no CI job; a new paragraph gives the reason and the minutes it saves; the read-mostly paragraph adds that F38-g’s smoke account holds only view keys (and all keys that widen them). The full tier’s row notes that its sign-in is open until F38-h’s plan. § Open Decisions: the AD-O-11 row records the revision.
  • Why: the lead’s answer to F38 OQ-D for the smoke tier, 2026-10-19, while F38-g’s spec was drafted (F38 Rev 21). F38 FR-34 required AD-O-11 to be revised if OQ-D chose a manual run.
  • Not changed: the full tier inside deploy-uat and deploy-prod; no nightly run; the local browser gate (F40). F38-h starts the full tier from the finding recorded in F38 OQ-D: the full suite depends on the local seed’s fixture users and the stub login, which uat will not have as built.

Rev 67 — 2026-10-18 — deploy-uat is not a copy of deploy-prod

  • Changed — § CI/CD Pipelines: “UAT deploys are deferred, deliberately” no longer says deploy-uat is a copy of deploy-prod. It now says F38-h builds deploy-uat first, from the reviewed dev workflows, states its shape from F38 FR-35, and leaves the deploy-prod trigger to F38-i. The browser-tier table names deploy-uat first for the full suite. In § Per repo, the backend and frontend tables gain a deploy-uat row, and their deploy-prod rows say F38-i builds them and settles their tag trigger, because the Phase 1 candidate v0.1.0 carries no -rc suffix (F38 FR-20, FR-35), and that they run the release vulnerability check; the backend’s deploy-prod row says it promotes the dev image instead of rebuilding (F38 NFR-4).
  • Why: deploy-prod is F38-i’s, in Phase 2, so it does not exist when deploy-uat is built, and F38 FR-35 had already defined deploy-uat differently (the lead asked for the fix on 2026-10-18; F38 Rev 19).

Rev 66 — 2026-10-18 — running cost is a design constraint

  • Changed — § Deployment Topology: a first bullet states that keeping the AWS bill low is the delivery team’s responsibility through design and daily use, that billing settings belong to Shyamin Ayesh, Kavindu Anthony, Malinda Wellalage and Thilina Abeyrathna, and that a design choice adding a running cost is justified by a requirement and named in the spec. .claude/CLAUDE.md § Boundaries carries the same rule for every session.
  • Why: the lead’s decision of 2026-10-18, when the AWS Budgets and cost allocation tags were taken off the delivery team’s list.

Rev 65 — 2026-10-18 — how dev is deployed today

  • Changed — § CI/CD Pipelines: a new subsection, “How dev is deployed today”, describes the dev pipelines the DevOps team built ahead of F38-d, how the three repositories relate (fixed AWS names and one shared key, no calls between them), and the backend pipeline’s known gaps: no manual trigger, and no wait for the ECS deployment to finish.
  • Why: the lead asked for it on 2026-10-18; the tables above it describe the design, which the built workflows differ from. The gaps are fixed by F38-d (its spec’s Open Questions, environments-and-identity.md §4 item 6).

Rev 64 — 2026-10-17 — the development database is not encrypted at rest

  • Changed — § Committed security baseline (the KMS item): in the development account the database is not encrypted at rest and there is no database or backups key; development builds only the storage key and the mailbox token key. Whether production’s database is encrypted is undecided: Shyamin Ayesh, Thilina Abeyrathna and Malinda Wellalage decide it before F38-i creates the production database (.forge/owed.md).
  • Why: the lead’s decision of 2026-10-17 (F38 Rev 17): encrypting dev’s existing instance needed a snapshot-and-restore only the DevOps team could do, and dropping it removes that dependency; dev holds test data only. A post-issue note on the proposal (17 October) records the departure from §A.4; a “no” for production would be a further departure, probably needing Empire Teas’ agreement, and encryption is free only when the database is first created.

Rev 63 — 2026-10-17 — defaults for the live inbox and past mail, and past mail for a mailbox that connects later

  • Changed — § Mailbox integration: the inbox page size is at most 100 (50 by default), and a new record’s past mail is fetched back 12 months by default. Both stay settings in application.yml. Past mail is also linked from the mailbox side: when a mailbox connects, and after a bulk import, a background job scans each connected mailbox’s headers for the same period and links matches to existing records.
  • Why: the lead accepted these on 2026-10-17. 50 a page halves the requests that 25 would need while staying small (only the list’s fields are fetched); 12 months bounds the background search. Leads and accounts are migrated before every user has connected a mailbox (PRD §F4), so without the mailbox-side scan a user who connects later would have none of their past mail with those buyers on the migrated records. A header scan is about 20 requests for a year of a busy mailbox, against one search per record per mailbox for a bulk import.
  • Also changed (the lead, 2026-10-17, after a review of the design): a linked email’s attachments are stored with it, in S3 with a size limit, because fetching them from the owner’s mailbox fails for colleagues once the owner leaves or deletes the email; unlinking removes the stored copy when no other record holds it and serves data-protection deletion requests; blocking applies to new mail, with an option to unlink the past; linking needs the record’s manage and the email in the user’s own mailbox, unlinking the record’s manage. The mailbox connects itself at sign-in for users whose role holds email.manage, with no Connect button, and one connection carries the mail, calendar and contacts permissions; the sign-in session and the mailbox connection keep separate lifetimes, so signing out never stops mail linking. The connection is checked on every load of the CRM, so a permission granted later connects without a new sign-in; Disconnect stays, in the user’s settings, and is never undone automatically; losing email.manage releases the connection; email.manage stays a per-role setting, not given to every user by default.

Rev 62 — 2026-10-17 — the CRM stores only email linked to a record

  • Changed — § Mailbox integration: a new bullet. The inbox is read live from Microsoft, 50 messages a page by default (a setting), over Inbox, Sent Items, Archive and the user’s own folders, with Outlook categories shown; only email linked to a lead, contact or account (automatically by address or thread, or by a user) is stored, in full; a record created later has its past mail fetched from every connected mailbox by a background job, back to a configured period; users and the administrator can block addresses and domains; nothing is deleted automatically. Today’s code (F20-b) stores every message since the connection; F20-f changes that.
  • Why: the lead’s decision of 2026-10-17, after Kavindu Anthony asked on 2026-10-16 why every email is synced when some mailboxes are over 50 GB (.forge/discovery/meeting-notes/2026-10-16-kavindu-progress-update.md §5). A filter by known address alone would drop a new buyer’s first inquiry, so unmatched mail stays visible through the live inbox instead of being stored. Linked email is stored whole because a colleague who reaches the record cannot read the owner’s mailbox through Microsoft, and the owner’s connection ends on disconnect or deactivation. Pipedrive, HubSpot, Salesforce and Zoho all keep linked email in full.
  • Past mail for a new record: fetched from every connected mailbox (the lead, 2026-10-17), because auto-linking already links a colleague’s new mail with that address, and the creator’s mailbox alone would leave the record’s history depending on who created it. It runs as a background job, so creating the lead does not wait; Microsoft Graph’s mail calls are not charged per call, and a search per mailbox sits far inside Graph’s limit of 10,000 requests per 10 minutes per mailbox. A colleague’s personal correspondents are kept off records by their block list.

Rev 61 — 2026-10-16 — the database password is not rotated on a schedule

  • Changed — § Deployment Topology › Secrets and § Committed security baseline: the database credentials are no longer “rotated; the mechanism is open as F38’s OQ-K”. RDS keeps managing the master user’s password in Secrets Manager, its automatic rotation is set in Terraform to the longest interval Secrets Manager accepts (or off, if AWS allows that for a secret RDS manages) in every environment, and no restart on rotation is built. The password is changed by hand, followed by a forced new deployment, when a leak is suspected or someone who could read it leaves (.forge/guides/aws-setup-explained.md §7). Planned, not yet applied: the DevOps team makes the change in forge-et-iaac.
  • Why: the lead’s decision of 2026-10-16 (F38 Rev 14, which answers OQ-K). No person has seen the password, it is in neither git nor the Terraform state, and the database is reachable only from inside the VPC, so a scheduled change protects little, while a rotation nothing follows with a restart cuts the backend off. A post-issue note on the proposal (16 October) records the departure from §A.2.3 and §A.4.

Rev 60 — 2026-10-15 — the development account goes without most of the account baseline

  • Changed — § Committed security baseline: in the development account there is no CloudTrail trail (AWS’s free 90-day event history is the record), no root-user protection, account password policy or alternate contacts, and no account-level S3 Block Public Access (each development bucket blocks public access on its own). Development’s Terraform state stays in the management account, and its AWS Budgets are arranged by the DevOps team with Empire Teas. The dns-dev role, the et-ops state bucket and development’s two IAM users stay made by hand, as named exceptions to AD #23; the crm.empire.lk zone is imported into Terraform by F38-i, before production’s records are written. Production keeps the baseline as written.
  • Why: the lead’s decisions of 2026-10-14 and 2026-10-15 (F38 Rev 13): none of these affects building or testing the CRM, and the lead chose not to add work for the DevOps team in development. A post-issue note on the proposal (15 October) records the departure from §A.2.1 and §A.4.

Rev 59 — 2026-10-14 — the staged S3 sync deletes only in a last step of its own

  • Changed — § CI/CD Pipelines (staged S3 sync): the three upload steps no longer say “(all with --delete)”. None of them deletes; a final --delete --size-only sync removes what the build no longer has, and the deploy runs in a concurrency group that never cancels a run.
  • Why: with --delete on the hashed-asset step, the old scripts would go before the new index.html landed, which is the blank page the staged sync exists to prevent; and a filtered sync --delete deletes only what its filter includes, so deleting on the HTML step would never remove old assets. Found while fixing BUG-136 (forge-et-fe#259), which built the sync this way.
  • Not changed: the cache headers and the upload order.

Rev 58 — 2026-10-14 — the development account’s identity and backup exceptions

  • Changed — § CI/CD Pipelines › Cross-cutting, § Committed security baseline, the backups bullet in § Deployment topology: in the development account, one administrator CI user (svc-github) serves forge-et-iaac, forge-et-be and forge-et-fe; the team reaches dev through svc-harness’s access key instead of personal Identity Center logins, with MFA on its console password optional; database backups are optional. Production keeps the rules as written.
  • Why: the lead’s decisions of 2026-10-14 (F38 Rev 9 and Rev 11): going back to the DevOps team for each narrowed identity slows the work, and dev is not where Empire’s live data is kept. The proposal’s §A.4, §A.2.3, §A.5 and §A.6.3 are departed from in development only, recorded in the proposal’s second post-issue note of 14 October.

Rev 57 — 2026-10-14 — development runs around the clock until development is complete

  • Changed — § Deployment topology (the AWS environments bullet): development is no longer scheduled off outside working hours while development is under way.
  • Why: the team runs work against dev overnight. The lead decided on 2026-10-14 (F38 Rev 10, which defers FR-16) that dev runs around the clock until development is complete, and then is scaled down, scheduled off or decommissioned.
  • Commercial: the proposal’s §A.2.1 promised the schedule, so a post-issue note on it records the departure. Dev costs about USD 62 a month as built, against the cost annexe’s USD 34 (environments-and-identity.md §4 “What dev costs”; the annexe is to be re-derived, .forge/owed.md).

Rev 56 — 2026-10-12 — every app repo has a Slow lane, and the local record is a required check

  • Changed — § CI/CD Pipelines: the frontends’ pr-validation runs Vitest in a Slow lane job again, with the backend’s condition; the local record in all three app repos is the required Test record commit status, set once per PR after the last push, instead of a Fast-lane step that read the record comment; the bootstrap paragraph and the required-checks bullet say so.
  • Why: recording before every push to a ready PR ran the suite again for each review fix; one lane shape in all three repos. Lead sign-off, Tharinda, 2026-10-12 (.claude/rules/git-conventions.md § The test suites run locally, and the PR records them).
  • Not changed: the Fast lane and Slow lane check names, the deploy workflows and AD-O-11’s two post-deploy tiers.

Rev 55 — 2026-10-12 — the frontends’ unit and component tests leave PR CI

  • Changed — § CI/CD Pipelines: the forge-et-fe pr-validation row’s triggers become every PR, a push to release/*, a nightly run on main (skipped when main has not moved) and on demand; Vitest runs on the nightly run, release/*, Dependabot PRs and on demand, and on a ready PR into main or release/* the Test record step checks the PR’s local test record (pnpm test:record) instead. The forge-et-pwa sentence (“the same three workflows”) covers it.
  • Why: GitHub Actions minutes; lead sign-off, Tharinda, 2026-10-12 (.claude/rules/git-conventions.md § The test suites run locally, and the PR records them, coding-standards.md §7.1).
  • Not changed: the Fast lane check name, the deploy workflows and AD-O-11’s two post-deploy tiers.

Rev 54 — 2026-10-11 — the capture app keeps and retries failed uploads instead of queuing offline

  • Changed — § Trade-Show Capture App: the PWA caches its shell so it opens with no signal, and keeps a capture whose upload fails, sending it again when the app is open with a connection. There is no background sync or offline queue.
  • Why: the lead dropped F36-e on 2026-10-11 (PRD Rev 64); F36-a carries the retry.

Rev 53 — 2026-10-11 — global search is dropped

  • Changed — § Search: rewritten. There is no global search; each list endpoint keeps its own q filter. The PostgreSQL full-text search design is withdrawn.
  • Changed — § Open Decisions: AD-O-2 is closed as no longer needed.
  • Why: the lead dropped F31 on 2026-10-11 (PRD Rev 60): each list screen carries its own search, and the revised app frame has no top bar for a global box.

Rev 52 — 2026-10-09 — GuardDuty is not enabled

  • § Committed security baseline, the virus-scanning row and AD-O-4: GuardDuty is left out — both Malware Protection for S3 and account-wide threat detection. Altrium management (Thilina, with Malinda) decided on 2026-10-09 to go without it and to add it only if it is needed or Empire Teas asks; Tharinda told Shyamin Ayesh the same day.
  • What runs instead: every environment sets F38-j’s ET_FILES_SCAN_PROVIDER=none with ET_FILES_SCAN_OFF_ACKNOWLEDGED=true, so each upload is stored NOT_SCANNED, downloadable, audited (attachment.scan_skipped) and counted, and FS-11’s type and size validation still apply. Dev has run this way since its first deploy.
  • Not changed: the code. F38-c’s GuardDutyFileScanProvider and the scan-result consumer stay on main, unused, so adding GuardDuty later is Terraform plus two settings. The FileScanProvider seam is unchanged.
  • Commercial: the proposal lists GuardDuty in §A.2.2 and §A.4, and the client-facing PRD says uploads are virus-scanned, so Empire Teas is told before production and the proposal carries a post-issue note (.forge/owed.md). F38 Rev 7 carries the change into the cloud bring-up.

Rev 51 — 2026-10-02 — the database engine is PostgreSQL 18

  • § Weekly Bulk Pricing Subsystem and § Links to Repo-Level Design Docs: the engine is PostgreSQL 18, not 17. FS-2 had recorded 17 with a trigger to re-check against 18 once the AWS account existed (FS-2 spec Constraints, Q-12). It fired on 2026-10-02: RDS has offered 18 since November 2025, its standard support runs a year longer (28 Feb 2031), and the lead chose it. Local, the Testcontainers suite and the pricing proofs moved together (forge-et-be#146); the proofs pass unchanged on 18.6. No RDS instance exists yet; the pin lands in forge-et-iaac (register §B FS-2 row).
  • Not changed: the schema. It still uses no version-specific feature (FS-2 NFR-3) — EXCLUDE USING gist rather than 18’s WITHOUT OVERLAPS — so the next major upgrade stays as cheap. Rev 22’s verification line keeps “17.11” as the record of that run.

Rev 50 — 2026-10-02 — CI reaches AWS through a service user per account, not GitHub OIDC

  • § CI/CD Pipelines › Cross-cutting: the first bullet changes from “AWS access by GitHub OIDC → IAM role. No static keys anywhere” to an IAM service user per workload account with its access key held as a GitHub secret: a deploy user for the app repositories and a Terraform user for forge-et-iaac, keys created outside Terraform, held as Environment secrets in the app repositories, and rotated at least every 90 days. People and the backend keep no static keys.
  • Why: Shyamin Ayesh, who builds the accounts, confirmed this setup on 2026-10-02, and the delivery team chose to follow it (.forge/discovery/meeting-notes/2026-10-01-aws-setup-shyamin.md § Confirmed with Shyamin after the call, D-2). Recorded as F38 spec Rev 4, which is the requirement. The proposal’s “no long-lived keys for people” (§A.4) is unaffected.
  • Not changed: the Environments, concurrency and build-time-config rules; § Committed security baseline (Identity Center with MFA for people).

Rev 49 — 2026-09-30 — the cache policy for static files without a content hash

  • § CI/CD Pipelines (staged S3 sync): the “other static files” step now has a stated cache policy, max-age=0, must-revalidate. They are the files copied from public/ under fixed names; the favicon change (forge-et-fe#89, forge-et-pwa#39) added the first such icons to the CRM, and an immutable header would keep a changed icon cached for a year. Registered as a §B FS-1 row in .forge/cloud-gated-validation.md, because the sync step is not built yet.
  • Not changed: the hashed-asset and HTML policies, and the upload order.

Rev 48 — 2026-09-29 — the Terraform lives in forge-et-iaac

  • § Infrastructure as code and § CI/CD Pipelines (terraform workflow): AD #23’s location is revised — all Terraform and other DevOps work lives in a separate repository, altrium-io/forge-et-iaac (created empty on 2026-09-29), not in forge-et-be/terraform/, which was never created. The terraform plan-on-PR / apply-on-merge workflow moves with it.
  • Not changed: everything else in AD #23. How the delivery team reviews changes in the new repository, and which delivery-repo conventions it takes on, are answered from Shyamin Ayesh’s setup.

Rev 47 — 2026-09-29 — Empire Teas holds the AWS account; four developers; the revised schedule

  • § Open Decisions: AD-O-10 re-resolved — the AWS account is Empire Teas’ own and AWS bills them directly; SOW ET-002 (Rev 36’s resolution) is superseded and was never signed. The Rev 36 entry below stays as written.
  • § Resource & Timeline Reality: team capacity is four full-stack developers (Nanndish Satgunarajah joined), with no fixed lanes.
  • § UAT deploys are deferred, deliberately: the settle-by for the first UAT environment moves from 2 Nov to 30 Nov, the start of the Phase 1 UAT round in the revised Statement of Work (.forge/client/project-timeline.md).
  • § Resource & Timeline Reality › Delivery window: annotated with the revised Statement of Work’s dates, which replace §7’s indicative window.
  • Not changed: the estate’s shape, AD #4’s one account per environment (whether dev and prod become member accounts under an AWS Organization is answered from Shyamin Ayesh’s setup), and AD #23’s Terraform location, which waits on the same setup.

Rev 46 — 2026-09-29 — the browser gate’s CI step, and the frontends’ one lane (F40)

  • Changed — § CI/CD Pipelines: the forge-et-fe pr-validation row gains the Fast lane’s last full-run step, node scripts/browser-gate.mjs ci-check, which reads the PR’s current description with pull-requests: read and runs no browser; the forge-et-pwa sentence says the same. § Browser E2E runs in two CI tiers gains one paragraph: every ready app-repo PR is gated locally by pnpm e2e:gate. The “Bootstrapped ahead of Foundation” paragraph and the § Cross-cutting required-checks bullet no longer say the app repos have two lane jobs: forge-et-be has Fast lane and Slow lane; forge-et-fe and forge-et-pwa have one Fast lane job since forge-et-fe#76 and forge-et-pwa#30 (2026-09-28).
  • Why: F40 spec FR-13 and Rev 2; the job removal is recorded in git-conventions.md § Branch Protection.
  • Not changed: AD-O-11’s two post-deploy tiers, which stay with FS-1’s cloud half; the deploy workflows.

Rev 45 — 2026-09-27 — AD #37: a grant has no scope

  • Changed — § AuthN / AuthZ: the permission-model bullet stores (role, permission_key) grants and states reach from the reporting hierarchy plus the <entity>.all key; the ownership bullet restates reach without own / team / all and names F5-l as the feature F5-f builds on; § Global search cites the rule by its new name; the AD #15 row of the Architecture Decisions mirror gains its AD #37 refinement.
  • Why: AD #37 (lead decision, 2026-09-27; PRD Rev 43).
  • Not changed: the catalog shape of AD #34 otherwise, sharing (AD #35), the audit trail (AD #36), the seams.

Rev 44 — 2026-09-27 — doc-drift corrections from the second harness review

  • Changed — § AI data-handling boundary: the “nothing is sent automatically in the background” sentence is replaced — system-run AI (research, triage, briefings) runs as background jobs on minimum data (AD #32, PRD Rev 30); user-invoked AI runs when triggered; no AI output is committed without a person. The divergence from proposal §A.6.1 is stated in the proposal’s 27 September post-issue note (lead decision).
  • Changed — § API conventions and § Links to Repo-Level Design Docs: the worked example is GET /api/v1/buying-standards (BuyingStandardController), which replaced the products example at FS-15.
  • Changed — § Trade-Show Capture App: the POC is described as API-integrated with a reference-only backend, not “hardcoded data, no backend” (L-005).
  • Changed — § CI/CD Pipelines table and the § Foundation Backlog FS-4 row: the Trivy gate flips when all three app repos read 0 HIGH/CRITICAL (AD #27, FS-4 spec Rev 3), not “at Phase 2”.
  • Not changed: any AD, any scope, the AI governance invariant.

Rev 43 — 2026-09-27 — the network layout: no NAT, public-subnet tasks, private database

  • Changed: § Deployment Topology gains a Network bullet. There is no NAT gateway. The backend tasks run in a public subnet with a public IPv4 address and a security group that admits only the load balancer. The database is in private subnets and admits only the tasks. The bullet also notes that anything running in the VPC without a public IP needs its own interface endpoint.
  • Why: the lead’s decision while the F38 spec was drafted (2026-09-27, .forge/specs/F38/cloud-bring-up-spec.md § Context, decision 3). It keeps proposal §A.2.1’s “no NAT gateways” at the lowest cost. Until now the subnet layout was recorded nowhere, so later specs and plans had no design entry to cite.
  • Also changed — § Deployment Topology › Secrets: “DB credentials (RDS-managed rotation)” becomes “rotated; the mechanism is open as F38’s OQ-K”. Without a NAT gateway, RDS-managed master-user rotation and a rotation Lambda for a separate user have different network and restart consequences (F38 spec FR-10).
  • Impact: F38-b’s Terraform follows the bullet. The database-secret rotation mechanism is open as F38’s OQ-K. Whether proposal §A.6.2’s “from the private network” wording needs a post-issue note is F38’s OQ-G.

Rev 42 — 2026-09-24 — access, ownership and sharing, and the audit trail (AD #34, AD #35, AD #36)

  • Changed — § AuthN / AuthZ: the roles bullet names the six as the recommended set, none predefined, with the Managing Director’s approval met by configuration (quote.approve_sub_floor). New Users bullet: sign-in needs an active, pre-created user; no auto-provisioning or invitation; an email change clears the identity link; users are deactivated and reactivated, never deleted; deactivation deletes the user’s Spring Session JDBC rows by the principal-name index, and is refused for oneself, for the last access.manage holder, while the user has direct reports and while they own records (F5-c); no Entra sync, with Empire’s Entra disable as a backstop. The permission-model bullet is rewritten to AD #34’s minimal catalog (view / manage per entity, manage implies view, the special keys, one unscoped access.manage), with no category axis, no superadmin, no is_system, no * grant, the Flyway-seeded IT Admin role and user (F5-k), and the last-admin invariant at its four points; core.app_user.manager_id loses its stale schema qualifier and OQ-56’s hierarchy questions are answered. New bullets: permission changes take effect on the next request (grants re-read every request, no cache; the frontend re-reads /me after a 403 and on window focus), ownership, sharing and one visibility rule in auth.access for lists and per-record checks (AD #35, built by F5-f), and a minimal user directory for pickers. The enforcement bullet names the keys instead of “Admin/Tea-Room-only”.
  • Changed — § CSRF and session hardening: deactivation deletes the user’s session rows; a permission change ends no session.
  • Changed — § Mailbox integration, § Rate limiting, the System Context diagram and the F20 row of § Build Feasibility: info@ is handled by forwarding in V1; there is no unowned MailboxConnection and no shared-mailbox rate bucket; F20-e has left V1 (lead decision, 2026-09-24).
  • Changed — § Audit trail: rewritten to AD #36 — one audit_event table and service, written in the same transaction as the change, covering every write and the named security events, not reads, kept indefinitely, no viewer screen in V1, a SYSTEM actor; created_at / modified_at on every table (F39).
  • Changed — § Search, § Feature flags, the pricing table’s publisher row, AD snapshot row 15 and the FS-6 backlog row: search filters through the one visibility rule; AI features switch per feature under settings.manage, not per role; publishing is price.publish by configuration; row 15 and FS-6 carry an AD #34 pointer (FS-6’s row keeps what shipped and names F5-k as the realignment).
  • Why: the lead’s access-model decisions of 2026-09-22 to 2026-09-24. Full rationale: .forge/engagement-log.md § AD #34, AD #35, AD #36.
  • Not changed: AD #5’s server-side sessions, AD #26 (a check names the permission), AD #28 (Microsoft-only sign-in), the CSRF cookie design of AD #33, and the AI governance invariant. Earlier revision entries that describe the category axis, the superadmin or the shared mailbox record their own time and stay as written.
  • Impact: new features F5-k (catalog collapse, seeded IT Admin) and F39 (audit trail); F5-f re-scoped to the ownership and sharing substrate; F5-c and F5-d re-scoped; F20-e dropped from V1. Cloud-gated items for the seeded admin are in .forge/cloud-gated-validation.md §B F5-k.

Rev 41 — 2026-09-24 — the apps call the backend cross-site (AD #33)

  • Changed: §Deployment Topology’s Compute bullet gains the AD #33 sentence: the backend keeps its api.* address; the apps call it cross-site with credentials, a per-environment CORS list, and a shared-domain XSRF-TOKEN cookie whose name differs per environment.
  • Why: the cross-host cookie decision (register A-4) was open; the lead chose it over routing the backend through each app’s CloudFront. Full rationale: .forge/engagement-log.md § AD #33.
  • Impact: the Entra reply URLs stay on api.*; a small cookie change is owed in the backend and the frontend, tracked as F5-j; per-environment values are in the register’s §D.

Rev 40 — 2026-09-23 — the capture stream runs alongside Phase 2, not weeks 8–13

  • Changed: §Trade-Show Capture App’s Scheduling line. “weeks 8–13” becomes alongside the Phase 2 work (weeks 7–13), where Gate 3 (2026-09-17) placed F36 with its scope unchanged, and the line names the Fri 13 Nov descope checkpoint.
  • Why: PRD Rev 35 makes the same correction; project-timeline.md §2 schedules the stream alongside Phase 2.
  • Not changed: AD #20’s scope, the parallel-stream shape and the descope lever. Earlier revision entries below that say “weeks 8–13” or “week 8” record their own time and stay as written.

Rev 39 — 2026-09-23 — the Graph subscription expiry is seven days, not three

  • Changed: §Mailbox integration’s “expire in ~3 days” becomes the documented ceiling — 10,080 minutes, at most seven days for Outlook message/event/contact subscriptions — and points at MailboxSubscriptions.MAXIMUM_EXPIRY, the constant F20-a pinned, rather than restating a figure that can drift from the code again. The 1,440-minute cap for subscriptions carrying resource data is noted; F20 requests none. Nothing else in the section moves: renewal stays mandatory, the lapsed-subscription alarm stays, push stays primary with the delta poll as the safety net.
  • Why: F20-a established the real figure from Microsoft’s documentation on 2026-09-22 and pinned it in code, but never wrote it back here. F20-b’s spec then reproduced the stale “~3 days” in good faith — and used it as the load-bearing argument for deferring a subscription-reconciliation pass, where an orphan window of three days versus seven is the whole question. Its Pass-3 review caught it. The same figure is corrected in PRD risk R-12 in the same change, and in the two further copies found immediately afterwards — discovery/research/m365-mailbox-integration.md (a derivative that named this section as its authority and then restated the number) and the F20-b tracker.yaml note. This entry first said R-12 was “the only other copy”, which was itself a copied claim and was wrong; four copies existed.
  • How it was found: /forge-spec-review on .forge/specs/F20-b-inbound-sync-inbox-spec.md, which verified the claim against forge-et-be rather than against this document.

Rev 38 — 2026-09-22 — the mailbox section stops restating the test-account count

  • Changed: §Mailbox integration’s client-dependency pointer no longer says “three test accounts”; it names design/environments-and-identity.md §5 as the authoritative list. Nothing about the integration design moves — separate grants, envelope-encrypted refresh tokens, per-user scoping all stand.
  • Why: five accounts are provisioned (CRM01–05@empire.lk), and a count copied from another file goes stale silently (the NEVER-DO in .claude/CLAUDE.md). Raised as signal W-1 by F20-a’s gap-check; the spec resolved it for itself and deferred the older documents to “when next touched”.
  • Not changed: Rev 7’s alignment-sweep line keeps its “three test accounts” wording — a revision log records what was true when written, and correcting it would falsify the history.
  • Impact: documentation only.
  • Approved by: (owed — the approval of the F20-a harness PR carrying this revision)

Rev 37 — 2026-09-15 — the products catalog is removed; the Buying Standard is the sellable record (PRD Rev 27)

  • § Weekly Bulk Pricing Subsystem: the standard is now the sellable record for bulk and private label — the N:1 Product/grade edge and the “bulk only — must not leak into private-label quoting” row are replaced; the weekly-price workflow attaches to whichever standards are weekly-priced (OQ-61 decides whether private-label standards are; default: quoted per deal). Archive is the standard’s is_active flip — history kept, out of quoting and the weekly round. § Cross-cutting (global search): searches buying standards, not products. § Feature mapping (F9): the held side of the certification check is the standard’s.
  • Why: PRD Rev 27 — a team requirement change, applied to the client-approved prototype in harness PR #88 (2026-09-15): one list instead of two, since every sellable item Empire quotes, bulk or private label, is a client’s standard.
  • Consequence for shipped code (hand-off, Tharinda — AD #31): forge-et-be carries a product table (V3__product.sql), the catalog package (Product, ProductController — FS-10’s worked API example), ListPriceModel, ProductPermissions (product.view / product.manage) and product_id FKs on buying_standard and line_item (docs/data-model.md §2). The data model is revised by its owner; retiring the package, keys and migration is scheduled with F26’s spec or earlier. Nothing else here changes — topology, seams and the pricing subsystem’s temporal design stand.
  • Not changed: AD #14 (effective-dated prices), the AuctionPriceProvider seam, the draft → published workflow, the auction-sale validity anchor.

Rev 36 — 2026-09-13 — AD-O-10 resolved: Altrium owns and runs AWS (SOW ET-002)

  • § Open Decisions: AD-O-10 marked RESOLVED — the managed-cloud-infrastructure SOW (ET-002, ../client/aws-sow.md) has Altrium own and administer the AWS organisation and accounts and bill Empire a fixed USD 650/month (all-inclusive of AWS + AI + managed ops; separate from the USD 360/month app support under ET-001); accounts are not transferred to Empire on exit. This reverses the earlier working assumption (Empire opens/hands over the account); context — Empire is non-technical and its cloud billing is normally run by Dialog, but Empire asked Altrium to run AWS and invoice monthly.
  • § Foundation Backlog (FS-1): the AD-O-10 note carries a superseded pointer; the cloud half (Terraform bootstrap, AD #23) now starts when Altrium stands up the accounts.
  • New reference: ../design/environments-and-identity.md — concrete DNS per environment, the Entra app registration (Client/Tenant IDs, reply URLs, Graph scopes, certificate-based login — client secrets blocked by Empire’s tenant policy), AWS ownership and a Terraform pointer (Ayesh may stand up a separate Terraform repo — pending; AD #23 stands until then).
  • Consequence cascade: CLAUDE.md Active Context + AD-O-10, client/aws-sow.md (new), client/dependencies.md §1.1, client/sow-cost-annexe.md billing model, client/client-facing-prd.md data-governance framing, ai-provider-strategy.md, project-prd.md §Deployment (PRD Rev 25), and a proposal post-issue note. The data-governance story shifts from “Empire’s own account” to “the project’s AWS account, Altrium as processor (SOW §10)” — substance (in-account, no separate AI vendor, isolated) unchanged.
  • No change request: internal ownership/commercial structure governed by SOW ET-002; L-001 governs the proposal’s scope/price/providers, unaffected.

Rev 35 — 2026-09-12 — AD-O-4 closed: virus scanning is GuardDuty S3 Malware Protection

  • § Open Decisions: AD-O-4 struck through and marked decided — Amazon GuardDuty Malware Protection for S3 (managed), enabled by devops via Terraform at environment setup. Chosen over a ClamAV container (no second container per AD #22, least Terraform per AD #23, no signature upkeep) and over a third-party API (ruled out on AD #19’s in-account posture). Behind the FS-11 FileScanProvider seam so ClamAV stays a swap-in. Cost is usage-based, bounded to well under $1/mo at Empire’s file volume; the running-cost annexe line is owed when the cloud half enables it.
  • § System Components > build-vs-buy table: the virus-scanning row’s “implementation choice open” resolved to the same decision.
  • Settled by FS-11 — spec .forge/specs/foundation/011-file-pipeline-spec.md (its OQ-1 recorded the decision). No client-facing or commercial impact (internal infra choice on the already-budgeted GuardDuty base; L-001 governs scope/price/providers, unaffected).

Rev 34 — 2026-09-11 — the role model is simplified (AD #32, PRD Rev 24)

  • § AuthN / AuthZ: the granular-levels bullet now reads three categories — read / edit / execute — with AI not a grantable level (system-run AI is not a permission; user-invoked AI assist is implied by the permission it serves); no role templates ship (only the system superadmin is seeded; Empire’s Administrator creates the six recommended roles); one role per user, so no cross-role union; the release step is “update roles”.
  • Gate-2 AD snapshot row 15 and the FS-6 Foundation Backlog row carry the same refinement; FS-6’s spec Rev 5 is recorded as owed.
  • Why: team decision (Tharinda, 2026-09-11; confirmed by Dinil) to remove complexity nobody had asked for — the template copy/reset mechanism, the multi-role union, and an AI category an Administrator could grant detached from the action it assists. AD #32 in CLAUDE.md.
  • Not changed: the code-declared catalog, (role, permission_key, scope) grants, manager_id and per-permission scope, AD #26, the FS-3 PermissionGuard seam, the human-in-the-loop invariant (now stated as: the AI holds no permission and a person commits every output).

Rev 33 — 2026-09-11 — one price per standard; the capture app gains an account lookup (PRD Rev 23)

  • § Weekly Bulk Pricing Subsystem: the properties table’s market row and the price key change — price is (buying_standard, validity), one price per standard per week; destination market is a customer attribute and a quote field, no longer a price axis. The as-of query loses its market term.
  • § Trade-Show Capture App: the backend surface gains a read lookup of accounts and contacts for the scan-time existing-client check.
  • Why: Empire stated on 2026-09-09 that a standard’s price does not vary between customers or regions, and the weekly price workbook they shared afterwards carries one row per standard per week; the decision was recorded by Dinil on 2026-09-11 (PRD Rev 23, revising the Rev 6 answer to OQ-38). The capture-app additions come from the same meeting.
  • Not changed: effective-dated rows (AD #14), the auction-sale validity anchor, draft → published publication, the AuctionPriceProvider seam, the Tea Room role. Hand-off: forge-et-be/docs/data-model.md §2.2 and the price/snapshot DDL it describes (owner: Tharinda, AD #31). No shipped migration carries the market price axis — FS-2 shipped no pricing DDL — so this is a document-and-spec change ahead of F26.

Rev 32 — 2026-09-10 — the cascade catches the doc up to the merged collapse (AD #31, FS-14)

Rev 31 added the FS-14 row and announced the collapse; this revision is the doc following the merged code.

  • § Core / Domain Separation is reduced from a 126-line design section to a compact historical record — what was built, why, and that FS-14 removed it — carrying a HISTORICAL banner and read entirely in the past tense. The module-layout diagram, the extension-point table, the enforcement table and the entity-extension DDL are dropped (they live in git history and in the FS-1/FS-2 specs); the still-live guardrails (AI prompts in one place per P-21; not multi-tenancy; the typed-extension entity model as data-model design; rule of two) are preserved.
  • The pr-validation CI rows (backend and frontend) drop the removed boundary / banned-vocabulary / FK-direction / package-boundary checks and state the surviving hygiene guards and the src/{app,features,ui,lib} folder rules.
  • Foundation Backlog FS-1 / FS-2 / FS-3 rows are annotated past-tense (pre-FS-14 wording; the split is collapsed — Rev 32); the Gate-2 candidate-snapshot AD #17 row points at CLAUDE.md’s authoritative AD chain (17/29/31). Prior revision entries (Rev 5, 22, 29, …) keep their dates and substance; only incidental package-name literals are described rather than named, so the doc reads clean.
  • Not changed: any product commitment, the deployment topology (always one ECS service), or the entity map’s relationships. Approved by Tharinda, 2026-09-09 (the AD #31 lead sign-off).

Rev 31 — 2026-09-09 — the core/domain split is collapsed (AD #31, FS-14; supersedes the “stays in place” half of AD #29)

  • Changed: Foundation Backlog gains FS-14 — Single-module structure (spec .forge/specs/foundation/014-single-module-spec.md): the backend becomes one Gradle module with feature-first packages, one public schema and a squashed migration sequence; forge-et-fe one package laid out src/{app, features, ui, lib}; forge-et-pwa mirrored with a shared-file drift check; the split’s guards retired, every hygiene guard kept, FS-10’s layering rule relocated, a feature-cycle rule added. FS-8’s row now promises the package layout and hygiene guards rather than the module layout and boundary guards. This revision records the decision only — § Core / Domain Separation, § Module layout and the FS-1/FS-2/FS-3 row texts still describe the pre-collapse build and are rewritten or annotated by the FS-14 cascade revision once the code PRs merge.
  • Why: AD #29 stopped extending the split but kept its scaffolding as cheaper than removal. Opened up on 2026-09-09 the scaffolding proved to be mostly empty shells (13 of 16 backend modules, 2 of 3 frontend packages) and the substance moves rather than rewrites, while keeping it would tax every feature for a payoff already declared gone. Nothing is deployed or migrated, no feature code exists and Gate 3 has not run — the cheapest moment there will ever be. Lead sign-off: Tharinda, 2026-09-09. No change request (internal structure — L-001).
  • Not changed: every product-facing commitment; AD #29’s cancellations (FS-12/FS-13) and its first-consumer rule for the workflow primitives; P-21 (AI prompts kept in one place — the ai package once it exists); the entity map’s relationships (only its schema qualifiers change, in the cascade); the two CI job names.

Rev 30 — 2026-09-07 — role management becomes fully configurable, with a reporting hierarchy (AD #30, refines AD #15)

  • Changed: § AuthN / AuthZ’s granular-levels bullet now describes the configurable model — a code-declared permission catalog (<resource>.<action> keys, ~100–150, each carrying category / label / description / UI group / scope-aware metadata), (role, permission_key, scope) grants as data, admin-authored roles with the six confirmed roles as copy-on-create templates, core.app_user.manager_id as the reporting hierarchy behind own / team / all scope set per permission, roles unioning to the most permissive grant, and the slice-level consequences (fail-closed new keys → “update roles and templates” release step; orphan-grant check; non-deletable superadmin + last-admin protection). The AD #15 row in the Gate-2 candidate snapshot is annotated as refined. Foundation Backlog FS-6 row restated to the new model and marks spec Rev 3 as owed.
  • Why: Empire asked for a fully configurable role-management system (2026-09-07; PRD Rev 21). The four levels stay load-bearing as category metadata — the ai-use-vs-execute split is what makes human-in-the-loop structural — and are more visible there than as a grant column. AD #26 is unchanged and strengthened: every check names a permission key. Treated as a V1 requirement — no change request (Dinil, 2026-09-07); the divergence from proposal §3.2’s quoted access model is recorded as a post-issue note on the proposal header (L-001: stated, not silently absorbed). Lead sign-off: Tharinda, 2026-09-07.
  • Not changed: the six roles as confirmed, the pricing floor and AI invariants, the FS-3 PermissionGuard seam (Decision 13’s PermissionDecision union is agnostic to how the backend computes a decision — only FS-6’s /api/me half moves), enforcement at the service layer, and the CSRF/session section. No spec or plan is touched — FS-6 Rev 3 is a separate task. Multi-office data partitioning remains deferred; the reporting hierarchy is an org chart, not an office wall.

Rev 29 — 2026-09-07 — the core/domain split is no longer extended (AD #29, supersedes AD #17)

  • Changed: § Core / Domain Separation carries a superseded banner and now reads as the record of what FS-1/FS-2 built; the extension-point table notes that no substrate is built for it; the rule-of-two and OQ-50 guardrails are annotated. § Foundation Backlog: FS-12 and FS-13 are dropped before start (rows kept as the record, ids retired), the footnote and FS-8’s row updated. § Resource & Timeline Reality’s estimate bullet notes the drop without re-running the band.
  • Why: AD #29 — the split’s return rested on OQ-50’s assumed reuse of the generic layer on future projects; that reuse is no longer expected, so the ~+8–15% of V1 it costs has no payoff and the unstarted remainder is cancelled. The cost paid in FS-1/FS-2 is sunk and argued neither way. Stop-extending was chosen over collapsing (one module tree, one schema, the tea schema migrated into the generic one) because the collapse is a real refactor on already-migrated schema with no payoff of its own; the modules, schemas and four guards therefore stay physically in place and green. Trade-offs, the open F26 data-model ownership and the lead sign-off are recorded on AD #29.
  • Not changed: the module layout, package roots, schema separation, Flyway partition and enforcement table — they still describe the build as it is. No spec, plan, migration or arch test is touched: shipped artefacts record what was decided at the time.

Rev 28 — 2026-09-04 — login narrows to Microsoft-only (AD #28)

  • Changed: § Identity & Access > Login — one credential path: Microsoft (Entra ID) OAuth2 only; Google OAuth and local email/password dropped (AD #28, refining AD #5’s login half — the session model stands). The mailbox-consent bullet reworded (login OAuth ≠ Graph consent, unchanged in substance). § Deployment/Secrets now names one OAuth client secret. Foundation Backlog FS-6 row updated to the Microsoft-only shape + the profile-scoped local/test stub login, and now links the approved spec (Rev 1).
  • Why: team decision 2026-09-04 — Empire is all-M365 (OQ-24/AD #16), so the local fallback protected nobody real; dropping it removes the CRM’s entire credential-storage/reset/lockout surface. Trade-offs recorded on AD #28 (no local break-glass during an Entra outage; the Entra app registration becomes the sole login path’s hard external dependency — FS-6 spec Q-6).

Rev 27 — 2026-09-03 — the API-contracts row flips to created (FS-10 FR-D3)

  • Changed: § Links to Repo-Level Design Docs’ API-contracts row, from “not yet created (Foundation slice 10)” to created, naming the five documents (README.md with the adding-an-endpoint checklist, versioning.md, collections.md, errors.md, payloads.md) and the OpenAPI document the application serves at /v3/api-docs; § API conventions gains the same pointer plus the worked example (GET /api/v1/products — ProductController + ProductCollectionDefinition). Retiring with the product entity (Rev 37); a replacement example is owed.
  • Why: FS-10’s spec FR-D3 names these two one-line edits as the harness companion to the backend’s docs/api/, and its plan’s Decision 2 schedules them on the slice’s closing harness PR so this document claims the directory exists only once it does. The design-system spec’s Rev 9 records the settled pagination shape from the consumer’s side.
  • Not changed: § Foundation Backlog’s FS-10 row (Rev 24) — it stays as the record of what the slice was asked to hold; both seam commitments it carries are now met.

Rev 26 — 2026-08-31 — the dependency-vulnerability scanner is Trivy (AD #27)

  • Changed: the four places this document named OWASP Dependency-Check as the dependency-scan tool — the CI/CD deploy-shape overview, the pr-validation pipeline row, the external-dependency selection table, and § Foundation Backlog’s FS-4 row — now name Trivy, with the gate stated as it actually enforces: HIGH,CRITICAL ≡ CVSS ≥ 7.0, report-only until the Phase 1→2 flip (FS-4 spec Rev 1), governed per-repo .trivyignore.yaml. The FS-4 row also now covers all three app repos for the scan, matching FR-O1.
  • Why: FS-4 subtask 5 measured OWASP DC unable to scan the pnpm frontends (0 npm coordinates from node_modules; 1 dependency from its experimental lockfile parser), which made AD #9’s “one tool uniformly across Java and Node” unsatisfiable with the named tool. The empirical re-evaluation and verdict are 004-scanner-tool-analysis.md → AD #27 + FS-4 spec Rev 2; AD #9’s intent (uniform gate, configurable ≥ 7.0 threshold, governed suppressions with justification + expiry) is preserved verbatim.
  • Not changed: the point-in-time records — the FS-4 plan’s approved Decisions 10–13 and the pre-swap Progress entries keep their DC wording (the plan’s ## Notes records the deviation); engagement-gate-runs.md and the issued proposal’s §A tool table are frozen (the proposal carries a post-issue note instead).

Rev 25 — 2026-08-29 — FS-3’s repo scope widened to both frontends at spec approval

  • Changed: § Foundation Backlog’s FS-3 row now covers both frontends (previously <frontend-repo> alone): <capture-repo> receives its own copies of the token contract + breakpoint module (the shared UI library the named source of truth, the copies held identical by the spec’s cross-walk check), the token rename + Empire theme file, the fixture-import dependency-cruiser rule and check-testid-coverage.mjs. The POC screens’ remap onto the tokens stays F36 capture-stream work (design-system open item 5). The row also clarifies that its “Layout” component reads as the layout/* token family + breakpoint module, not frame chrome — the §6 app frame defers to the first screen-shipping feature (spec Q-5), and it now links the approved spec, matching the FS-1 row.
  • Why: the approved FS-3 spec’s Q-1 surfaced that three documents already committed the capture app to this slice — test-strategy.md § Toolchain lists both repos on the FS-3 tool rows, the FS-1 spec’s deferral table sends “the capture retheme” here, and the design system’s swap-one-file reskin only holds if the rename lands in both frontends. The backlog row was the one place still saying frontend-only; same widening-at-the-row precedent as FS-1 (Rev 21).
  • Not changed: AD #20’s weeks 8–13 capture feature stream and F36’s scope — this is the pwa shell’s token layer only.

Rev 24 — 2026-08-28 — FS-10’s row carries the design system’s two API seam commitments

  • Changed: § Foundation Backlog’s FS-10 row now states the two constraints the design-system spec committed the API to in its Rev 2–3 (PR #28): offset/numbered pagination with a known total (F32’s data-table UI paginates as 1–25 of 340 with bulk selection over stable page boundaries — a cursor-only API cannot serve it), and confidence (0–100) + source on every AI-produced payload (the §5 four-element AI-provenance rendering is unbuildable without them).
  • Why: both commitments were recorded only inside design/ui/design-system.md — a frontend-facing document the author of a backend API-conventions slice has no reason to open. A cross-repo commitment lives where its consumer reads, or it surfaces as a surprise at build time. The design-system spec’s Rev 6 records the same move from its side, so the two documents cannot silently diverge on who committed what.
  • Not changed: the FS-10 slice’s scope and sequencing — these are constraints on decisions FS-10 was already going to make, not new work.

Rev 23 — 2026-08-21 — the spike-closure cascade Rev 22 missed

  • Changed: § Build Feasibility & High-Risk Requirements’ bulk-pricing row, which Rev 22 left describing SP-ARCH-003 as an open spike — with the superseded (standard × market × week) key and an instruction to reconcile the research doc, now exactly the wrong instruction. It now reads as resolved and points at <backend-repo>/docs/data-model.md §2, matching how the same table records SP-ARCH-001 and SP-ARCH-002 standing down.
  • Why it was missed: Rev 22 updated the subsystem section and the entangled-entity list, which is where a reader looking for the design goes. The feasibility table is where a reader looking for what is still unresolved goes, and it is the one a stale entry misdirects. Two places state a spike’s status; both have to move together.
  • Also changed: § Weekly Bulk Pricing Subsystem said the research doc’s §7 schema is “superseded in four places”. That is a tally of another document’s contents — the data model owns the reconciliation table and can add a row to it any time — so the count is dropped and the pointer kept. Same rule as the standing prohibition on copied counts; Rev 22’s own entry keeps the number, because a revision entry records what was true when written.
  • Not changed: the point-in-time records — engagement-gate-runs.md’s “Spikes scoped” table and the resolved_spikes[].description in tracker.yaml keep their original wording, including the old price key. Rewriting them would falsify what was scoped at Gate 2 Run 2.

Rev 22 — 2026-08-21 — SP-ARCH-003 resolved; the pricing schema lands in the backend repo

  • Changed: § Weekly Bulk Pricing Subsystem now points at the settled schema in <backend-repo>/docs/data-model.md §2 instead of at the research doc as a candidate. The price key is restated as (buying_standard, market, validity) with validity anchored to a numbered auction_sale row — the previous effective_week wording implied a calendar week, and the research doc carries a verified refutation of fixed auction weekdays, so “the next auction” is not derivable from a weekday or ISO week.
  • Added: LineItem to the list of entangled entities carrying a typed 1:1 extension table. A bulk quote line’s price provenance points into the tea schema, so it cannot live on the generic line-item table without the cross-schema FK that AD #17 forbids and CI rejects. This was latent — it would have surfaced as a red CI check partway through F26 implementation.
  • Superseded: bulk-tea-pricing.md §7’s DDL, in four places — the priced unit (Buying Standard, not Product), currency/Incoterm leaving the price key, the provenance FK’s home, and cost moving to its own grain. Its domain half stands. The reconciliation table is in the data model, so the research doc is no longer a schema source.
  • Verification: the schema is proven rather than asserted — an assertion suite plus the AD #17 “core alone is a working generic CRM” acceptance test, on PostgreSQL 17.11, reproducible from the backend repo and gated by a bidirectional check that the document and the executable scripts have not drifted apart.
  • Not changed: AD #14 (effective-dated rows), the AuctionPriceProvider seam and its never-auto-price rule, the Tea Room publication workflow, and the FS-2/F26 substrate split — all confirmed by the exercise rather than revised.

Rev 21 — 2026-08-20 — FS-1 covers all three app repos; the capture shell is scaffolded now

  • Changed: § Foundation Backlog FS-1 now scopes to three repos — <capture-repo> joins the backend and frontend. Developer decision 2026-08-20: an empty repo is cheap, the POC exists to port from, and scaffolding all three in one pass shares the conventions work (repo CLAUDE.md, .editorconfig, husky/lint-staged/commitlint, Dependabot, CI lanes) instead of repeating it in November against a colder context.
  • AD #20 is unchanged. The capture app remains a weeks 8–13 parallel work-stream at full scope; what moves earlier is only its shell — Vite/React/pnpm scaffold, PWA manifest and service worker, routing skeleton, slice-1 toolchain. No capture feature (camera/QR capture, card reading, offline queue, notifications) is pulled forward; those stay F36.
  • Why now: the AWS account gates FS-1’s cloud half and nothing in its non-cloud half, so the whole scaffold is available work during the pre-account window. The FS-1/FS-3 seam is stated explicitly in the spec: the frontend workspace packages are created empty-but-wired at FS-1, their contents and the dependency-cruiser boundary rules stay at FS-3.
  • Also: the stale header Last updated pointer corrected — it read Rev 11 while the log had run to Rev 20.
  • By: Tharinda (with Claude) — scope-of-slice change within an approved architecture; no design decision reversed.

Rev 20 — 2026-08-20 — CI/CD section aligned to the bootstrapped workflows

  • State-reconciling, no design change. The app repos’ PR-validation CI was bootstrapped ahead of Foundation slice 4 so its two check contexts (Fast lane, Slow lane — the §7.1 lanes) could be made required ruleset checks while temporary repo-admin access was available; §CI/CD Pipelines now records the bootstrap and names the workflow pr-validation (was pr-validate in the tables — the shipped name wins).
  • deploy-dev rows gain a manual workflow_dispatch trigger alongside push-to-main (team decision 2026-08-20: dev must be re-deployable without an empty commit).
  • pr-validation triggers stated precisely: every PR whatever its base (hotfix PRs to release/* included) plus pushes to main and release/*.
  • Harness row: repo-hygiene gains the gitleaks secret scan (the §7.7 layer — the paid GitHub push-protection add-on was decided against, 2026-08-20).
  • §Cross-cutting extended after a pipeline review of an existing production set of the same AWS/GitHub-Actions shape: deploys never cancel in-flight (cancel-in-progress: false); frontend deploy jobs assert non-empty build-time config before building (a renamed Actions variable evaluates to empty string and ships silently otherwise); staged S3 sync with HTML last; build/deploy job separation so AWS credentials never coexist with package-manager lifecycle scripts; paths-ignore on deploy triggers; persist-credentials: false standard; action pins on current majors with Dependabot’s github-actions ecosystem keeping them moving; the stale “add required checks at slice 4” bullet corrected — checks are required from the 2026-08-20 bootstrap.

Rev 19 — 2026-08-19 — capture app folded into the PRD as F36 (OQ-48 resolved)

  • Changed: § Trade-Show Capture App intro note — the record-level gap is closed: the app is F36 in the PRD (Rev 13), so the section no longer describes itself as design-closing an open scope record. Section content unchanged.
  • By: Tharinda (with Claude) — state-reconciling only; architecture remains approved.

Rev 18 — 2026-08-19 — capture-app POC published as a read-only sibling repo

  • Changed: § Trade-Show Capture App — the working prototype is now published as forge-et-pwa-poc, cloned as a sibling with the other four repos (team-guide.md § Repos on This Project). The prototype bullet now names what the POC contains (exported PWA frontend, its own docs set, pitch prototypes) and its trust posture: read-only input material — port into forge-et-pwa, never write to it; this document and the proposal win on any disagreement.
  • Why: the capture stream starts from the POC, and the harness previously described the prototype with no location a team member could open.
  • By: Tharinda (with Claude) — additive/state-reconciling; architecture remains approved.

Rev 17 — 2026-08-19 — FS ids stamped; Micrometer Tracing named at FS-5

  • Foundation slices carry their ticket ids in place — the Backlog table’s # column is now Id (FS-1…FS-13), matching git-conventions.md § Ticket IDs; tracker.yaml setup.foundation.slices[].id renamed from the older F-001 style, which was one hyphen away from the feature ids (F1…) in a branch name.
  • FS-5 (Observability stubs) names the tracing mechanism: Micrometer Tracing (micrometer-tracing-bridge-brave) — traceId/spanId stamped into every log line via the MDC; request threads auto-instrumented by the dependency alone, @Async executors via an MDC-snapshot task decorator in the async configuration, SQS consumer legs via trace context carried in message attributes alongside the AD #13 idempotency key. The Cross-Cutting observability bullet names the same mechanism. Full discipline: coding-standards.md §8 (new) — mechanics, levels (fault-vs-outcome), the business-event contract, message structure, and the deny-list (AI bodies never in prod logs per A.6.3; commercial figures not at INFO).

Rev 16 — 2026-08-19 — quality toolchain named; frontend linter is Biome

  • coding-standards.md gains §7 Tooling & enforcement — the per-repo quality toolchain, the pre-commit → PR fast/slow-lane → merge → tag enforcement ladder, coverage policy (per-package, report through Phase 1, gate from Phase 2), dead-code policy, commit/PR lint, supply-chain measures (secret-scanning push protection, gitleaks, grouped Dependabot, lockfiles), suppression discipline, and a recorded do-not-run list (Checkstyle/PMD/SpotBugs, Sonar, nightly E2E, mutation testing, repo-wide coverage gates).
  • Frontend linter: Biome (format + lint), replacing the ESLint + Prettier pairing in live text (CI/CD pr-validate row, §Core/Domain frontend-import-rules row, Foundation slice 3). dependency-cruiser stays as the whole-graph boundary tool — Biome restricts import paths but does no cycle/orphan/transitive analysis. Dated decision records (AD #17 rows, Rev 5 history, the 2026-08-06 core-reuse feasibility study) keep their original ESLint wording as point-in-time records.
  • Foundation slice 4 row now points at §7 and carries the slice-4 tool set (Error Prone + NullAway, JaCoCo report, Gradle wrapper validation, bundle budget, Knip) plus the prove-red-green-once requirement.

Rev 15 — 2026-08-19 — E2E CI tiering decided (AD-O-11 closed)

  • AD-O-11 closed: two tiers — smoke on merge, full suite on release tag; no nightly. The /forge-deliver orchestrator already runs the full live suite on the wave branch before the wave PR opens, so a merge-time repeat tests the same commit twice. CI covers only what a local run structurally cannot: cross-wave integration breakage on main (two waves that pass independently can break each other once both land) and deployed-environment failures — migrations, CORS, OAuth redirect URIs, CloudFront/S3 SPA routing — which pass locally by construction. The tag-time run is the one that matters most: it verifies the exact artifact the client is about to test.
  • Nightly full run considered and dropped — it duplicates the tag run without adding a distinct failure class, and Actions minutes come from an org-wide shared pool.
  • Smoke tier constrained to read-mostly. It runs against the shared development environment, so it creates only uniquely-named records and cleans them up, and never reseeds — test-strategy.md § Test Data & Isolation requires E2E to reset/reseed between files, which is incompatible with a shared environment mid-workday. Recorded as a design constraint on the smoke specs, not an implementation note.
  • New ## CI/CD Pipelines subsection Browser E2E runs in two CI tiers carries the trigger/scope/target table; both jobs live in <frontend-repo>.

Rev 14 — 2026-08-19 — CI/CD pipelines specified

  • Added ## CI/CD Pipelines — per-repo workflows, triggers and what each runs, wired at Foundation slice 4. States the artifact asymmetry that shapes them: the backend image is environment-agnostic (one image, one application.yml, all per-environment values from the task definition) and so promotes unchanged, while a frontend bundle bakes its build-time config at build time (AD #22) — a UAT bundle and a production bundle are different artifacts from the same commit, so a frontend build is always per-environment.
  • deploy-prod only; no deploy-uat until a round needs it. The UAT environment is temporary (terraform apply/destroy, one instance from Phase 1’s round to the end of Phase 2’s, AD #23), so a standing workflow would target infrastructure that does not exist for most of the engagement (as decided; since the revision of 2026-11-18 it exists from mid-November to the end of Phase 2) — and a single deploy workflow parameterised across UAT and production would be a correctness hazard given the bundle asymmetry above. Settle-by: before the Phase 1 UAT round opens (2 Nov).
  • Cross-cutting rules recorded: AWS access by GitHub OIDC → IAM role, no static keys; GitHub Environments with required reviewers on production as the actual implementation of the “manual promotion gate”; per-environment concurrency groups; required status checks added to branch protection once the pipelines are green.
  • New AD-O-11 — where the browser E2E + accessibility suite runs in CI (post-deploy-dev against the dev environment vs. both services booted on the runner), settle by Foundation slice 4.

Rev 13 — 2026-08-19 — branching, release and protection model (AD #24)

  • Deployment section now states what each environment deploys: development auto-deploys main; UAT and production deploy an annotated release tag (vX.Y.Z), never a branch. A delivery phase may reach production ahead of V1 sign-off, so fixes to a live release are cut from that release’s release/vX.Y.Z branch and merged back to main. Full branching, tagging, naming and branch-protection rules live in .claude/rules/git-conventions.md; the decision itself is AD #24. main remains the single integration point, so the wave orchestration invariant (WAVE_BASE = main) is unchanged.

Rev 12 — 2026-08-19

  • Capture repo forge-et-pwa now exists in altrium-io — the Components-table note drops its “created at the stream’s start” qualifier. No design change; the stream still starts ~week 8. Applied here, in CLAUDE.md (Reference Map), README.md, team-guide.md, and git-conventions.md (CODEOWNERS wired into all three app repos the same day).
  • CODEOWNERS wired into forge-et-be, forge-et-fe and forge-et-pwa (one PR each) — until now only the harness carried the file, so PRs in the app repos auto-requested nobody. All three owners were verified to hold push access first; CODEOWNERS silently no-ops otherwise.
  • Repo-contents qualifiers dropped from the doc set — notes of the form “(repo exists, README-only)” on forge-et-be/forge-et-fe/forge-et-pwa are self-staling: they are wrong the moment the first code lands. The rows now say only when each repo’s CLAUDE.md arrives, which is the durable fact.

Rev 11 — 2026-08-19 — OQ-15 residual closed; dependency asks front-loaded

  • OQ-15 pointers updated (AI-layer notes, core-domain risk table, comparison table, ## Open Questions) from “pending formal client approval at contract stage” to resolved — the data-handling arrangements are those in the accepted proposal (Appendix A.6), signed off with its commercial acceptance 2026-08-16 (PRD Rev 12); no separate approval document or gate. SP-ARCH-001 remains stood down; the AIProvider seam remains as the safeguard.
  • Mailbox dependency pointer re-dated (row 4 — admin consent + test accounts + shared-mailbox confirmation): Fri 18 Sep → preferred by Fri 4 Sep, after the client dependencies register was cut to the seven development-blocking inputs carrying one preferred date for everything (Fri 4 Sep) — asked far earlier than the build needs each item, so a client-side slip cannot stall the build.

Rev 10 — 2026-08-19

  • Terraform adopted for all AWS infrastructure (AD #23): env-parameterized modules per account, S3 state + DynamoDB locking, home forge-et-be/terraform/. New §Deployment bullet states the operational reason the temporary UAT environment needs it — dev hosts the Phase 2 build during the Phase 1 round and production would need a test-data purge, so each acceptance window is an apply/destroy of a uat instance on the prod shape. Slice 1’s cloud half named as the Terraform bootstrap. Config posture (same day): one application.yml, all per-env values from the task definition, profiles only for local/test bean wiring.

Rev 9 — 2026-08-18 (night)

  • Region revised: AD-O-9 Singapore → US East (us-east-1), on cost — Singapore was priced 10–25% above the proposal’s mid-cost basis, US East lands at or below it, and us-east-1 is Bedrock’s home region so every pinned Claude model serves natively (the cross-region-inference caveat dissolves). Accepted trade-off: ~200ms API round-trip from Sri Lanka; the static frontends serve from CloudFront edge regardless, and buyer data stays inside the client’s own account in either region. Applied here, in CLAUDE.md (Stack, AD #19), the PRD (Rev 11), ai-provider-strategy.md, coding-standards.md, and the client pack (dependencies Rev 5, client PRD Rev 3).

Rev 8 — 2026-08-18 (late evening)

  • Frontend goes SPA; hosting unifies on static. Both frontends are now React SPAs built with Vite — Next.js dropped (AD #21: internal authenticated apps, no SEO; matches the team’s existing frontend convention) and both deploy as static S3 + CloudFront bundles at their own domains (AD #22) — the backend becomes the only Fargate service, behind the ALB, and AD-O-1’s costed Fargate frontend is superseded at lower cost (its SSR session-cookie residual dissolves with SSR). CI/CD split into the two deploy shapes: backend image → ECR → task-definition revision → service update; frontends → Vite build (GitHub Actions variables/secrets for build-time config — public values only) → S3 sync → CloudFront invalidation.
  • Secrets model made concrete: backend runtime secrets (DB credentials, OAuth client secrets, session key) live in Secrets Manager, injected via task-definition secrets references; all AWS access via the task IAM role — no static keys; the frontends carry no secrets at all.
  • Capture repo named forge-et-pwa (team decision). Mailbox section gains the explicit Pipedrive-parity note (per-user + shared inbox = the model the team already uses), pointing at the new m365-mailbox-integration.md research note. Titles dropped from names in live prose (roles live in team-guide.md).

Rev 7 — 2026-08-18 (evening)

  • Alignment sweep after the decision wave: Bedrock residue cleared from live text (overview, security baseline, in-house-first table, AI-key claims — no Anthropic API key exists; the task IAM role authenticates) · AD-O-6 pointer corrected (retention/erasure is closed, not open) · AD-O-1 restated at the compute bullet (frontend on Fargate; ALB + ACM named) · Amazon SNS alarm delivery added (observability + slice 5) · capture app hosting fixed as static S3 + CloudFront · dev profile corrected to build-only (temporary-UAT model) · config shape unified to a single top-level provider + per-feature {model, enabled} · SES sending identity added to slice 5 · mailbox section now cites dependency row 4 (admin consent + three test accounts, Fri 18 Sep).

Rev 6 — 2026-08-18

  • Added: ## Trade-Show Capture App section — full scope in V1 (matching client/project-proposal.md §4; internal decision 18 Aug), positioned as apps/capture in the frontend workspace with a capture API slice feeding F11; prototype exists (Thilina). OQ-48’s PRD fold-in remains pending.
  • Changed: Components table carries the real repo names (forge-et-be/forge-et-fe, created 13 Aug, README-only) · runtime contexts/profiles noted in Deployment (local/dev/prod, conventions in coding-standards.md §5) · AD-O-10 downgraded from “blocking unknown” to a working assumption (Empire-held account opened at signature — confirm in writing with the SoW; slice 1’s non-cloud half proceeds in mobilisation week) · Foundation slice 1 wording updated to match · stale Foundation-Backlog footnote fixed (9–13).
  • Companions added the same day (not part of this file): ai-provider-strategy.md (models, fallback chain, verified costs), coding-standards.md, the .forge/client/ pack, and the rendered docs-html/ site.
  • AI section now names the provider chain in this file — Anthropic direct primary with a single Gemini Flash fallback (a Bedrock middle tier was in the morning draft and dropped the same day: it lags new-model availability, and the data-handling document covering both vendors makes cross-vendor failover approvable from day one) — with per-feature {provider, model, enabled} runtime routing, so the approved architecture record carries the decision itself, not only a pointer to the companion.
  • Decision wave (18–19 Aug, applied in this file): AI is now Claude via Amazon Bedrock only — in-account, one AWS bill, no direct-API tier and no second-provider fallback (degrade-to-manual is the outage path; the earlier direct-primary/Gemini-fallback design lasted one evening) · capture-app notifications are email-only via SES (WhatsApp dropped — no external messaging vendor) · AD-O-3 closed (SES) and AD-O-9 closed (Singapore, ap-southeast-1) · the capture app moves to its own repository with its own hosting/URL · delivery consolidates to Phase 1 (= 0+1a) and Phase 2 (= 1b+1c) with a client UAT round after each, hosted in a temporary UAT environment or pre-go-live production (dev no longer doubles as UAT).
  • Same-day reconciliation sweep (evening): ## Resource & Timeline Reality restated for the team of 3, the 13-slice + full-scope-capture ~68–92 cycle-day estimate against the 64-working-day dated window, and the capture app being inside the estimate · extension-point rows 3–4 renamed to the canonical ChecklistEngine / TagSetCompatibility (matching the module layout, slice 13, and coding-standards.md) · AD-O-9 id-collision footnote corrected (Gmail question vs AWS region) · candidate-AD note updated (promoted as CLAUDE.md AD #17–#20) · Revisions re-sorted reverse-chronologically · header date fixed · timeline references re-pointed after the timeline’s Rev 2 consolidation.
  • By: Tharinda (with Claude) — architecture remains approved; these are additive/state-reconciling changes, flagged for Dinil/Thilina review on PR #10.

Rev 5 — 2026-08-06 (core/domain separation adopted IN FULL — supersedes Rev 4)

  • Developer decision: build the full clean separation, not the reduced subset Rev 4 proposed. “We need to build it to be fully functional — all components for a clean separation.” Rev 4’s cost-driven trimming is withdrawn.
  • ## Core / Domain Separation rewritten to full scope. The acceptance test is now explicit: deleting the tea tree must leave a clean, working generic CRM. Rev 4’s approach failed that test by design — it left tea columns on generic tables.
  • Adopted in full: the two-tree module layout (8 generic modules, 7 tea modules, one deployable) · typed 1:1 extension tables for Account/Deal/Product/Quote, explicitly not the F34 JSONB mechanism, since PRD P-09 requires first-class typed fields · all ten extension points · three frontend UI packages with a FieldRenderer registry · two separate Postgres schemas with a partitioned Flyway version space and an FK-direction CI check · four-layer enforcement (build graph, ArchUnit incl. a banned-vocabulary rule, ESLint/dependency-cruiser, CI schema check) · a ## Layer Classification section added to the spec template.
  • Foundation Backlog 11 → 13 slices. New slice 12 (extension-point substrate) and slice 13 (core workflow primitives — ChecklistEngine, GateRule, TagSetCompatibility, RoundLifecycle, StaleClock). Slice 1 gains the module skeleton and its enforcement; slice 2 gains schema separation and the Flyway version partition; slice 3 gains the frontend package split and the FieldRenderer registry.
  • Cost recorded, not hidden: ~+8–15% on V1. This moves the /forge-estimate band from ~58–74 to roughly 63–85 cycle-days against a ~55–65 working-day feature-complete budget, on a 2-developer team, under a proposal with a day-for-day slippage clause. R-ARCH-001 tightens accordingly — the concern was raised, the developer reaffirmed the decision, and it proceeds as an explicit investment.
  • Guardrails retained: AI prompts stay in tea-ai (the product’s differentiator is tea-domain AI per P-21 — core takes orchestration only) · this is not multi-tenancy and must not become it · rule-of-two on anything beyond the ten seams.
  • OQ-50 (reuse rights) — assumed yes, advice reported 2026-08-06. Not a blocker on any of the above.
  • Candidate AD row 17 rewritten to match.

Rev 4 — 2026-08-06 (core/domain separation, reduced scope — SUPERSEDED by Rev 5)

  • Added ## Core / Domain Separation (reduced scope) — folds the answer to the “can we reuse the generic CRM on a future project?” question into the architecture, at a deliberately smaller scope than core-reuse-feasibility.md recommended.
  • Why smaller. That analysis costed the full approach at +8–15% of V1 while team size and delivery window were both unknown. Both are now known — 2 developers against a proposal-committed ~11–13 weeks, with /forge-estimate already showing 58–74 cycle-days against a 55–65 day budget. A ~10% platform tax has nowhere to land, and it would be paid to serve a client who does not exist yet.
  • Adopted (3 items, each justified by this project alone): (1) module separation with a build-enforced one-way dependency — hours of work, and it keeps the ~two-thirds Pipedrive-parity surface from tangling with tea rules; (2) a single ChecklistEngine + GateRule primitive — cheaper than not doing it, since F7/F8/F9/F10/F19 are five instances of one pattern, built with its first consumer in P1a rather than as another Foundation slice; (3) a swappable design-token layer — near-free in Foundation slice 3, expensive afterwards.
  • Explicitly not adopted: typed extension tables and the ten extension points (the expensive, speculative half), any published/versioned generic-core artifact, and multi-tenancy. Tea attributes stay as ordinary typed columns on core tables.
  • Consequence stated in the doc rather than left implied: these items make a later extraction cheaper but do not deliver a reusable core — deleting the tea tree after V1 would leave generic entities still carrying tea columns. Accepted trade.
  • Foundation slices updated: slice 1 now also establishes the module split and its enforcement; slice 3’s tokens become a swappable theme layer, flagged time-critical.
  • Candidate AD row 17 added (module separation, typed columns not extension tables, no extension-point substrate in V1).
  • New signal OQ-50 — whether the Empire contract permits reuse of the generic layer at all. Deliberately not a blocker on the three adopted items, since each stands on its own merits; it gates only the reuse narrative.

Rev 3 — 2026-08-06 (verification dry-run findings)

  • Trigger: a /forge-arch-probe dry-run run after the Rev 2 fix landed, to verify the new proposal-input step actually works. It did — and a full read of the proposal (rather than Rev 2’s targeted sweep) surfaced four more divergences. Rev 2 grepped; Rev 3 read.
  • Environment count corrected — three to two. Deployment topology, CI/CD, Foundation slice 1, and the PRD’s hosting NFR all assumed dev / staging / prod. proposal § A.1 funds two (development + production), with development doubling as UAT and scheduled off outside working hours; A.2.3 prices a separate staging environment as an unpurchased +$45/mo add-on; A.2.4 frames three environments as the rejected ~$520/mo option. CI/CD now promotes dev → prod directly, with a note that promotion must not disturb an active UAT window. Same failure shape as the Rev 2 Multi-AZ correction: the architecture had scoped infrastructure the client did not buy.
  • New signal OQ-49 — the proposal contradicts itself on this. § 11 Deliverables promises three environments at handover while five places in Appendix A fund two. This architecture follows the costed appendix until a human settles it; it is not a doc edit, it is a client conversation.
  • AD-O-7 widened — the migration is two migrations. proposal § 8 commits a parallel run with Pipedrive as system of record, then a freeze-window final migration. F4 therefore needs a delta reconciliation pass — skip already-migrated records, capture new Pipedrive records, never overwrite CRM-created ones — plus a held-open rollback position and a verifiable migration report. The decision previously read only “rollback-safe,” which is a different problem.
  • Two previously untracked unknowns added: AD-O-9 (AWS region — 10–25% cost variance per A.1, and tied to EU data-protection in § 12) and AD-O-10 (who holds and pays the AWS account — § 12/§ 17 says “to be confirmed”). AD-O-10 blocks Foundation slice 1 outright, which slice 1 now states explicitly. Open decisions: 5 → 7 (AD-O-2, 3, 4, 7, 8, 9, 10 active; AD-O-1, 5, 6 closed).
  • Phasing corrected in the PRD (not this document): F23 moved P0 → P1c and F19 moved P1a → P1c, to match proposal § 6, because § 6/§ 17 tie milestone acceptance and payment to those boundaries. A reconciliation note records the two consequences — the import engine is still built in P0 to serve F4, and deals can reach Won before F19 exists.
  • Unchanged: the Gate 2 Run 2 verdict. This is a dry-run’s findings applied as content, not a new gate run.

Rev 2 — 2026-08-06 (post-Gate-2-Run-2; proposal reconciliation)

  • Trigger: team size confirmed at 2 developers, and a sweep of project-proposal.md — prompted by the mailbox finding in Rev 1b — established that the proposal already answered several things this document recorded as unknown or stated differently. Reconciliation is against the issued proposal, which is the binding artifact.
  • ## Resource & Timeline Reality rewritten. Team = 2 devs. The delivery window was never missing — proposal § 7 commits ~11–13 weeks to feature-complete and ~3.5–4 months to signed-off V1, with a day-for-day slippage clause; § 6 defines the phases. /forge-estimate (2026-08-06): ~58–74 wall-clock cycle-days for 11 Foundation slices + 30 features against a ~55–65 working-day budget — fits on paper, thin in practice because the estimate excludes queue time and this engagement’s queue is already enumerated. Basis: org baselines v0.34.0, zero project samples.
  • Three open decisions closed as already-answered: AD-O-1 (frontend on ECS Fargate, costed in A.2), AD-O-5 (backup RPO/RTO, PITR granularity, retention, restore rehearsal + quarterly test — fully specified in A.5), AD-O-6 (per-data-class retention and the deletion-on-request path — A.6.3). AD-O-3 strengthened (SES named in A.7, though inside the conditional capture-app section). Open decisions drop from 8 to 5 — remaining: AD-O-2 (search), AD-O-3 (SES), AD-O-4 (virus scanning), AD-O-7 (migration rollback), AD-O-8 (seed data).
  • Corrected a claim the client had not bought: this document said “Multi-AZ prod.” The costed baseline in A.2/A.5 is single-AZ across all environments, with Multi-AZ a priced add-on (+$30/mo) recommended once the system carries real business. The recovery targets follow from that baseline.
  • AI cost control replaced with the committed figures — $50/month budget, billing alert at $150, per-feature admin toggles without deployment, prompt caching, per-call cost/token/latency/outcome logging, and a configurable ceiling that disables AI rather than allowing an unbounded bill (A.3.2).
  • Added ### Committed security baseline from A.4 — GuardDuty, CloudTrail, KMS, IAM Identity Center with MFA, Shield Standard, account isolation, plus standing controls; WAF and the rest as priced add-ons. The pre-go-live security review is a committed deliverable, so it is a release gate rather than a recommendation. This document had described security more thinly than what was sold.
  • Added ### AI data-handling boundary from A.6.1–A.6.2 — minimum-necessary payloads, an explicit never-sent list, no blanket database upload, and nothing sent automatically in the background in V1. That last point forbids auto-triggering F12 on mail arrival, which is an easy “optimisation” for someone to reach for later.
  • Provider comparison reclassified from safeguard to commitment. A.3.1 commits a side-by-side quality comparison on real inquiries during Phase 1b, with Gemini priced as the named alternative. The AIProvider seam will therefore actually be exercised with a second implementation — build for genuine swappability and keep request/response shapes provider-neutral.
  • New signal: OQ-48 — the trade-show lead-capture PWA is in the issued proposal (§ 4, costed in A.3.2/A.7) but absent from the PRD and this architecture, and the proposal contradicts itself on whether it is in V1. Parked by the developer; recorded so it survives.
  • Risk restated, not closed: R-ARCH-001 is no longer “team capacity and timeline unconfirmed” — both are known. It is now whether 2 developers and a ~3.5–4 month commitment are compatible, with the threat concentrated in client-dependency queue time, dependency serialisation, and four novel features. Scope levers recorded in the tracker.
  • Compounding fix: project-proposal.md was not in /forge-arch-probe’s input list, which is why a gate that passed cleanly hours earlier had missed all of this. Added to the command’s step-3 inputs with an explicit precedence rule, and written up as .forge/lessons.md L-001.

Rev 1b — 2026-08-06 (supersedes Rev 1a on mailbox scope)

  • Evidence: project-proposal.md — already issued to the client — was checked. It names Microsoft 365 exclusively in six places: §4 scope (“integration with Microsoft 365”), the §9 architecture diagram node, the §9 narrative, §Client Obligations (“each user connects their own Microsoft 365 mailbox”), and the Appendix A third-party-services and cost tables (“Mail, calendar, and contact synchronisation via Microsoft Graph”, licences held by Empire). Gmail, Exchange-on-prem and raw IMAP appear nowhere in the proposal.
  • Changed: mailbox scope is now stated as Microsoft Graph only, as a commercial boundary. Gmail/EWS/IMAP are out of V1 scope, additive only via change request. Rev 1a’s three-tier model — which retained Gmail on the strength of the internal OQ-24 wording — is superseded: the issued proposal is the binding statement of scope and it never quoted Gmail.
  • Added: a MailboxProvider seam, giving mailbox access the same treatment as AIProvider (AD #6) and ErpHandoffService (AD #10). This was a consistency gap — two deferred integrations had named seams and the third did not. It is what makes excluding the other providers cost-free architecturally.
  • Closed: AD-O-9 (was Gmail in V1?) — answered by the proposal, no longer an open decision.
  • Realigned: the F20 build-feasibility row (residual risks restated as deliverability, shared-sender, and silent sync failure — not provider count), candidate AD #16, the OQ-24 entry, the In-House-First row, and the Data Flow push-notification bullet.
  • Correction history, for the record: Rev 1 claimed “not built in V1” citing OQ-24 — right conclusion, wrong evidence. Rev 1a corrected toward multi-provider on the strength of the OQ-24 wording — wrong conclusion, since that wording was never backed by the proposal. Rev 1b settles it on the binding document.
  • Upstream fix: the PRD overstated this scope in two places (§F20’s provider list and the OQ-24 resolution wording). Corrected in PRD Rev 7 — see project-prd-history.md.

Rev 1a — 2026-08-06 (correction to Rev 1)

  • Corrected: Rev 1 stated that Gmail, Exchange-EWS and raw IMAP were “not built in V1”. That overstated the record. The authoritative OQ-24 resolution in project-prd-history.md reads “Gmail/Exchange/IMAP remain supported by the build but are not in use” — an observation about Empire’s mailboxes, not a descoping decision. Rev 1 converted the former into the latter, which nobody decided.
  • Changed: the mailbox section now describes three tiers — Graph as the live path, the Gmail API retained as a first-class OAuth-native integration (as designed at Gate 2 Run 1), and EWS/IMAP accommodated but unimplemented because SP-ARCH-002 stood down. The F20 build-feasibility row, candidate AD #16, the OQ-24 entry, the In-House-First row, and the Data Flow push-notification bullet were all realigned to match.
  • Added: AD-O-9 — whether Gmail is implemented and tested in V1 or accommodated only. The OQ-24 phrase “supported by the build” does not settle this; the proposal must be checked, since a quoted provider is a commitment regardless of current usage.
  • Unchanged: standing down SP-ARCH-002 remains correct — no Empire user is on EWS or IMAP. Only the claim about what is built was wrong, not the claim about what is used.

Rev 1 — 2026-08-06

  • Changed: reconciled the whole document against project-prd.md (last updated 2026-08-03) and project-prd-signals.md, which had advanced three weeks past this document.
  • Resolved forward: OQ-24 → Microsoft 365 as the mailbox provider in use, with the other providers tiered rather than removed (SP-ARCH-002 stands down). OQ-15 → cloud Claude accepted (SP-ARCH-001 stands down). OQ-2 → current ERP named as IFS with the automated path as a priced follow-on.
  • Added: ## Weekly Bulk Pricing Subsystem (confirmed in the PRD after Gate 2 Run 1, previously unmodelled) · EventBridge scheduling · idempotency requirements · the six-role + granular-permission-level model · CSRF/session hardening · shared-mailbox modelling · Graph subscription renewal + silent-failure alarms · AI resilience and cost control · search, API-convention, virus-scan, backup, and retention treatment · an AuctionPriceProvider seam · ## Open Decisions (8 items) · Foundation slices 9–11 · candidate AD rows 12–16.
  • Impact: this revision touched decisions locked at Gate 2 Run 1 and added Foundation scope. Gate 2 Run 2 verdict given 2026-08-06 by Dinil: passed-with-risks-and-spikes. R-ARCH-001 carried; SP-ARCH-001 and SP-ARCH-002 stood down; SP-ARCH-003 (bulk-pricing data model) newly scoped; AD rows 12–16 promoted to CLAUDE.md. The audit block, the PRD ## Gate Status row, and tracker.yaml setup.architecture were all written on that verdict.
  • Not changed: the core shape — one backend owning all logic and secrets, a queue for slow work, and named seams for unresolved forks — held up under review and is unmodified.

Generated from .forge/design/architecture.md by .claude/lib/render-docs-html.js. Markdown is canonical.