Empire Teas CRM — Engagement Log
The dated narrative of how the engagement got to where it is.
CLAUDE.md § Active Contextcarries only the current state and points here for the history; this file is where the history goes when it leaves that section. Append-only below the line — a paragraph moved here keeps its original wording, so a reader tracing a decision sees what the team wrote at the time, not a later summary.
What belongs here: the engagement-evolving narrative that used to accumulate in
CLAUDE.md § Active Context(per-slice histories, meeting fold-ins, decision cascades), and the long-form rationale of Architecture Decision rows thatCLAUDE.mdcompresses to a decision plus a one-line why. What does not: anything that is the live rule or the live state — those stay inCLAUDE.md, the tracker, the PRD andarchitecture.md.
Active Context — as it stood on 2026-09-16, before the Gate 3 run
Moved verbatim from CLAUDE.md § Active Context when that section was reduced to current state only. Every paragraph below is the text as it was on that date; the pointers inside it are to the documents that were live then.
Last reconciled 2026-09-16.
Commercially accepted; kickoff set. Empire Teas accepted the commercial proposal on 2026-08-16 — USD 15,500 one-time + USD 360/month support (AWS + AI billed direct to the account holder, outside both figures — quote running costs from .forge/client/sow-cost-annexe.md, never the proposal’s §A.2.2/§A.8, which describe a superseded estate). Kickoff is Tuesday 1 September 2026, with an internal mobilisation week from 24 August. Delivery shape: two phases with a client UAT round after each — Phase 1 complete Fri 30 Oct then UAT 2–13 Nov (in parallel with the Phase 2 build); Phase 2 feature-complete Fri 27 Nov then UAT 30 Nov–15 Dec; sign-off target Tue 15 Dec. Each UAT round runs in a temporary environment stood up for the window (or pre-go-live production with test-data cleanup) — the development environment stays build-only. The client-facing pack is three dev-authored documents: .forge/client/project-timeline.md (schedule), .forge/client/dependencies.md (the seven development-blocking client inputs — one preferred date for everything: Fri 4 Sep), and .forge/client/client-facing-prd.md (plain-language PRD incl. running costs). Still unwritten: the SoW itself, finalised §17 commercial terms, and the phase acceptance-criteria sets (Foundation + Phase 1 due within 5 business days of signature).
Team = 3 full-stack developers, confirmed 2026-08-18: Tharinda Rajapaksha, Dinil Gamage, Biseni Perera — all three carry development + QA + harness work across the app repos; no backend/frontend ownership split (waves are sliced vertically). Roles, review pairings, and the client-contact rule live in team-guide.md — names stay title-free everywhere else. Thilina’s trade-show capture POC is a near-complete product, not a mock prototype (read-only sibling repo forge-et-pwa-poc; its own docs/plans/README.md records the epic status — most epics done and verified, including a deployed Python backend and an API-integrated frontend). The backend does not port — its stack and infrastructure decisions yield to AD #19–#23, making it a proven reference for the pipeline, API contract and prompt design rather than reusable code; the frontend is the portable half; theme alignment is still open. The capture app ships at full scope inside V1 (Option C — AD #20) and is F36 in the PRD (OQ-48 resolved, Rev 13); the F36 sizing delta against the POC’s real contents is OQ-55. AI model/cost strategy: .forge/design/ai/ai-provider-strategy.md — Haiku 4.5 high-volume / Sonnet 5 synthesis via Amazon Bedrock in-account behind the AIProvider seam (AD #19); the verified monthly cost estimate lives there and in sow-cost-annexe.md.
Gate 1 (PRD) passed-with-risks (2026-07-07). Gate 2 (architecture) passed-with-risks-and-spikes at Run 2 (2026-08-06); architecture.md is approved — the full run record is .forge/engagement-gate-runs.md § Gate 2 Run 2.
No spike remains open. SP-ARCH-001 (self-hosted AI) and SP-ARCH-002 (Exchange-EWS/IMAP) stood down at Run 2 — OQ-15 fully resolved 2026-08-19 (the accepted proposal’s A.6 covers the data-handling arrangements; PRD Rev 12; AIProvider seam retained as safeguard) and OQ-24 resolved to Microsoft 365 only. SP-ARCH-003 (bulk-pricing data model) resolved 2026-08-21 — the model is settled and DDL-verified in forge-et-be/docs/data-model.md §2, which supersedes the research doc: F26 must be specced against §2. Its §2.14 open items are non-blocking; the load-bearing one is validating the model against the real Tea Room price list when it arrives (client dependency, ~late Sep). Revised by PRD Rev 23 (2026-09-11): the price grain drops its market axis — one price per standard per week (Empire, 9 Sep; the weekly price workbook they shared on 11 Sep confirms the shape) — so §2.2 needs a revision before F26 is specced (owner: Tharinda, AD #31); the price-list dependency is met in substance, its currency/unit and duplicate-number questions are OQ-59.
Timeline = committed; R-ARCH-001 restated 2026-08-18, not closed. project-proposal.md § 7 commits ~11–13 weeks to feature-complete, ~3.5–4 months to signed-off V1, with a day-for-day slippage clause — anchored to dates: feature-complete target Fri 27 Nov 2026, sign-off target Tue 15 Dec 2026 (project-timeline.md §1). The scope basis and cycle-day band live in tracker.yaml under R-ARCH-001 (the SessionStart hook injects them every session): it fits with thin headroom, because the estimate excludes queue time and most of the open OQs are blocked on the Pipedrive audit (live list: project-prd-signals.md). The risk is the waiting, not the coding — closing the Pipedrive audit and OQ-9 removes more calendar risk than any feature cut; scope levers under R-ARCH-001.
⚠️ .forge/client/project-proposal.md is a binding input — read it before any gate or scope claim. Where the issued proposal and an internal document disagree, the proposal wins — the why is .forge/lessons.md L-001 and .claude/rules/source-trust.md; /forge-arch-probe reads it as a step-3 input. Two Gate-1 risks carry through architected-around rather than resolved: R-PRD-001 (ERP API → ErpHandoffService) and R-PRD-002 (external-AI privacy → AIProvider). OQ-9 (standard-held certification storage — the buying standard carries its certs since PRD Rev 27) is open and gates F9.
Foundation is complete in substance — every non-cloud slice is done and reflected (FS-1 through FS-7, FS-9, FS-10, FS-11, FS-14, FS-15 and the closing FS-8); the phase was sealed 2026-09-16 (Tharinda, lead) and Gate 3 (/forge-decompose) is the next step. One late slice was added 2026-09-16 — FS-15 (retire the product catalog, PRD Rev 27: a minimal buying_standard + GET /api/v1/buying-standards replace the product stand-in, the catalog package and product.* keys go) — spec approved 2026-09-16 (Tharinda, harness PR #99), plan approved the same day (Dinil as peer, harness PR #100, after a two-pass /forge-plan-review); SHIPPED 2026-09-16 (forge-et-be#29 + harness#102/#103; reflected via harness#105 — L-042…L-045 promoted, three scoped; its three framework follow-ups — the pipe exit-status trap, capability re-check before recording an absence, the external-artifact rule for plan test tables — are still owed their own PR); FS-8 (developer onramp) ran last, assigned to Tharinda (2026-09-15) — spec approved 2026-09-15 (Rev 1 2026-09-16: the timed run is a fresh clone on the tester’s own laptop, no fresh OS account — company laptops), plan approved 2026-09-16, implemented 2026-09-16: AC-1 met at 23 min 13 s (Dinil, Windows, office wifi; five runs, thirteen README defects fixed — 008-developer-onramp-findings.md F-001); the Node pin (.nvmrc 24, engines, engine-strict) and fnm as the team’s Node manager landed in all three repos with a docs/adding-a-feature.md each; all four PRs merged 2026-09-16 (forge-et-fe#16, forge-et-pwa#17, forge-et-be#28, harness#98) — FS-8 is DONE and reflected the same day (harness#109 — L-046…L-050; the framework follow-up harness#110 added the tick-at-close rule, dropped the dashboard hook’s mtime skip and the one-line conflict rule); FS-12 and FS-13 were dropped (AD #29). The manual foundation review (.forge/specs/foundation/README.md step 4) completed 2026-09-15 — pass-with-risks, accepted risks R-FND-001…004, recorded in .forge/engagement-gate-runs.md as the Gate 3 precondition note; it ran beside FS-8’s spec approval per lead decision D3, so Gate 3 (/forge-decompose) may now run.** FS-6 (Auth scaffolding) SHIPPED 2026-09-15 — forge-et-be#21 + harness #85 merged, reflected the same day (harness #86; L-032…L-036 promoted, six findings scoped). History: plan drafted 2026-09-08 (Dinil, against spec Rev 3) and revised 2026-09-10 against spec Rev 4 for the single-module layout; merged via harness PR #58 (.forge/plans/foundation/006-auth-scaffolding-plan.md, Status: approved on 2026-09-14 after a four-pass /forge-plan-review; implemented and merged 2026-09-15). Sixteen subtasks, T2 throughout, backend only; one auth package (com.empireteas.auth), migrations V4–V8 in the one Flyway sequence, FS-14’s arch suite in place of the retired split guards. Plan decisions (Q-2/Q-11/Q-12): template content is seeded data (role_template + role_template_grant, copy-on-create and reset read the same rows; the Empire set is migration V8) — superseded by AD #32 (2026-09-11): no templates, one role per user, no ai-use category; spec Rev 5 + Rev 6 and the plan revision landed via harness PR #76 ahead of the plan review — one GrantConsistencyChecker at startup (fail-fast on orphans and bad scopes) and again in CI, /api/me served at /api/v1/me under FS-10’s prefix. Recorded hand-off, owned since 2026-09-15: first-administrator provisioning for a cloud environment — F5’s spec owns the bootstrap step in app code, the FS-1 cloud half owns the per-environment value in the task definition; the CSRF cookie host question stays a cloud front-end decision (forge-et-be/docs/auth/README.md). Spec drafted 2026-08-31 (Dinil), merged as a draft via PR #41 and approved 2026-09-03 (manual foundation cycle); Q-1 resolved as a recorded AD #12 carve-out — Spring Session’s built-in expired-session cleanup stays in-process, an idempotent DELETE with no duplicate outward effect, and FS-9 may move it later; spec Rev 1 (2026-09-04) applies AD #28 — Microsoft-only login, Google + local password dropped, a profile-scoped local/test stub login replaces the password path as the offline-dev story; lead re-ack of Rev 1 given 2026-09-14 as part of the single Rev 1–6 ack; spec Rev 3 (2026-09-07) applies AD #29 + AD #30 — the plan above is authored against it; the single lead ack covering Rev 1 through Rev 6 was given by Tharinda on 2026-09-14 (relayed by Dinil). FS-10 (API conventions) shipped 2026-09-03 — spec approved 2026-09-02 (PR #43 merged; hand-authored, foundation specs are exempt from /forge-spec-review), plan approved 2026-09-02 via /forge-plan-review (two passes, PR #44); backend forge-et-be#14 + harness #46 merged to main (the FS-6 spec approval folded into #46, so #48 was closed). The pre-PR review found no Blockers — four Importants fixed with red-green receipts, three deferred with a written fix path, one FS-6 hand-off; full record in the plan’s ## Notes. Reflected 2026-09-03 — F-001 (JSpecify @Nullable is TYPE_USE-only, so springdoc/swagger-core renders a nullable field as non-nullable) promoted to lessons L-019; five findings scoped (010-api-conventions-findings.md). CARRY-FORWARD in the plan’s ## Notes: OpenAPI listPrice nullability owed before the first FE generator run; the huge-page 500 and the body TYPE_MISMATCH mapping both want a spec Rev / ASK FIRST; the FS-6 method-security 403 hand-off. FS-1 (App shell) shipped 2026-08-21 across all three app repos; its cloud half (Terraform bootstrap) is a separate, still-unwritten spec gated on the AWS account — forge-et-be/terraform/ does not exist yet. FS-2 (Data layer) shipped 2026-08-30 — spec (Rev 6) + plan approved, all 15 subtasks merged to main (forge-et-be PR #12 + harness #33); finding F-001 (partitioned Flyway version space vs outOfOrder=false) promoted to lessons L-014. One carry-forward: pin the RDS engine version when terraform/ lands (17 vs 18). Per-subtask detail lives in the plan’s ## Progress; scope in forge-et-be/docs/data-model.md § 2.13. FS-6 is unblocked — only OQ-53’s Tea Room/Executive column mapping remains, and it does not gate the slice. FS-3 (Design system primitives) shipped 2026-09-07 — forge-et-fe#12, forge-et-pwa#13 and harness#51 merged, 24/24 ACs closed: the token contract (names + neutral fallbacks in src/ui, Empire values in each app’s theme file, the pwa carrying identical copies), self-hosted Fraunces/Inter, the FR-C1 component set, the PermissionGuard seam (plan Decision 13 — PermissionDecision + PermissionResolver, stub allows everything), the FieldRenderer registry, and the check:boundaries / check:testids gates in both frontends; the §6 app frame and §5 plain Table stay deferred (Q-5 — first screen-shipping features / F32; F5’s role editor is the likely second Table consumer). Reflected 2026-09-08 — 12 findings promoted (L-020…L-026), 17 scoped; F-005 (tsc -b emitted tests into dist) and F-006 (coverage scope) are resolved by FS-14 — the single package typechecks with tsc --noEmit and coverage now includes src/ui; the pre-PR review’s carried-forward items each have a destination in the plan’s ## Notes § Reflect. AD #29/#30 landed after the slice shipped and change no FS-3 requirement, AC or code — the spec and plan carry clarifying notes only; the permissions/* JSDoc still cites the old (role, resource, level) tuple (doc-only, rides with F5’s provider wiring; the cruiser config was rewritten by FS-14). FS-4 (Build & CI) shipped 2026-08-31 — all subtasks merged to main (forge-et-be#13, forge-et-fe#10, forge-et-pwa#11 + harness#35); the slice-4 quality gates (Error Prone/NullAway, the Trivy dependency scan per AD #27, JaCoCo/Vitest coverage report-only, the route-chunk bundle budget, Knip advisory, and the Playwright/axe scaffold with F-004 closed) are live across all three repos’ lanes. Reflected 2026-09-01 — findings F-001…F-007 walked (L-015…L-018 promoted, the rest scoped). CARRY-FORWARD: coverage (JaCoCo/Vitest) + Trivy gates flip ON at the Phase 1→2 boundary; the Node engines/.nvmrc pin is an open team call. FS-5 (Observability stubs — in-process half) shipped 2026-09-12 — code forge-et-be#17 + harness #73 merged to main; Micrometer Tracing on request threads (the FS-10 traceId hand-off now closed on real 500s), structured-JSON/console log format by env-var toggle, explicit sample rate, and the MdcTaskDecorator substrate (authored, wired by FS-7). Boot-4 wiring needed two runtimeOnly artifacts — the Brave binding plus Boot’s spring-boot-micrometer-tracing-brave auto-config module (the binding alone wires nothing). Reflected 2026-09-12 — the Boot-4 modular-tracing trap promoted to lessons L-028 (coding-standards §8.2/§2.4 corrected); the cloud half (CloudWatch/SNS/SES + per-target alarms) stays a deferred companion spec gated on the AWS account + FS-1 Terraform. FS-7 (Background job substrate) and FS-9 (Scheduler substrate) shipped 2026-09-12 — forge-et-be#18 and forge-et-be#19 merged to main. FS-11 (File pipeline) SHIPPED 2026-09-15 — forge-et-be#22 + harness #89 merged, reflected the same day (harness #90 / #91; L-037…L-040 promoted, six scoped); plan approved 2026-09-12 (Tharinda, three-pass /forge-plan-review). Per-slice history lives in each plan’s ## Progress and its findings file; the tracker notes carry one line of current state. No foundation slice is currently blocked. Work the Foundation Backlog in architecture.md (the authoritative slice list), then the manual foundation review (done 2026-09-15 — the Gate 3 precondition note in engagement-gate-runs.md), then Gate 3 (/forge-decompose) — the next step. Gate-3 standing instruction (team): decompose into small work items — each wave a thin vertical slice verifiable end-to-end across FE + BE, sized for quick review and test; when in doubt, split smaller (small pieces get verified bit by bit as they land, not in one big pass). Map every feature’s blocked_by explicitly and classify what can run in parallel vs what must be sequential — the dependency graph is the work-division plan across the three developers.
AD-O-10 is resolved — the AWS SOW (ET-002) has Altrium own and run AWS (2026-09): the earlier working assumption (Empire opens and hands over the AWS management account at signature) is superseded by the signed managed-cloud-infrastructure SOW (.forge/client/aws-sow.md), under which Altrium owns and administers the AWS organisation and accounts and bills Empire a fixed USD 650/month — all-inclusive of AWS consumption + cloud admin, and separate from the USD 360/month app support under SOW ET-001 — with the accounts not transferred to Empire on exit (data + artifacts are exported instead). Context: Empire is a non-technical business whose cloud billing is normally handled by their IT provider (Dialog), but Empire asked Altrium to run AWS for this project and invoice monthly. Concrete environment/identity values (DNS, Entra IDs, certificate-based login) live in .forge/design/environments-and-identity.md. Two permanent environments (development + production) plus a temporary UAT environment per acceptance round (or pre-go-live production with test-data cleanup) — dev never doubles as UAT; the proposal’s two-vs-three wording contradiction remains OQ-49. The open architectural choices are tracked in architecture.md § Open Decisions, each with a settle-by point; the remaining styling-mechanism and library choices are FS-3 plan decisions. AD-O-3 (SES) and AD-O-9 (US East us-east-1, on cost) are decided.
The three requirements from the 2026-07-16 client meeting are all captured in the PRD: CC/BCC on CRM-sent email → F20; first-class lead-source tracking → F11/F17; price-sensitive weekly bulk pricing → F26/F7/F14, modelled as the client-specific Buying Standard with effective-dated pricing (architecture.md § Weekly Bulk Pricing Subsystem).
The 9 September 2026 client meeting is folded in as PRD Rev 23 (2026-09-11; debrief .forge/discovery/meeting-notes/2026-09-09-requirements-followup.md). Bulk pricing is one price per standard per week — destination market is a customer attribute and a quote field, not a price key (Empire’s statement, confirmed by the weekly price workbook they shared; recorded by Dinil; revises OQ-38’s Rev 6 answer). Hand-offs: forge-et-be/docs/data-model.md §2.2 drops the market price axis (owner: Tharinda, AD #31 — no shipped migration carries it; FS-2 shipped no pricing DDL); F7’s “unpriced market blocks quoting” becomes “unpriced standard”; the prototype’s per-market price board (harness PR #63) was collapsed to one price per standard by harness PR #88 (2026-09-15). Out of V1 (team decision, Tharinda, 2026-09-11; confirmed by Dinil): WhatsApp integration — unchanged. The bulk-email half of that decision was reversed on 2026-09-16 (PRD Rev 28) — see the bulk-email paragraph below. The committed weekly-price path is unchanged either way: prices go out per account from a send this week’s prices action on the account page, through the rep’s own mailbox. F36 grew (QR confirmed as net-new build, a scan-time existing-client check needing an account/contact lookup from the app, a same-day follow-up email) — noted on R-ARCH-001; the descope lever is narrower. Signals: OQ-52 and OQ-55 updated, OQ-51 gains the active-owner answer, OQ-57–OQ-60 raised (participants on a lead, owner-initiated sharing, workbook ingestion, same-day show email). The role-management refinement from the same period landed as AD #32 / PRD Rev 24 (2026-09-11) — see the role-management paragraph below. FS-6 spec Rev 5 + plan revision landed (PR #76), and the prototype PR for the role screens and the price board landed as harness PR #88 (2026-09-15) — which also removed the products catalog (see the next paragraph).
FS-14 (single-module structure) SHIPPED — AD #31, 2026-09-09/10. The core/domain split is collapsed in all three code repos: backend one build.gradle with feature-first packages com.empireteas.<capability> (platform, catalog, pricing, then one per feature), one public schema, one squashed V1… Flyway sequence; forge-et-fe one src/{app,features,ui,lib} package; forge-et-pwa mirrored with a shared-file drift check. Code PRs merged 2026-09-10 — forge-et-be#16, forge-et-fe#14, forge-et-pwa#15 — and the code freeze is lifted. The split’s guards were retired; the hygiene guards stayed and a feature-cycle guard was added (FeatureSlicesSpec). The harness cascade landed with this doc, architecture.md § Core / Domain Separation (now a historical record), coding-standards.md §1, entity-map.md, test-strategy.md, the spec template (Layer Classification removed), FS-6 spec Rev 4, and OQ-50’s closure; FS-3 findings F-005/F-006 are resolved by the collapse. Spec .forge/specs/foundation/014-single-module-spec.md (Appendix C dispositions every FS-1/2/3/4/10 AC — nine retired as split-only). Reflected 2026-09-10 (L-027); the foundation review’s bookkeeping follow-up landed as harness#96.
Core/domain separation — built (AD #17), stopped (AD #29), removed (AD #31/FS-14). The generic-core / tea-domain split adopted 2026-08-06 rested on OQ-50’s assumed reuse of the generic layer on future projects. That reuse was no longer expected (AD #29, 2026-09-07), so FS-12/FS-13 were dropped and the “deleting the tea tree leaves a working generic CRM” acceptance test was retired; FS-14 (AD #31, 2026-09-09) then collapsed the scaffolding outright — one module, one public schema, feature-first packages (see the FS-14 paragraph above). architecture.md § Core / Domain Separation holds the full historical record. Still true regardless: the AI prompts stay rich and in one place (the ai package once it exists — P-21); this is not multi-tenancy; the typed 1:1 extension tables survive as data-model design, now unqualified in one schema, until a feature spec revisits them. F26’s data model (forge-et-be/docs/data-model.md §2) is owned by Tharinda (AD #31); OQ-50 is closed (project-prd-history.md). No change request — internal structure only (L-001).
Role management is FULLY CONFIGURABLE, with a reporting hierarchy — and simplified (AD #30, 2026-09-07, refined by AD #32, 2026-09-11; PRD Rev 21 + Rev 24). Empire asked for admin-authored roles (7 Sep); the team then removed the complexity nobody had asked for (11 Sep — Tharinda’s decision, confirmed by Dinil). The model: a code-declared permission catalog (<resource>.<action> keys, ~100–150, each with category / label / description / UI-group / scope-aware metadata) with grants as data (role, permission_key, scope); no role templates — the only seeded role is the non-deletable system superadmin, and Empire’s Administrator creates every other role by hand from the catalog with Altrium supervising at go-live (the six confirmed roles plus the Managing Director role are the recommended day-one set, recorded in the PRD matrix and client/roles-and-permissions.md); one role per user (app_user.role_id; no union; a role still held cannot be deleted; last-admin protection stands); three categories — read / edit / execute — AI is not a grantable level: system-run AI (scoring, extraction, briefings) is not a permission and user-invoked AI assist rides on the edit/execute permission it serves, so the ai-use-vs-execute split is replaced by the plainer invariant that the AI holds no permission and a person commits every output; app_user.manager_id gives a reporting hierarchy and scope is own | team | all, set per permission. AD #26 is unchanged — every check names a permission key. Consequences: PRD Rev 17’s “levels fixed per role” stays reversed (Rev 21) and Rev 24 restates the axis; OQ-53(b) is the recommended Tea Room/Executive role contents; OQ-51 carries the one-role answer; OQ-56 (four hierarchy questions) is open. F5 builds the role editor, manager assignment, guard rails and the effective-permissions viewer — smaller than AD #30 implied (no templates UI, no union), recorded against R-ARCH-001. No change request: the proposal §3.2 divergence and its 11 Sep refinement are post-issue notes on the proposal header (L-001); the client pack — client-facing-prd.md, open-questions.md Q1/Q2, dependencies.md row 3, roles-and-permissions.md (DRAFT, revised 2026-09-11, awaiting Empire’s sign-off) — is restated as a team decision stated to the client. FS-6 spec Rev 5 (AD #32) + Rev 6 (2026-09-13 — coarse view/manage permissions + certificate auth) are applied (PR #76); the plan was approved 2026-09-14 and the slice shipped 2026-09-15 (forge-et-be#21). FS-3 plan Decision 13’s PermissionDecision union is agnostic to the backend’s computation and survives unchanged. The prototype’s template markers, two-role person and AI-assist chip were removed by harness PR #88 (2026-09-15). Lead sign-off on AD #30: Tharinda, 2026-09-07; on AD #32: Tharinda, 2026-09-11.
Bulk email is back on the table as a V1 STRETCH — recorded, prototyped, NOT committed (PRD Rev 28, 2026-09-16; recorded by Dinil). Empire confirmed bulk sending as an important requirement and a genuinely useful feature, naming two use cases: sending the week’s prices to every client at once and sending newsletters. This reverses the bulk-email half of the 2026-09-11 team decision (Rev 23) — WhatsApp stays out, unchanged. It lands as F37 in PRD §Deferred and as a stretch-phase row in features.md, at the low priority Empire themselves attached to it: taken into V1 only if the schedule allows, decided at the mid-November checkpoint already held under R-ARCH-001 (the same one that owns F36’s descope lever), otherwise the first post-V1 item. Two separable halves, ranked. (a) Weekly price broadcast — one action sending this week’s prices to every client, as a batch of per-account emails (each client sees only their own standards, so it is a mail-merge run, never one message to a list); it is F26/F20’s existing per-account action under one confirmation, which makes it the cheap, low-risk half and the one to build first. (b) Newsletters — one common message to many contacts; gated on OQ-62 (per-contact consent/opt-in and unsubscribe, bounce/complaint suppression, sender identity — a rep’s Graph mailbox does not suit a several-hundred-recipient send, a shared SES address does and moves deliverability/reply-routing/SPF-DKIM — and the audience definition). F37 is deliberately not a campaign product: no segmentation builder, no analytics beyond F20’s open/link tracking, no template designer — that stays deferred F28. Planning rule, load-bearing: the committed V1 scope is unchanged and everything downstream is specced as if F37 does not ship — F20 sends one email at a time and the weekly prices go out per account. Commercially: the issued proposal does not cover bulk sending, so committing F37 is added scope — a change request or a compensating descope under R-ARCH-001 (L-001); recording it as a candidate needs neither. Stated to the client as a post-issue note on the proposal header (16 Sep) and in client-facing-prd.md, which also tells Empire the newsletter half needs their answers first. Prototyped the same day (this change): a Send to all clients action on the Pricing screen and a Newsletter composer on the Inbox screen, both carrying a visible Stretch — not committed marker so a demo cannot be read as a promise, plus a new Send a bulk email permission kept separate from Send email from a record (AD #26 — a bulk send is a different act from a one-to-one send, so it is its own key).
Delivery phasing intent + product decisions (2026-09-13, team — Tharinda). Recorded to drive Gate 3 decomposition; not yet formalized in the tracker (Gate 3 not run). Phase 1 targets Empire’s stated main pain — following up the large cold-lead backlog: login, users & role management, leads, accounts, email (2-way sync) + AI email draft, migrating existing leads + accounts (not deals), lead/account ranking (cold-lead detection), and weekly prices (update + send per account). Phase 2 (tentative): trade-show capture app, sampling, quotes, deals, pipeline — none flagged urgent by Empire. This moves the capture app from AD #20’s weeks-8–13 slot to Phase 2 — still full-scope inside V1, sequenced later (tentative; confirm at Gate 3), so AD #20’s scope stands and only its timing shifts. Migration scope: import leads + accounts only; Empire chose a fresh start on deals (refines F17). WhatsApp: a later phase, not Phase 1 (some customers are WhatsApp-only); already outside the V1 core (PRD Rev 23). Pricing: a standard is globally unique and belongs to one client (a client holds many); price is (standard, week), append-only (AD #14) — the market axis is dropped from the price key (PRD Rev 23), destination market being a customer/quote attribute; the forge-et-be data-model §2.2 revision implementing this is in flight (its own PR). Products are removed — the revisit happened (PRD Rev 27, 2026-09-15): there is no separate products catalog; the Buying Standard is the sellable record for bulk and private label alike, carrying grade / origin / brand / held certifications, cost and price history, with a create / edit / archive lifecycle (archiving keeps the history and drops the standard out of quoting and the weekly round; numbers are never reused) — applied to the prototype in harness PR #88, whose commit message flagged the harness reconciliation as owed. A customer receives their standards and prices through the per-account send this week’s prices action (no new email surface). A price-lookup page (type a standard number, see this week’s price — any role holding the price-view permission) is intended but not a Phase-1 priority; sequence at Gate 3. Backend hand-off (Tharinda, AD #31): the shipped product table (V3__product.sql), the catalog package (Product, ProductController — FS-10’s worked API example), ListPriceModel, the product.* permission keys (ProductPermissions; FS-6 spec Appendix A.2) and the product_id FKs on buying_standard / line_item in data-model.md §2 all assumed the catalog — DISCHARGED by FS-15 (2026-09-16, forge-et-be#29 + harness#102/#103): V10 creates the minimal buying_standard, V11 drops product, the catalog package and the product.* keys are gone, GET /api/v1/buying-standards is FS-10’s reference endpoint re-homed, and data-model.md §2 was revised (forge-et-be#20, #29); FS-6’s key list and the FS-10 worked example followed in the same slice. Whether private-label standards are weekly-priced is OQ-61 (default: quoted per deal). Lead ack of Rev 27: Tharinda, 2026-09-16 (the FS-15 spec approval, harness PR #99) — it reverses the 2026-09-13 kept for now. Cardinality (later phase): 1 deal → many samples; 1 deal → 1 quote. Permissions (feeds FS-6 Rev 6): a coarse view / manage per entity model (manage ⟹ view) plus a short list of sensitive actions kept separate (quote.approve_sub_floor — AD #26, price.publish, email.send), rather than fine-grained per-action — a simplification within AD #30’s catalog latitude (no AD change); AI stays non-grantable (view → AI summary, manage/edit → AI draft; AD #32). Sharing — SETTLED 2026-09-16 (PRD Rev 29, OQ-58 closed; .forge/design/data/record-sharing-model.md): the owner of a lead/deal/account, or a manager above them, shares that record with a named colleague — the third visibility path, covering the peer-to-peer and cross-line case the hierarchy structurally cannot reach (a manager needs no share). A share widens reach, never authority: no access level on the share, the recipient’s role decides what they may do, and it never widens mailbox.read. Not transitive, survives owner reassignment, revocable by owner/sharer/covering manager, shown on the record. Rides on the entity’s manage key — no new catalog key. No backend change is owed now (no lead/deal/account table exists; FS-6 left the ownership context unwired for F1/F2) — it lands with F1/F2 together with the list-query visibility predicate, which they owe regardless of sharing. The ⏰ reminder is discharged; Tharinda is owed a courtesy note that his sketch was read as owner+shared rather than co-owners. Implementing work-streams — all landed: data-model §2.2 (forge-et-be#20), FS-6 spec Rev 5 + Rev 6 + plan (PR #76), and the prototype updates (harness #88, 2026-09-15 — which also removed the products catalog, see above).
Decisions since the 2026-09-16 snapshot
2026-09-17 — Trivy dependency-gate: enforcement trigger changed from calendar to clean-baseline
The dependency-vulnerability gate (Trivy, AD #27) was to switch from report-only to enforcing at the Phase 1 → Phase 2 boundary (FS-4 spec Rev 1). Tharinda (lead) changed the trigger from that calendar date to a condition: enforce as soon as the dependency baseline is clean — the moment the latest trivy-report artifacts for forge-et-be, forge-et-fe and forge-et-pwa all read 0 HIGH/CRITICAL. Rationale: the boundary was only ever a proxy for a clean baseline; enforcing per-PR from the moment it is clean keeps every new HIGH/CRITICAL attributable to the PR that introduces it and cheap to fix then, instead of accumulating an unattributed set to clear right before UAT handover. Measured 2026-09-17 from the latest green main-branch runs: forge-et-fe and forge-et-pwa read 0; forge-et-be reads 3 CRITICAL, all org.apache.tomcat.embed:tomcat-embed-core 11.0.24 (CVE-2026-65182, CVE-2026-65905, CVE-2026-68525), fixed in Tomcat 11.0.25 — a Spring Boot patch bump. That bump is the one remaining trigger; no Gate-3 feature owns it, so it is carried as owed work (owner: Tharinda). Mechanism (team decision, Tharinda, 2026-09-17): take Tomcat 11.0.25 via the next routine Spring Boot upgrade that carries it in the BOM, not a forced Tomcat version override now (FS-4 Rev 1’s reasoning — a forced transitive pin must be unpinned after each upgrade); nothing is deployed yet, so the reported CRITICALs are not exploitable (FS-4 Rev 1), and the only hard deadline is that the upgrade lands before the backend reaches any reachable environment (UAT/prod). The flip itself is a coordinated TRIVY_GATE_EXIT_CODE 0 → 1 across the three pr-validation.yml files, a lead-approved CI change made only after the backend baseline is clean. A newly disclosed CVE in an untouched dependency turning an unrelated PR red is the accepted cost; the governed .trivyignore.yaml (statement + tool-enforced expired_at) is the escape hatch, with Dependabot bringing the fix. The Phase 1 handover regression cycle (RC-1) also records a dated clean-baseline attestation as handover evidence — an addition to the per-PR gate, not a substitute. Coverage (JaCoCo/Vitest, FR-J3) is unchanged: it still gates at the Phase 1 → Phase 2 boundary, its trigger a settled denominator. Recorded as FS-4 spec Rev 3; AD #27’s row carries the condition in place of the calendar clause. No change request — internal CI timing (L-001).
2026-09-30 — who may reassign a record, share it and remove its shares (AD #35 confirmed)
Reviewing AD #37’s cascade, the delivery team found client/roles-and-permissions.md telling Empire that a representative “cannot reassign records they do not own”, while AD #35 lets anyone whose role holds the entity’s manage and who reaches the record reassign it — a colleague it was shared with included. It asked the lead to choose: keep the simple rule and correct the client wording, or limit reassignment to the owner, the owner’s managers and all-key holders. Tharinda (lead) kept the simple rule: anyone with manage on a record they reach, by any path, may reassign it, share it and remove any share on it. No AD changes, because AD #35 already said this. The share picker stays as AD #35 set it — it offers only active colleagues whose role can view that kind of record and who do not already reach it, because a share to anyone else changes nothing. Recorded as PRD Rev 46, record-sharing-model.md D-1 (2026-09-30), the client documents (revised 30 September) and the F5-f stub, whose worked example gains the case of a sharee reassigning.
The lead also asked whether the unowned-record narrowing, which AD #37 moved into F5-l, needed an input. It does not: AD #35 already decided that only the entity’s all key reaches an unowned record, ContactService already applies that to account-less contacts on main, and since PRD Rev 44 no planned V1 path leaves a lead unowned. The change is in the shared permission check, and no user sees anything different.
Three more lead decisions, the same day, on points the review raised:
- A handover is not a CRM change for the Pipedrive import. F4-a FR-C1 counted a reassignment as a change made in the CRM, so every imported record the import owner hands out would have stopped taking Pipedrive’s updates on the final run. The lead chose to ignore an owner-only change, as Dinil had already decided for shares on 2026-09-29. Recorded as F4-a spec Rev 3; F4-d changes the code before its first write run (F4-b waits for F4-d).
- F4-c is dropped. PRD Rev 44 had taken activities and custom fields out of the migration, which was most of F4-c; the final run after the data freeze is F4-d and F4-b run again, and F4-a’s report serves the client. It is recorded under Phase 1, where the decision was taken — the same as F20-e.
- F11-b keeps the Unassigned filter as a safety net, although no planned V1 path leaves a lead unowned.
Addition to the line to Empire (with the AD #37 bullet, before it is sent):
- Anyone who can manage a record can hand it on. Its owner or a colleague it was shared with (whose role manages that kind of record), a manager above either of them, or a role with “all records” can hand it to a new owner, share it, and remove its shares. Our earlier wording that a representative “cannot reassign records they do not own” was wrong for a record shared with them.
2026-09-30 — the Pipedrive import owner and the bulk hand-out
Checking the 9 October parallel-run start the F4-d stub quoted, the delivery team found it came from the schedule replaced on 29 September; the timeline now says the parallel run begins inside Phase 1 on a date to be agreed, and the first load needs F4-d and F4-b, late in Phase 1. It also found that after an import every record belongs to the import owner and a rep reaches none of theirs (AD #37), while Phase 1 had no bulk way to hand thousands of records out (bulk reassign was F32-b, Phase 2). Tharinda (lead) decided:
- Both runs stay — the first load and the final run after the data freeze — as a safeguard.
- One import owner per run, by default the signed-in user who runs it (most likely Kavindu Anthony as IT Admin in production), unless the run names another. Their role holds
lead.manage,account.manage,lead.allandaccount.all, which the migration-seeded IT Admin grants itself (audited). A later run never takes a record back from its new owner. - The “change owner” bulk action on the lead and account lists comes forward to Phase 1 as a new feature, F32-c, split from F32-b; every other bulk action and deal reassignment stays in Phase 2.
- The Pipedrive owner name stays hidden: kept on each imported record (F4-a FR-M5), never shown on a record page or in an everyday list, and used only as the hand-out filter in F32-c.
Recorded as PRD Rev 47, F4-a spec Rev 4, the F4-d, F4-b, F32-b, F32-c and F5-h stubs, the tracker and features.md, and the client PRD (revised 30 September).
Addition to the line to Empire:
- The migration hand-out. Whoever runs the Pipedrive import — most likely your IT administrator — receives every imported lead and account first, then hands each representative theirs in bulk; the Pipedrive owner’s name is kept on each record only for that. The parallel run starts on a date we agree with you once the migration is ready, late in Phase 1, rather than early October.
2026-10-12 — the frontends’ unit and component tests leave PR CI, as the backend’s suite did
forge-et-fe’s Fast lane step “Unit and component tests” took 445 s and 782 s on recent ready-PR runs, and GitHub Actions minutes are one budget for the organisation (running out stops every workflow, deployments included). The backend’s suite left PR CI on 2026-09-28 for the same reason. The lead approved the same arrangement for forge-et-fe and forge-et-pwa, and asked that the three repos behave and read the same as far as the stacks allow:
- A local test record.
pnpm test:record(scripts/local-test-evidence.mjs, a byte copy inforge-et-pwa) runspnpm teston the committed head and adds or updates one PR comment whose first line is<!-- local-test-evidence sha=<commit> -->, with the Vitest counts and the time; it refuses a dirty tree and records nothing on a failure — the shape of the backend’slocal-build-evidence.py. - The
Fast lanechecks it. A newTest recordstep fails a ready PR intomainorrelease/*without a record for its head written by a delivery-team member (the base branch’s.github/CODEOWNERS*line), the same check as the backend’sBuild recordstep. A draft, a Dependabot PR, a PR into a wave branch and a PR that changes only documentation no test or build step reads (scripts/fast-lane-scope.mjs, the frontends’ counterpart ofslow-lane-scope.py) need none. The required check’s name staysFast lane. - CI still runs the tests every night on
main(skipped whenmainhas not moved since the last nightly run), on pushes torelease/*, on Dependabot PRs and on demand. The nightly run is kept because the git conventions rely on it to catch two PRs that merge cleanly but break each other’s tests. The coverage report becomes an artifact of the nightly run. - The order of work for a push to a ready frontend PR is commit →
pnpm test:record→pnpm e2e:gate --push; an app-repo PR now opens as a draft and is marked ready after its local record.
Recorded in .claude/rules/git-conventions.md § The test suites run locally, and the PR records them (which replaces the backend-only section), the Common Commands table, /forge-review-pr step 5, /forge-pr-open, /forge-deliver, review-record.md, coding-standards.md §7.1, test-strategy.md Rev 17, architecture.md and each frontend’s CLAUDE.md, e2e/README.md and PR template. Lead sign-off: Tharinda, 2026-10-12.
2026-10-12 — the suite runs once per PR, and every app repo has a Slow lane
The same day, the lead asked that the three app repos run their CI the same way and that local test runs be kept to the minimum, ideally one per PR, and chose the recommendation below:
- The local record becomes a required check. The record scripts (
local-build-evidence.py,local-test-evidence.mjs) set aTest recordcommit status on the commit they tested, linking to their comment, andTest recordis added to the required checks ofprotect-mainandprotect-releasesin all three app repos. The Fast lane’sBuild record/Test recordsteps, which read the comment and failed the lane, are removed. A new commit starts without the status, so the record runs once, after the PR’s last push, rather than before every push to a ready PR; a push no longer needs a CI re-run after recording. - A record carries across documentation. The script sets the check without running the suite when nothing a test or build step reads changed since a commit recorded on the PR, using the Fast lane’s documentation-only rule. Only a delivery-team member’s record is reused (the
*line of the base branch’s CODEOWNERS, as the removed Fast-lane step trusted). CI sets the check on a documentation-only PR intomainorrelease/*, in a job of its own after the Fast lane so the token that can write a status never runs beside the build tools, andforge-review-dependabot.yml(now the same file in all three repos) on Dependabot’s own commits, whose suite the Slow lane runs. Any writer on a repo can set a status, the same trust asForge review’s. - Every app-repo PR stays a draft through its review — a person’s PR,
/forge-deliver’s single-plan PRs and its wave PRs alike — so the record, and in the frontends the browser gate, run once, after the review’s last fix, beforegh pr ready./forge-review-prreports a missing record as owed during its fix rounds and requires it before anapproverecord on a ready PR. - The frontends’ tests move to a
Slow lanejob, with the backend’s condition (the nightly run, a push torelease/*, a manual run, a non-draft Dependabot PR), andSlow lanebecomes a required check there again. A skipped job is not billed, so the setup minute the 2026-09-28 merge of the lanes saved now costs only on those runs. - Caps: every
Fast lane15 minutes, everySlow lane30. The backend’s nightly suite took 13 to 19 minutes from 2026-10-04 to 2026-10-11 and hit its 20-minute cap on 2026-10-10. - Two consistency fixes:
forge-et-be’sscripts/slow-lane-scope.py, which decides the Fast lane’s scope, is renamedfast-lane-scope.py; and each record script’s--self-testruns in the Fast lane. - The browser gate keeps its mechanism (the
Browser gate:line the Fast lane reads). Its rule changes with the record’s: the push that marks a PR ready, and the last later push that changes a gate input, goes throughpnpm e2e:gate --push.
Recorded in .claude/rules/git-conventions.md § Pull Requests and § Branch Protection, .claude/CLAUDE.md § Quality Gates and the Common Commands table, review-record.md, release-and-branch-protection.md, /forge-review-pr step 5, /forge-pr-open, /forge-deliver, /forge-pre-pr-review, coding-standards.md §6.8 and §7.1, test-strategy.md Rev 18, architecture.md Rev 56, the team guide, the guides and the quality checklist, and in each app repo’s workflows, record script, CLAUDE.md and PR template. Lead sign-off: Tharinda, 2026-10-12.
2026-10-12 — claim a bug or feature before starting it
Teammates had fixed the same bug twice: one was working locally, with no PR yet, when another took the bug because its tracker row showed no owner. A tracker owner reached main only when the work’s PR merged. The lead asked for the claim to be the first step, for bugs and features alike, and for several tickets at once:
/et-claim <ticket> …(.claude/commands/et-claim.md) checks each ticket with.claude/lib/claim-check.pyagainst the tracker onorigin/mainand GitHub: free, already yours, taken (someone else owns it, has an open PR for it or pushed a branch named after it), closed or unknown. When every ticket is free or yours, it sets eachowner(and a bug’sstatus: in-progress) onmainthrough a small harness PR;--releasegives a claim back.- No auto-merge (the lead’s decision): the claim PR is merged when the person says so, or by them in GitHub; no required approval stands in the way.
/forge-deliverStage 0 runs the same check and halts on a ticket someone else holds; the bug-fix flow intracker.mdclaims first; the tracker’sdelivery.teamgains each person’sgithublogin, which names the owner.- A claimed feature gets
startedas well asowner, which keeps the tracker’s “a started feature has an owner” rule and/forge-doctor’s check true, and the dashboard now shows the owner of abacklogfeature that hasstarted. A claim waiting for its PR to merge answersPENDING, so a re-run opens no second claim; the work’s own harness branch is cut after the claim merges.
Lead sign-off: Tharinda, 2026-10-12.
2026-11-03 — Trivy’s advisory lag stays accepted (AD #27 revisited)
AD #27 accepted that the GitHub advisories Trivy reads can trail NVD by days to weeks, “to revisit when the release check is built (AD #38)”. With the release check in deploy-uat (F38-h FR-35) and deploy-prod (F38-i), the lead kept the lag accepted and added no second scanner: every app repo is scanned every night, and a UAT or production release stops on any open HIGH/CRITICAL finding. Dependabot reads the same reviewed advisories as Trivy (.forge/security/README.md), so it does not shorten the lag. What remains is the days between a publication and Trivy’s database learning of it, a small exposure for an internal CRM of about twenty users, against the cost of a second tool and a second suppression list. Recorded in AD #27’s row of .forge/design/architecture-decisions-why.md; the owed.md row that asked for it is closed.
Lead sign-off: Tharinda, 2026-11-03.
Architecture Decisions — full rationale archive
CLAUDE.md § Architecture Decisions keeps every row — the decision text is unchanged — but the Why column of the rows below was compressed to a one-line why plus a pointer here. The full original text of both columns is preserved verbatim, so nothing a lead signed off on is lost.
AD #29 — 2026-09-07
Decision (as written): The core/domain separation is no longer extended — reverses AD #17 by stopping it, not collapsing it. FS-12 (extension-point substrate) and FS-13 (core workflow primitives), both not started, are cancelled; AD #17’s acceptance test (“deleting domain-tea leaves a working generic CRM”) is retired as a design goal; no further extension points, typed extension tables or layer deliberations are undertaken for reuse’s sake. Everything FS-1/FS-2 already built stays physically in place and stays green — the crm-core/domain-tea modules, the core.*/tea.* schemas with their partitioned Flyway version space, and the four enforcement mechanisms (build graph, ArchUnit boundary + vocabulary rules, dependency-cruiser import rules, the core → tea FK check) — retained as scaffolding because removing it costs more than keeping it, not because the boundary still buys anything. New code goes where it compiles under those guards, without deliberating over core-vs-tea; an interface added because a guard requires one is plumbing, not a seam designed for a second domain. Each workflow primitive (ChecklistEngine/GateRule, RoundLifecycle, StaleClock, TagSetCompatibility) is built and sized by its first consuming feature. Nothing is refactored. Refined by AD #31 (2026-09-09) — the “stays physically in place” half is reversed: FS-14 removes the scaffolding; the cancellations (FS-12/FS-13, the retired acceptance test) and the first-consumer rule for the primitives stand
Why (as written): AD #17’s return rested on OQ-50 — reuse of the generic layer on future projects, assumed yes in August. That reuse is no longer expected, so the ~+8–15% of V1 the split costs has no payoff, and the remaining spend (FS-12 + FS-13) is cancellable. The cost already paid in FS-1 and FS-2 is sunk and is not an argument either way. Collapsing the split instead (one module tree, one schema, tea.* migrated into core.*, data-model §2 rewritten) was rejected as a real refactor on already-migrated schema with no payoff of its own. Accepted trade-offs: no reusable generic layer results from this engagement; two schemas and four guards remain as structure without a purpose — a later decision may remove them if they get in the way; F26’s data model (forge-et-be/docs/data-model.md §2, on tea.*, shipped by FS-2) needs a named owner now that no slice owns its substrate. Lead sign-off: Tharinda, 2026-09-07 — given as the approvals on harness PR #52 and forge-et-be PR #15 (required because AD #17 is a DO-NOT-REVERSE row). No change request: the issued proposal never described the split, nothing client-visible changes, and the reversal only lowers cost — L-001 governs scope, price, timeline and providers, not internal structure
AD #30 — 2026-09-07
Decision (as written): Role management is fully configurable, on a code-declared permission catalog — refines AD #15; AD #26 survives intact and is strengthened. The grant tuple becomes (role, permission_key, scope). The catalog is code; the grants are data: each module declares its permissions as constants with metadata (key shaped <resource>.<action> — deal.view, deal.create, quote.issue, price.publish; category; label; description; UI group; whether scope-aware), roughly 100–150 keys covering the system; the database stores only which role holds which key at which scope, and the admin UI renders from the catalog, so an admin can only grant something the code actually checks. Admin-authored roles: Empire creates roles and attaches any catalog permissions. Role templates: built-in templates for the six confirmed roles (plus the seeded managing_director profile) and admin-created ones; creating a role from a template copies the permission rows — a snapshot, never a link — so editing a template cannot silently mutate live roles. The four levels (read / edit / ai-use / execute) survive as the category metadata on each permission, not as a grant column — this is load-bearing: the ai-use-vs-execute split is what makes the PRD’s human-in-the-loop promise structural, and as metadata it becomes more visible (the role editor can warn “this role holds N outward-acting permissions”). A reporting hierarchy: app_user.manager_id, a nullable self-reference; visibility scope becomes own | team | all, where team is the subtree beneath the user. Scope is per-permission, not per-role: a Sales Manager may hold deal.view at team while holding deal.edit and mailbox.read at own — a per-role scope would have a manager reading their reps’ personal mail; the catalog declares which permissions are scope-aware at all. Multiple roles union to the most permissive grant. AD #26 is unchanged in every check: code asks user.can("quote.approve_sub_floor"), never which role or template the user holds. The catalog is not enumerated here — that is FS-6 spec Rev 3’s and F5’s work; only the key shape, the ordering convention (<resource>.<action>, grouped by resource) and the metadata fields are locked. Refined by AD #32 (2026-09-11): no role templates (only the system superadmin ships), one role per user (no union), and AI is not a grantable level — the category axis is read / edit / execute. The catalog, grants-as-data, the hierarchy and AD #26 stand
Why (as written): Empire asked for a fully configurable role-management system (2026-09-07). A fixed matrix with per-role levels (PRD Rev 17) cannot express it, and retrofitting configurability onto a level-column model after FS-6 ships is the expensive failure mode AD #15 was written to avoid. Keeping the levels as catalog metadata preserves the one property Rev 17 made structural — the AI layer never holds an outward-acting permission — while letting Empire shape everything else. Accepted trade-offs: ~100–150 permissions needs UI grouping (the UI group metadata) or the role editor is unusable; a renamed permission key orphans existing grants, so an orphan-grant check (startup or CI) is owed; new permissions ship un-granted — fail closed — making “update roles and templates” a required release step for every feature that adds keys; an admin can lock themselves out, so a non-deletable system superadmin role and last-admin protection are required. Treated as a V1 requirement — no change request (Dinil, 2026-09-07). Proposal §3.2 quotes six roles plus fixed granular levels, and PRD § Multi-Tenancy had deferred structural hierarchy; per L-001 that divergence is stated, as a post-issue note on the proposal’s header, not silently absorbed — and the whole client-facing pack, the Who Can Do What role-access document included, is restated to the configurable model in the same change. F5 grows materially (role authoring, templates, manager assignment, an effective-permissions viewer) and the added scope is recorded against R-ARCH-001. Lead sign-off: Tharinda, 2026-09-07 (required because this reverses PRD Rev 17, which Tharinda approved, and refines a DO-NOT-REVERSE row)
AD #31 — 2026-09-09
Decision (as written): The core/domain split is collapsed — nothing of it remains. Supersedes the module/schema half of AD #17 and the “stays physically in place” half of AD #29; AD #29’s cancellations (FS-12/FS-13, the retired acceptance test) and its first-consumer rule for the workflow primitives stand. Backend: one Gradle module — a single build.gradle (no buildSrc, one gradle.lockfile), feature-first packages com.empireteas.<capability> with no core/tea/app segments (platform, catalog, pricing, then one package per feature as it lands; layers web/service/repository inside each), one Postgres schema (public), one Flyway location with the shipped migrations squashed into a fresh V1… sequence (nothing was ever deployed or migrated — confirmed 2026-09-09). Frontends: forge-et-fe becomes one package (no pnpm workspace, no tsc -b) laid out src/{app, features, ui, lib}; forge-et-pwa mirrors the layout and keeps byte-copies of the shared token files behind a drift check. The split’s guards go (build graph, BoundarySpec’s boundary rule, VocabularySpec, ExplicitSchemaSpec, CoreToTeaFkSpec, CoreOnlyMigrationSpec, the version-band map, the cruiser package rules); every hygiene guard stays (Error Prone/NullAway, -Werror, doclint, @NullMarked, the src/test/java guard, fixture reachability + leak, FS-10’s web → service → repository layering, testid/bundle/Trivy/coverage) and one is added: feature packages and folders must be free of dependency cycles, with platform/ui depending on no feature. Plain Spring Boot — no Spring Modulith. Delivered as foundation slice FS-14 (.forge/specs/foundation/014-single-module-spec.md)
Why (as written): AD #29 kept the scaffolding on the judgment that removal cost more than keeping. Opened up (2026-09-09) the scaffolding is mostly ceremony — 13 of 16 backend modules and 2 of 3 frontend packages are near-empty shells; the substance (~11k lines a side) moves rather than rewrites — while keeping it taxes every one of ~30 features (a Layer Classification per spec, a module and a version band per change, 16 lockfiles, guards with no purpose, out-of-order Flyway — L-014) for a payoff AD #29 had already declared gone. A tidy feature-first monolith is also the shape AI-assisted extraction handles well, so the reuse option survives without paying to keep it. The cost of removal is at its lifetime minimum — no environments, no feature code, Gate 3 not run, no open worktree — and rises with every slice built on the split. Accepted trade-offs: ~4 working days added to the Foundation band (R-ARCH-001), recouped within the engagement by the per-feature tax removed; a code freeze on forge-et-be/-fe/-pwa while FS-14 is open (from 2026-09-09; PRs raised meanwhile re-integrate onto the collapsed main); FS-6’s approved spec takes a Rev 4 and its draft plan (harness PR #58) is revised against the new layout; the five shipped slices’ specs and plans are annotated, never rewritten, and nine of their 111 acceptance criteria are retired as split-only (spec Appendix C); F26’s data model (docs/data-model.md) gets its owner — Tharinda. Lead sign-off: Tharinda, 2026-09-09 — given as the approvals on the FS-14 harness PRs (required because AD #17 is a DO-NOT-REVERSE row and AD #29 refined it). No change request: internal structure only — L-001 governs scope, price, timeline and providers
AD #32 — 2026-09-11
Decision (as written): Role management is simplified — refines AD #30; the catalog/grant model and AD #26 stand. Three changes. (1) No role templates. The role_template concept goes; the only seeded role is the non-deletable system superadmin. Empire’s Administrator creates every other role by hand from the code-declared permission catalog, with Altrium supervising at go-live; the six confirmed roles (plus the Managing Director role) become the recommended day-one set recorded in the PRD’s capability matrix and client/roles-and-permissions.md, not seeded data. (2) One role per user. app_user.role_id replaces the M:N join; the most-permissive union disappears; a person who needs a mix gets a purpose-built role; a role still held by a user cannot be deleted; last-admin protection stands. (3) AI is not a grantable level. The category axis is read / edit / execute (client-facing: View / Edit / Act). AI the system runs on its own (lead scoring and triage, inquiry extraction on intake, account briefings, the morning briefing, duplicate/spam detection) is not a permission — its results are visible under the record’s read, and the per-feature {model, enabled} switch (AD #19) is the control. AI a user invokes on a record (draft an email, the quote assistant, the brief assistant) is implied by the edit/execute permission it assists — whoever may send may ask for a draft. The human-in-the-loop invariant is unchanged: the AI layer holds no permission, and committing any AI output is an execute action a person performs. Grants stay (role, permission_key, scope) over the code catalog; manager_id and own/team/all per permission stand; AD #26 is untouched
Why (as written): Team decision — Tharinda, 2026-09-11, to remove unwanted complexity; confirmed by Dinil. Templates added a copy/reset/provenance mechanism (template_key, role_template* tables, “reset to template” semantics, template-vs-role editing rules) that nobody had asked for and that Empire’s Administrator would have to learn; multi-role union added a second resolution rule and made “why can this person see this?” harder to answer than a single role does; a grantable ai-use category let an Administrator hand out “AI” detached from the action it serves, which is meaningless — a draft nobody may send is noise — and double-counted what the per-feature switch already controls. Removing all three shrinks FS-6 and F5 (R-ARCH-001) rather than growing them. Accepted trade-offs: a fresh environment has no roles until an Administrator creates them (a supervised onboarding step; the first-administrator provisioning hand-off from FS-6 stands); people doing two jobs mean more roles (role sprawl — mitigated by the effective-permissions viewer and the release note naming which roles a new key is recommended for); AI features are switched per feature by configuration, never per role. Consequences: FS-6 spec Rev 5 + plan revision (own PR); PRD Rev 24; the client pack restated as a team decision stated to the client (post-issue note on the proposal, no change request); the prototype’s template markers, two-role person and AI-assist chip await a prototype PR. Lead sign-off: Tharinda, 2026-09-11 (his decision; required because AD #30 refines a DO-NOT-REVERSE row)
AD #33 — 2026-09-24
Decision (as written): The backend keeps its own address; the apps call it cross-site (register A-4, option (a)). The backend stays at api.<env> behind the ALB; each app’s CloudFront distribution serves only its static bundle. The CRM (crm.<env>) and the capture app (capture.<env>) call the backend at VITE_API_BASE_URL = https://api.<env>. The backend’s CORS list names that environment’s two app origins, with credentials allowed (already the code’s shape). The XSRF-TOKEN cookie is given Domain= the environment’s CRM host (crm.empire.lk, uat.crm.empire.lk, dev.crm.empire.lk) so the SPA can read it and echo X-XSRF-TOKEN; the capture host sits under the same domain, so it can read it too. The cookie’s name differs per environment, because crm.empire.lk is the parent of the dev and UAT hosts and prod’s cookie also reaches them — without distinct names a browser that has visited both carries two cookies of one name and writes fail at random. The SESSION cookie stays host-only on api.*; crm.* and api.crm.* are the same site (empire.lk), so SameSite=Lax still sends it on credentialed calls. The Entra reply URLs stay on api.*: the three sign-in URLs registered on 10 Sep keep working, three mailbox URLs are added, and the capture app reuses the sign-in URLs.
Why (as written): Two options were weighed (the register’s A-4 row, 2026-09-23/24). (b), routing the backend paths through each app’s CloudFront, needs no application code but more CloudFront configuration (four path rules, a second origin, the viewer’s host passed through) and nine new reply URLs with the registered three retired. (a) keeps CloudFront to static hosting and keeps the registered reply URLs. The lead chose (a) for less AWS configuration and fewer changes on Empire’s Azure side, accepting a small cookie change in the backend and both frontends, per-environment settings that must match, and a CORS preflight on writes. A one-origin decision (b) was briefly recorded as AD #33 on 2026-09-23 and withdrawn the next day, before anything was built. Lead sign-off: Tharinda, 2026-09-24.
Security note: every host sits under crm.empire.lk, so dev and UAT are the same site as production — SameSite=Lax gives no separation between them, and production’s CSRF token is readable by scripts on the dev and UAT hosts. That is acceptable: the CSRF token is not a credential (the SESSION cookie stays host-only on api.crm.empire.lk), and production’s protection rests on the session cookie plus its own CORS list, which names only production’s origins. Keep dev and UAT free of untrusted scripts all the same.
Work it creates — tracked as F5-j (Phase 1, owner not assigned): the backend CsrfTokenRepository takes a configurable cookie domain and name; the frontend reads the cookie name from build config instead of the fixed XSRF-TOKEN (the capture app does the same in F36-a); per-environment values are listed in the register’s §D and set by F38.
AD #34, AD #35, AD #36 — 2026-09-24 (one design conversation)
How they were reached. Between 2026-09-22 and 2026-09-24, while F5-c (user management) was being delivered, the lead (Tharinda) set out his model for users, roles, the reporting hierarchy, authorization, sharing and audit in two long written briefs, then answered a series of multiple-choice questions on every point where his model, the shipped FS-6 code, the PRD and the client documents disagreed. The three decisions below are the result. They refine two DO-NOT-REVERSE rows (AD #30, AD #32), so each carries the lead’s explicit sign-off (“go ahead with all of them”, 2026-09-23, and the final choices of 2026-09-24). Which parts are his words and which are the delivery team’s: the model itself — who administers, no predefined roles, the minimal catalog, one role per user, own/team/all, the roll-up, transitive sharing under manage, removing a share in V1, reassignment under manage, reassign-before-deactivate, the manager-exit block, the own-mailbox rule, the unowned-records rule, the first admin by migration, and the audit trail — is the lead’s, from his two briefs and his answers. Several details are delivery-team technical calls, listed to him on 2026-09-23 under “technical calls I’m taking myself (veto any)” and not vetoed: changing a user’s email clears the identity link; the minimal name-and-role user directory; children follow their parent’s reach; deactivated users stay in the tree and shares to them stay inert; a role’s key is generated at creation and never changes; the last admin may move to another admin role; one visibility rule serves lists and single records; and no logout on a permission change (which replaced the session-kill he had accepted, under his delegation of that call). The account page showing only the final price is a default still awaiting his answer.
AD #34 — Decision (as written): Access is configured, never predefined, on a minimal catalog. Sign-in needs an active, pre-created app_user whose email matches the Microsoft-verified one; there is no auto-provisioning and no invitation email (closes OQ-51’s provisioning fork). Users are deactivated and reactivated, never deleted; deactivation refuses future sign-ins and ends the user’s existing sessions immediately (their next request is answered 401); nobody can deactivate themselves; in-app deactivation is the offboarding control, with Empire disabling the Entra account as a backstop (no Entra sync in V1). Changing a user’s email clears their Microsoft identity link. There are no predefined roles: no templates, no seeded business roles, no superadmin or break-glass role, no non-deletable system role, no * wildcard grant. A role can be created, renamed (its generated key never changes), re-permissioned, and deleted only while no user — active or deactivated — holds it. One role per user. The first admin comes from a migration (the lead chose this over a startup job on 2026-09-24): one Flyway migration seeds, in every environment, an editable “IT Admin” role holding access.manage and one active user holding that role. The user’s email is a Flyway placeholder supplied per environment: crm01@empire.lk — one of Empire’s crm01–crm05@empire.lk test mailboxes — for laptops, dev and UAT; in production the admin address Kavindu confirms (not yet confirmed), supplied at deploy from AWS Secrets Manager and never written into git. Never a real person’s email outside production. The runtime first-administrator job that F5-a built retires. A tester who wants one login that can do everything grants their own role every permission — configuration, not code. The catalog: each business entity has <entity>.view (read-only) and <entity>.manage (create, edit and every action on it — share, remove a share, reassign the owner, AI-assisted drafting); manage implies view. Separate keys exist only for special actions: price.publish and, in Phase 2, quote.approve_sub_floor. All user, role and hierarchy administration is one unscoped access.manage (replacing user.view/create/edit/deactivate/manage, role.view/manage/assign, hierarchy.edit, permission.view_effective, audit.view, platform.loggers.write); configuration is one settings.manage; a user’s own mailbox is one email.manage — no role can ever read another person’s mailbox. There is no read-only user-list permission and no category axis. The Phase 1 keys are access.manage, settings.manage, email.manage, lead.view/lead.manage, account.view/account.manage, buying_standard.view/buying_standard.manage and price.publish; Phase 2 adds deal.*, quote.*, sample.* and quote.approve_sub_floor. buying_standard.view shows the whole build-up — costs, margins, the floor and the LKR figures — so there is no separate cost key. (Default awaiting the lead — not part of the sign-off: the account page shows that customer’s standards with only the final published USD price under account.view, so a rep can send prices without seeing the book; offered on 2026-09-24 with “veto it if you disagree”, not yet answered.) At least one active user always holds access.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 is the control. Permission changes apply on the holder’s next request, because the backend re-reads grants on every request; there is no forced logout, and the frontend re-reads /me after a 403 and when the window regains focus.
AD #34 — Why (as written): the lead wants Empire to build every role from scratch, with the fewest permissions that describe the work (“manage leads” rather than create lead, edit lead and a key per action) and separate keys only where a business rule needs one. A seeded, undeletable superadmin was a risk nobody wanted handed to Empire or kept by Altrium; nine admin keys split work one person always does; the read / edit / execute axis duplicated what view / manage already says. The first person into a fresh environment needs a user and a role that can administer, and a migration is the one place that runs before anyone can sign in. Accepted trade-offs: a fresh environment’s only role is IT Admin until the admin builds the rest; if Empire’s only admin leaves without handing over, recovery is a one-off database fix by whoever runs AWS (recommendation to Empire: keep two people in an admin role); production cannot start until its admin email is supplied, because Flyway refuses a migration with an unset placeholder; the lead first accepted ending sessions on every permission change, and that was dropped (the lead delegated the call) because the backend already applies changes on the next request. Consequences: FS-6 spec Rev 12 and new feature F5-k (the code); F5-c and F5-d re-scoped; PRD revision; the client role document and the issued client pack restated; a post-issue note on the proposal. Lead sign-off: Tharinda, 2026-09-24.
AD #35 — Decision (as written): A record has one owner and can be shared; a share widens reach, never authority. Each lead, account, deal and quote carries one owner_id — NOT NULL except on leads, where it is nullable only for import edge cases. Shares are rows in one record_share table: one nullable foreign key per entity type (account_id, lead_id, later deal_id, quote_id) with a check that exactly one is set, plus shared_with_user_id, shared_by_user_id and shared_at, unique per record and user — never array columns. Reach is per grant: own = records I own or that are shared with me; team = records owned by, or shared with, me or anyone below me in the reporting tree, all levels down; all = every record, unowned ones included. own and all need no walk of the tree; only team does. Whether a manager may edit team records is configuration (manage at team versus view at team). One visibility rule serves both list queries and single-record checks. A user may act on a record only if their role holds the needed key and the record is in reach. Shares roll up the tree: a manager sees records shared with anyone below them. Sharing is transitive: someone who reached a record through a share may share it on. Sharing, removing a share and reassigning the owner need the entity’s manage; removing a share is in V1. The share picker offers only active users whose role holds the entity’s view key and who do not already reach the record; users who already reach it are not listed (existing shares appear in the record’s shared-with list, with Remove, not in the picker); users whose role cannot see that entity type are not listed either. Reassigning needs a new owner who is active and holds the entity’s view key; shares survive; the previous owner loses reach unless shared back. A user who owns any lead, account, deal or quote cannot be deactivated until their records are reassigned (PRD Rev 23 applied everywhere), and a user with direct reports cannot be deactivated until the reports are re-parented. Deactivated users stay in the tree; shares to them stay, inert and removable. Children follow their parent’s reach. Unowned records are visible only to all-scope holders (the lead lists get an “Unassigned” filter, not a queue). Record-linked mail follows the record’s reach; the mailbox itself stays its owner’s alone. A minimal user directory (active users’ names and role names) is readable by any signed-in user for the pickers; the admin user list stays behind access.manage. The owner pattern, record_share and the one visibility rule are built once, as a substrate (F5-f), before any list read-path.
AD #35 — Why (as written): the lead’s brief described exactly this: an allowed_users idea per record, the reporting tree for managers, own/team/all because some people (an analyst) need everything without owning anything, and a share picker that offers only people who cannot already see the record. The relational form keeps his allowed_users meaning (owner plus shares) while keeping one explicit owner, which reassignment, offboarding and “my records” need, and it gives foreign keys, “who shared it and when”, and an index for “which records can this user see”. One rule for lists and records answers the mismatch F1-a ships as a recorded interim (its FR-O3 and Q-11, and the F5-f stub): the account list filters team as own while the single-record check walks the tree, so a manager can open a report’s account by its link but not see it in the list. Accepted trade-offs: transitive sharing plus roll-up means a share across reporting lines becomes visible up the recipient’s chain, and anyone with manage can spread a record further — accepted because removing a share is in V1 and every share is audited. Consequences: F5-f re-scoped to the substrate; F5-g becomes the sharing screens; F5-h shrinks to bulk reassignment; F1-b and F11-b wait for the substrate; the record-sharing memo, the entity map and the PRD revised; a courtesy note to the lead that his sketch was read as owner plus shares was delivered in the conversation itself. Lead sign-off: Tharinda, 2026-09-24.
AD #36 — Decision (as written): Every write and every security event is recorded in one audit trail in the database. One audit_event table and a small service, written in the same transaction as the change it records: the actor (a user, or SYSTEM for background jobs), the action, the record, the time, and the change. It covers every mutating action plus sign-in success and refusal, sign-out, deactivation and reactivation, role and permission changes, sharing, share removal and reassignment, and exports. Reads are not recorded. Rows are kept indefinitely in V1. There is no viewer screen in V1; the trail is queryable in the database. Every table carries created_at and modified_at (framework-owned tables such as Spring Session’s excepted), and created_by and modified_by where a person makes the change. Built as F39: F5-c and F5-d wait for it, it retrofits the writes already on main, and later writing features call it.
AD #36 — Why (as written): the lead asked for “all actions done by all users in the entire system” to be audited and kept in the database, as the answer to unlimited self-escalation — it is what lets Empire find out afterwards who granted what. One shared table and service stop each feature inventing its own. Accepted trade-offs: the table grows without limit in V1 (small at Empire’s scale); no screen means an audit question is answered by us from the database until a viewer is built. Consequences: new feature F39; every writing feature calls the service; the FS-7 SYSTEM principal owed item is discharged by F39. Lead sign-off: Tharinda, 2026-09-24.
Line to Empire — draft, for Tharinda to send (the client documents were restated on 2026-09-24; this tells Empire what changed from what they were told, and asks for the one new input):
Subject: CRM access — a few changes to what we told you, and one new item we need
We have simplified how access works in the CRM; the updated Who Can Do What marks every changed point. In short:
- No built-in Administrator role. The system starts with one ordinary role, “IT Admin”, held by one account; your administrator signs in with it and builds every other role. The six roles we proposed are a recommended starting set: your administrator can create them as proposed, rename them, or build different ones.
- Permissions: each area has two — View and Manage — plus a few named ones that stand alone: publishing prices, approving a below-floor quote, user and role administration, system settings, and your own mailbox.
- No invitation email. Your administrator adds a person in the CRM and tells them; nobody can sign in unless they have been added.
- Leads nobody owns (only import edge cases) are seen only by roles that see everyone’s records, through an “Unassigned” filter on the lead list — not by every manager.
- Shared records can be passed on. Anyone who can work on a record can share it, including someone it was shared with, and any of them can remove a share. Every share is recorded.
- Leavers: a person cannot be deactivated until their records are reassigned and anyone reporting to them has a new manager (we had said their records would stay put). Deactivation ends their sessions at once; people are never deleted.
- Managing Director approval of below-floor quotes — and the Tea Room alone publishing the weekly prices — are the default set-up rather than rules the system enforces: whoever administers users and roles could give either right to another role, including their own, and every such change is recorded. Earlier we said an administrator could never approve a below-floor quote; that is now a matter of how the roles are set up. We recommend you keep at least two people in an administrator role.
- info@ stays outside the CRM: please forward inquiries to the rep who covers them; their own mailbox brings them in. If you prefer, info@ can be added as an ordinary user, as long as it is a licensed mailbox that can sign in to Microsoft.
One new item we need: the email address, confirmed by your IT, of the account that will start as IT Admin on the live system. The live system cannot start without it.
AD #37 — 2026-09-27
How it was reached. On 2026-09-27 the lead (Tharinda) wrote out his access model as four small tables — seven users with a role and a manager, five roles holding strings such as leads+team+manage, and leads and accounts each with a list of allowed users — and asked whether it worked and how it should be stored. The delivery team confirmed it gave the intended results and proposed the relational form already decided (AD #34, AD #35). The lead then proposed a further simplification: drop the own and team scopes, because the reporting hierarchy already decides them, and keep only an extra permission such as “access all leads”. The delivery team checked the lead’s example under the new model — every user reaches exactly the leads and accounts they reached before — and checked the recommended roles in the PRD capability matrix and client/roles-and-permissions.md: none holds one reach for view and another for manage on the same entity. The lead confirmed the design and asked for every document, table and feature to be realigned. Delivery-team calls, stated to the lead and not part of his sign-off: the key is named <entity>.all; it widens whichever of view or manage the role holds and is refused without one of them; it exists for every entity that has an owner, samples included; the code change is a new feature, F5-l, after F5-k rather than inside F5-k’s open waves, because F5-k’s wave 1 was already in review.
AD #37 — Decision (as written): A grant has no scope; the grant is (role, permission_key). A key on an entity that has an owner (lead, account; deal, quote, sample in Phase 2) reaches the records owned by, or shared with, the user or anyone below them in the reporting tree, through every level. For a user with nobody below them that is the records they own or that are shared with them — what own meant; for a manager it adds the team’s records — what team meant. Each such entity has a third key, <entity>.all, which widens the holder’s view or manage on that entity to every record, unowned ones included; a role cannot hold it without the entity’s view or manage. Everything else in AD #34 and AD #35 stands: manage implies view; mailboxes are outside every reach; unowned leads are reached only through lead.all; the share picker, transitive sharing, children following their parent, and one rule for lists and single records.
AD #37 — Why (as written): for a user with nobody below them, team already gave exactly what own gave, so the choice between them only ever mattered for managers — and the reporting line already records who manages whom. The only reach that needs a setting is “every record”, for people such as an analyst who own nothing. The role editor loses a scope choice on every key, the grant table loses a column, and the effective-permissions view has less to explain. Accepted trade-offs: a role can no longer reach further with view than with manage on one entity (A-6’s alternative in the client role document — managers view their team’s records but only the owner edits — and a variant of A-9 in which reps see every lead but edit only their own, are no longer possible; if Empire asks for either, the fix is to split the entity’s all key into a view-only and a manage variant, an additive change); and a user with people below them always reaches those people’s records, so setting a user’s manager is an access decision. Consequences: PRD Rev 43; the new feature F5-l removes the scope from the code and adds the all keys to FS-6 Appendix A, and blocks F5-d, F5-e and F5-f; the specs of those three and of F5-c, F11-b, F1-b, F2-a, F4-a, F4-b and F4-d restated; the client role document restated before it is sent. Lead sign-off: Tharinda, 2026-09-27.
Addition to the line to Empire above (one more bullet, to go in before it is sent):
- No reach setting per permission. A person sees their own records and the records of everyone below them in the reporting line; one tick per area that has owners — “all records” — lets a role reach every record in that area, including records nobody owns, with the View or Manage it holds there. So a manager who may work leads can work their team’s leads; the earlier option of managers seeing their team’s records without being able to change them is withdrawn.
AD #23 — location revised 2026-09-29
The lead confirmed that the Terraform and the rest of the DevOps work live in a separate repository, altrium-io/forge-et-iaac (created empty on 2026-09-29), where Shyamin Ayesh builds the AWS estate in Empire Teas’ own account. This answers the question the register (§C-3, “Start here” step 2), environments-and-identity.md §4 and the F38 spec (W-6 / OQ-B) had carried since Ayesh first raised a separate repository. The rest of AD #23 — Terraform for everything, modules per environment, per-account S3 + DynamoDB state, the temporary uat instance — is unchanged. Still open, and answered from Ayesh’s setup: how the delivery team reviews changes in that repository and which of the harness conventions (CODEOWNERS, branch protection, the PR template) it adopts. The row as it stood before this change:
| 23 | All AWS infrastructure is Terraform-managed — environment-parameterized modules instantiated per account (dev, prod, and a temporary
uatinstance applied for each acceptance window and destroyed after it); state in S3 with DynamoDB locking, per account; lives inforge-et-be/terraform/| The per-phase temporary-UAT commitment is only cheap if an environment is oneterraform applyaway; IaC also keeps dev and prod the same shape | 2026-08-19 |
AD #23 — state locking revised 2026-10-02
AD #23 said the Terraform state is locked with a DynamoDB table. forge-et-iaac, where Shyamin Ayesh and Senuthmi Thimansa build the estate, locks it with S3’s own lock file instead (backend "s3" { … use_lockfile = true } in overlays/dev/providers.tf on origin/dev, as of 2026-10-02). Recent Terraform releases provide this native S3 locking, and HashiCorp recommends it over the DynamoDB table, which F38-a’s gap-check had already raised as W-5. A check of stale notes on 2026-10-02 found the difference, and the lead (Tharinda) accepted S3’s lock file the same day: it is what DevOps built, and it needs no extra table. The rest of AD #23 is unchanged. Changed with it: architecture.md § Infrastructure as code, the register’s “Start here” step 8 and its §C Terraform row, the F38 spec’s FR-3 and AC-3 (Rev 6), and F38-a’s FR-5, W-5 and Input Sources. Lead sign-off: Tharinda, 2026-10-02. The row as it stood before this change:
| 23 | All AWS infrastructure is Terraform-managed, in its own repository,
forge-et-iaac(notforge-et-be/terraform/), which holds the Terraform and the rest of the infrastructure code: environment-parameterized modules per account (dev, prod, and a temporaryuatinstance applied for each acceptance window and destroyed after it), with state in S3 and DynamoDB locking per account | The per-phase temporary UAT environment is only cheap if it is oneterraform applyaway, and IaC keeps dev and prod the same shape; DevOps (Shyamin Ayesh) works in the separate repository, which the lead confirmed on 2026-09-29 | 2026-08-19 (location revised 2026-09-29) |
AD #23 — UAT lifetime revised 2026-11-18
How it was reached. On 2026-11-18 the lead planned Phase 1’s UAT round as two releases: what is ready around Mon 30 Nov, then a second release with F20-f, F20-j and F44 and any other open Phase 1 work while Empire tests (.forge/active-context.md § Release plan). AD #23 had the uat instance applied for each acceptance window and destroyed after it. A destroy deletes UAT’s database, so between the two releases the IT Admin would re-enter .forge/plans/F38-h/uat-data-checklist.md by hand and Empire’s testers would lose their records. Claude recommended keeping one instance up for both releases; the lead agreed and extended it to Phase 2, in their words: “Keep it running - go with your recommendation. once both uat rounds are done we can decommission uat env after phase 2.” Later the same day the lead asked whether two environments holding one tester’s mailbox could clash once production is live, and proposed pausing UAT after Phase 1’s UAT and before production goes live, keeping its database so it can be revived. They lean towards stopping the backend and frontends, and leave the final choice to Shyamin Ayesh (stop, snapshot and remove, keep running, or decommission), adding: “none of these should be automaticcally triggered by aws bsaed on some day. it should be manually done by a person”.
Decision (as written): one uat instance is applied for Phase 1’s acceptance round (after F38-h’s rehearsal destroys and re-applies it, F38-h spec FR-9 steps 8 and 10), kept with its data through Phase 1’s second release and Phase 2’s round, and destroyed after Phase 2’s round when the lead decides. Between the rounds Shyamin Ayesh (DevOps) decides whether it is paused with its data kept (backend and frontends stopped, or a database snapshot and a re-apply from it), kept running, or destroyed and applied afresh for Phase 2. Every pause, revive and destroy is done by hand by a person, never triggered by a date or a schedule (.claude/rules/tracker.md § Release & UAT Lifecycle). Each release reaches it as a new tag through deploy-uat.
Why (as written): the hand-entered data and the testers’ records survive both of Phase 1’s releases and carry into Phase 2, and no one re-enters the checklist. Cost: about 11 weeks at $9–14 a week, about $100–155 in all, on what dev actually costs to run (.forge/owed.md, “The cost annexe’s dev figure is about half of what dev costs”; F38-h NFR-1’s estimate of about $40 for three weeks); .forge/client/sow-cost-annexe.md §4 states it from 2026-11-18.
The AD #23 row as it stood before: “… environment-parameterized modules per account (dev, prod, and a temporary uat instance applied for each acceptance window and destroyed after it), with state in S3 per account …”
AD #19 — models revised 2026-09-30
The lead replaced Claude Sonnet 5 with Claude Sonnet 5.5 as the synthesis model, since Sonnet 5.5 reached Bedrock on 2026-09-28, and set Haiku 5.5 to replace Haiku 4.5 once it reaches Bedrock. AWS’s model pages, read the same day, also showed that neither model runs in-Region on Bedrock’s bedrock-runtime endpoint: Haiku 4.5 is offered through the us. geo profile (requests may run in us-east-1, us-east-2 or us-west-2) or the Global profile, and Sonnet 5.5 through the Global profile only, which may process a request in any commercial Region. So the row’s “where every pinned model is native” was dropped, “served inside the project’s AWS account” became “called from the project’s AWS account” (the call is made from the account; where it is processed depends on the profile), and the profiles are recorded in ai-provider-strategy.md §4b. The PRD’s OQ-15 resolution said the models run “inside the project’s AWS account and region”; the lead reopened OQ-15 for its location part the same day (PRD Rev 48, client question Q18), with the default that processing outside the Region and the US is acceptable unless Empire asks otherwise — the lead expects Empire not to mind, and a US-only route costs 10% more. The lead’s direction is to use Sonnet 5.5 now, through the Global profile, and to move to a US-only route only if Empire asks; the worldwide-routing point is a divergence from the proposal’s “inside Empire Teas’ own AWS account and region” (§A.3.1, §A.6.5), stated in a post-issue note on the proposal. The region itself (us-east-1, AD-O-9) is unchanged here; the dev Terraform applies to us-west-2 as of 2026-09-30, and the lead decides that after talking with Shyamin Ayesh. The rest of AD #19 is unchanged. The row as it stood before this change:
| 19 | AI runs on Claude via Amazon Bedrock exclusively — Haiku 4.5 (high-volume) / Sonnet 5 (synthesis) served inside the project’s AWS account (
us-east-1, where every pinned model is native); no direct-API tier in production and no second-provider fallback (outages degrade to the manual path); per-feature{model, enabled}runtime config. The one sanctioned exception is the proposal’s A.3.1 comparison, run on anonymised inquiries with Altrium-held evaluation keys (ai-provider-strategy.md) | One vendor relationship and one bill, with in-account processing as the strongest data-governance answer; Bedrock’s new-model lag is acceptable because models are pinned (ai-provider-strategy.md) | 2026-08-18 |
AD #27 — lane corrected 2026-10-02
A factual correction, approved by the lead, with no rule changed. AD #27 said the Trivy scan was “one trivy fs Slow-lane step per repo”. On 2026-09-28 the scan moved into the Fast lane job in all three app repos: in forge-et-be with commit 6767007 (the test suite left pull-request CI), and in forge-et-fe and forge-et-pwa with commits cedde33 and cc8f8e1 (every check in one job). The row now says “Fast-lane step”. The same correction was made in .forge/security/README.md, .forge/security/trivyignore-reference.yaml, .forge/test-strategy.md and .forge/team-guide.md. The same day, AD #36 and AD #37 were moved to the past tense where they described their build as future work: F39 and F5-l are both done, so “F5-c and F5-d wait for it” and “F5-l changes the code” no longer held. AD #38 (below, the same day) made the same lane correction independently and rewrote the row’s report-only clause.
AD #38 — 2026-10-02
How it was reached. On 2026-10-02, while the backend Dockerfile was being built ahead of F38-d (forge-et-be PRs #136 and #144), trivy image reported three CRITICAL Tomcat advisories and ten HIGH Jackson advisories in the libraries Spring Boot 4.1.1, then the newest 4.1.x, manages. The lead first chose to wait for a Spring Boot release, then decided the same day to override the versions now and remove each override on the Spring Boot upgrade that catches up (forge-et-be PR #145). The lead also said dev deploys must not wait on vulnerabilities: scans must report and be fixed later, never block. Two records said otherwise. F38 FR-22 listed “the Trivy gate is enforcing” as a condition of the first dev deploy, and AD #27 planned to switch the PR gate to failing builds. Offered three scopes (never block; block production only; block PRs later but not deploys), the lead chose “never block”. The issued proposal’s §A.4 standing controls then turned out to promise “a build pipeline that fails on any dependency vulnerability at CVSS 7.0 or above, with exceptions requiring written justification and an expiry date”. Offered the choice between blocking only UAT and production releases, which keeps that promise for what Empire receives, and never blocking with a post-issue note to Empire, the lead chose the release check.
AD #38 — Decision (as written): Vulnerability scans report everywhere and block only what Empire receives. Trivy runs on every app-repo PR and on every image deploy-dev builds, and reports HIGH/CRITICAL findings without failing the PR, the merge or the dev deploy; TRIVY_GATE_EXIT_CODE stays 0. A UAT or production release stops before deploying on an open HIGH/CRITICAL finding unless it has a .trivyignore.yaml exception with a statement and an unexpired expired_at. Findings are fixed as ordinary work, by version overrides when the Spring Boot BOM lags.
AD #38 — Why (as written): an enforcing PR gate stops every merge, and so every dev deploy, the day an advisory is published against a dependency the PR never touched, and dev has to deploy as soon as the AWS work allows. What Empire receives still meets the proposal’s control.
The AD #9 and AD #27 rows as they stood before this refinement:
| 9 | Dependency-vulnerability CI gate: CVSS ≥ 7.0 is the build-failing threshold (report-only until the clean-baseline flip — AD #27); per-repo suppressions need a justification and an expiry; one tool across the Java and Node ecosystems — the tool is Trivy (AD #27) | One uniform gate for both ecosystems | 2026-07-13 |
| 27 | The dependency-vulnerability gate is Trivy in all three app repos: one
trivy fsSlow-lane step per repo over the committed lockfiles with--include-dev-deps(Vite puts nearly everything in devDependencies), gating on--severity HIGH,CRITICAL(≡ CVSS ≥ 7.0); report-only until the baseline is clean in all three repos, then enforcing (FS-4 spec Rev 3); per-repo.trivyignore.yamlentries carry id,purls,statementand a tool-enforcedexpired_at; Dependabot stays the alert layer. Refines AD #9’s tool | OWASP Dependency-Check cannot scan pnpm and Trivy was the only free tool meeting every AD #9 property on both ecosystems; accepted while report-only: GHSA advisories can lag NVD by days to weeks, to revisit when the gate enforces | 2026-08-31 |
AD #38 and AD #9 — where Trivy runs, corrected 2026-10-02
A factual correction, approved by the lead, with no rule changed. When the AD #38 row was written (and the AD #9 row updated with it, commit 30ff5ad4), AD #38 came to say Trivy runs on “every merge to main”, and AD #9 that it reports on “every PR, merge and dev deploy”. No app-repo workflow runs on a push to main. The scan runs in each repo’s Fast lane on a ready pull request (in the backend, one that changes more than documentation), on a push to release/* and on a manual run, and the backend’s Fast lane also runs it on the weekday nightly run on main; the frontends’ workflows have no nightly run. deploy-dev, when F38-d builds it, adds trivy image on every image it builds. AD #38’s row now lists where the scan runs, and AD #9’s says it reports wherever it runs. AD #38’s text as written (above) says only that the scan does not fail a merge, not that a merge runs it, so it needs no change.
AD #14 — exception for costs, 2026-10-05
How it was reached. The second project audit (2026-10-05) found that F26-b FR-W4 deletes cost rows — a new cost from date D deletes every cost row starting on or after D, so that a cost entered by mistake today can be corrected — while AD #14 said prices and costs are never updated in place. The lead chose to record the exception rather than change F26-b.
AD #14 — Exception (as written): a cost row that starts today or later has applied to no earlier day, so a new cost from that date deletes it (F26-b FR-W4, each delete audited); a row that started earlier only has its end date set.
Why: a row that starts today or later is in no as-of read for a day before today, so deleting it changes no earlier day’s history; a row that started earlier is never changed except for its end date. Lead sign-off: Tharinda, 2026-10-05.
The AD #14 row as it stood before:
| 14 | Bulk prices and costs are effective-dated rows, never updated in place | Price history + as-of quoting are PRD requirements (OQ-33/38/42); temporality cannot be retrofitted without rewriting every read path | 2026-08-06 |
AD #39 — 2026-10-09
How it was reached. Until 2026-10-09 the CRM built every UI primitive in-house: CSS Modules on the --et-* tokens, native elements first, and react-aria-components for behaviour in two components only (Combobox, Tooltip) — the stack .forge/guides/tech-stack-reference.md explained and forge-et-fe/CLAUDE.md enforced (“No Tailwind”, “the component library is capped at two components”). A UI/UX discussion with the UI engineer about the built screens found recurring problems that each screen had fixed on its own, and proposed splitting each screen into a title bar, a data bar and a body. The problems included controls of different heights side by side, labels and buttons out of line, popups painted under sticky table cells, inconsistent paddings and states. A trial on the Users screen (local branch feature/ui-staging-users, 2026-10-08/09) rebuilt the list and the editor on shadcn/ui — Radix UI behind shadcn’s components, Tailwind v4 without its global reset, every Tailwind name mapped onto the --et-* tokens, the revamped colour layer from the design-system artifact — and split the screen into a title bar, a data bar and a body. Most of the fixes asked for during the trial (control heights, alignment, popup layering, a numbered pager, a table that scrolls inside its card) were settings of the shadcn components rather than new code. Nanndish reported on 2026-10-09 that the lead had approved adopting shadcn/ui for the project, and set how it is applied: existing screens are moved over one at a time (a backfill), work in flight is decided per PR by the reviewer, and every future frontend change uses shadcn.
AD #39 — Decision (as written): The CRM’s UI is built from shadcn/ui. New and changed screens in forge-et-fe use the shadcn components in src/ui/shadcn, adapted to the CRM’s rules: disabled renders as aria-disabled, base.css’s global focus ring is the focus indicator, icons come from the registry, a control inside a Field takes the field’s wiring, and every screen meets WCAG 2.1 AA at the supported sizes. Styling is Tailwind v4 utility classes on the tokens (no preflight; scanning limited to the shadcn folder and the features moved over) or a feature’s CSS Module. It replaces “CSS Modules only, no Tailwind” and the two-component cap on react-aria-components; no new use of react-aria-components is added, and its two components leave as their screens are moved over. Screens built before the decision are moved over one at a time and listed in .forge/design/ui/shadcn-backfill.md until they are. When a frontend PR adds a component that is not from shadcn, frontend-reviewer decides for that PR whether the author converts it before merge or lists the screen for the backfill. The revamped colour layer (theme-revamp.css, opted into per route) goes with it. The decision covers forge-et-fe; whether forge-et-pwa follows is open.
AD #39 — Why (as written): a library the whole team composes from removes the class of problems the in-house primitives produced, where each screen had to get spacing, sizing, alignment and layering right by itself. shadcn’s components are copied into the repo rather than imported, so they can be adapted to the CRM’s accessibility rules and tokens, and Radix UI supplies the tested behaviour (focus, keyboard, ARIA) that the in-house components had to build. Accepted trade-offs: the frontend now has two styling systems side by side until the backfill finishes; Tailwind’s class strings are long and a class built from pieces at runtime is not generated; the shadcn CLI needs checking after every run (it has twice added an unrelated npm package named cn); new dependencies were added (radix-ui, class-variance-authority, clsx, tailwind-merge, sonner, cmdk, and tailwindcss, @tailwindcss/vite, tw-animate-css as dev dependencies); the backfill is work not in the tracker’s features, done as untracked chore PRs by the lead’s direction. Consequences: forge-et-fe/CLAUDE.md rewritten in the first PR, forge-et-fe#201, which also moves the Users screens over; frontend-implementer, frontend-reviewer, the plan template’s UI section, the tech-stack guide and design-system Rev 41 updated; the backfill list created. Lead sign-off: Tharinda — approval reported by Nanndish on 2026-10-09; the date of the lead’s own approval is not recorded.
AD #39 — refinement, 2026-10-12: a test enforces it. The row as first written left each non-shadcn component to frontend-reviewer’s judgement on each PR. Nanndish asked for a check that stops any UI that is not from shadcn from merging, covering the screens already built, the PRs and local branches in flight and all later work. forge-et-fe’s src/app/shadcnOnly.test.ts fails a file in src/features or src/app that uses an older src/ui component with a shadcn counterpart, react-aria-components, or a raw <button>, <input>, <select>, <textarea>, <table> or <dialog>, unless src/app/shadcnBackfill.json lists that file and name. The list was generated from the tree on 2026-10-12 and only shrinks. The reviewer’s per-PR choice stays, as the decision to add an entry. It runs inside pnpm test, so pnpm test:record and the required Test record check enforce it, and no workflow changed. Design: .forge/design/harness/shadcn-only-check.md. One fact in the text above has since changed: forge-et-fe#201 removed sonner and cmdk again, because nothing used them yet; they come back with the first screen that does. Lead sign-off: Tharinda — reported by Nanndish on 2026-10-12.
The AD #39 row as it stood before: “… each is listed in .forge/design/ui/shadcn-backfill.md until it is; when a frontend PR adds a non-shadcn component, frontend-reviewer decides per PR whether it is converted first or listed. …”
AD #40 — 2026-10-28
How it was reached. AD #34 (2026-09-24) seeded the first administrator from a per-environment Flyway placeholder whose production value came “from Secrets Manager, never in git”, and F38-i’s approved spec (2026-10-27) planned a production administrator-email secret in base/secrets (its FR-4, FR-9, register step 28). Dev already carried its value, the crm01@empire.lk test mailbox, as a plain value in forge-et-be .aws/td.dev.json, while reading the Entra tenant ID, client ID and certificate — none of them secret — as Secrets Manager references (the .forge/owed.md row “Decide whether the Entra tenant and client IDs stay in Secrets Manager”, open since 2026-10-19). When F38-i’s spec was revised on 2026-10-28, the lead decided one way for every environment.
AD #40 — Decision (as written): A non-secret setting is a plain task-definition value in every environment, never a Secrets Manager secret. The seeded administrator’s email is a plain value in each environment’s task definition, production’s included, so production’s address is in git (forge-et-be .aws/td.prod.json) once Empire confirms it. The Entra tenant ID, client ID and certificate (the public half of the key pair) are plain values too, in dev, UAT and production. Only a value that must stay secret — the Entra private key, the Exa key, the RDS-managed database password — is a Secrets Manager secret. AD #34’s “never a real person’s email outside production” stands: dev and UAT keep the test mailbox.
AD #40 — Why (as written): one way in every environment; a value that is not sensitive does not justify a secret at about USD 0.40 a month per value per environment (USD 1.60 a month in production, which would have had all four; USD 1.20 in dev and UAT, whose administrator email was already a plain value); and a plain value can be read in the task definition, which a secret reference cannot. Accepted: a person’s work email address sits in a private repository once Empire confirms it.
The AD #34 row as it stood before: “… whose email is a per-environment Flyway placeholder — the crm01@empire.lk test mailbox outside production, the address Empire confirms in production (from Secrets Manager, never in git). …”
AD #41 — 2026-10-30
How it was reached. AD #34’s refinement of 2026-10-26 folded access.manage into settings.manage, so one key opened every Settings page, and .forge/owed.md held “Per-page permissions on the Settings page, only if Empire asks” for Tharinda. On 2026-10-30 Nanndish published design options for the role editor (three layouts) and chose the one that lists the pages under one Settings row; Tharinda agreed to per-page keys, and Nanndish asked for it to be built without a spec or plan.
AD #41 — Decision (as written): each Settings page has its own permission key, replacing settings.manage: settings.users.manage, settings.roles.manage, settings.account_tags.manage, settings.contact_tags.manage, settings.lead_tags.manage and settings.email_templates.manage, and a later page adds its own key, fail-closed. Administration is the Users and Roles keys together: the last-admin invariant keeps at least one active user holding both, and the loggers endpoint and the Pipedrive migration runs need both. The role and catalog reads also answer the Users key. The role editor shows one Settings row, a box that chooses every page, with the pages under it. Holding Users or Roles still lets the holder reach every page; the editor warns, and the audit trail is the control (AD #34). The migration forge-et-be V58__settings_page_keys.sql gives every role that held settings.manage all six keys and removes settings.manage, with audit rows labelled settings-pages-migration.
AD #41 — Why (as written): a role can be given some Settings pages and not others — the tags or the email templates without users and roles — which one key could not express. Accepted: a Users or Roles holder can still give themselves every page.
Accepted at review, 2026-11-02 (Nanndish, forge-et-be#342): the release before V58 cannot run against a database V58 has migrated. During the deploy that applies it, the old tasks answer 403 on every Settings page until they are replaced, and rolling the image back afterwards needs the grants put back by hand first (forge-et-be docs/auth/README.md § Rolling back past V58__settings_page_keys.sql), because the old catalog’s orphan-grant check refuses the six keys. One release was kept rather than two (declare the keys first, migrate in the next), as V54 did, because production had not gone live.
The AD #34 row as it stood before: “… all user, role and hierarchy administration and all configuration is one settings.manage, which opens every page of the CRM’s Settings page (refined 2026-10-26: it absorbed the separate access.manage), and email.manage is the holder’s own mailbox only. No category axis. At least one active user always holds settings.manage: a deactivation, role change, role edit or role delete that would leave none is refused. …”
The AD #37 row as it stood before: “… Setting a user’s manager is therefore an access decision (under settings.manage since AD #34’s refinement of 2026-10-26, audited — AD #36). Unchanged: mailboxes are outside every reach (email.manage is the holder’s own mailbox only); keys without an owner-bearing entity (settings.manage, buying_standard.*, price.publish, quote.approve_sub_floor) have no reach; …”
AD #42 — 2026-11-12
How it was reached. On 2026-11-12 the capture-app prototype (.forge/design/prototypes/pwa-current/) gained in-app notifications: a badge on the Leads tab, a Ready to review notice on any tab, and a notifications bell that keeps each finished lead and each lead a teammate converted or rejected. Reviewing the redesign the same day, Nanndish proposed that the capture app send no email, since the in-app notifications were enough; the prototype was built that way and the question was put to the lead in .forge/owed.md (the “Fold the capture-app decisions of 2026-11-12” row, item 7). Tharinda confirmed it the same day (reported by Nanndish).
AD #42 — Decision (as written): the capture app sends no email; its notifications are in-app only. A rep learns that a captured lead is ready, or that a teammate converted or rejected one, from the app’s notifications bell and its on-screen notice while the app is open, and finds them in the bell when it is next opened. No email goes to the rep or to a team address, and there are no push notifications in V1. F36-c builds no notification email. SES stays for the backend’s system mail (AD-O-3).
AD #42 — Why (as written): reps work the show from the app, where the bell and the notice already tell them when a lead is ready and what teammates decided, so an email repeats it; dropping it removes F36-c’s sender, its open recipients question and its template. Accepted: a rep with the app closed learns nothing until they open it.
The AD #20 row as it stood before: “… in its own repository (forge-et-pwa) at its own URL, with lead notifications by email only (SES); it is delivered in Phase 1 (F36-a to F36-d), scope unchanged …”
AD #43 — 2026-11-20
How it was reached. AD #39 (2026-10-09) left the capture app undecided, and .forge/owed.md gave the decision to the lead. With F36-a to F36-d done, Nanndish proposed on 2026-11-20 that the capture app move to shadcn/ui as the CRM had, so the two apps are consistent; Tharinda agreed (reported by Nanndish). Nanndish approved the new runtime packages the same day. The plan, with the screen order and the capture app’s own sizes, is .forge/design/ui/pwa-shadcn.md.
AD #43 — Decision (as written): the capture app’s UI is built from shadcn/ui too, applying AD #39 to forge-et-pwa. New and changed screens use the shadcn components in forge-et-pwa’s src/ui/shadcn, copied from forge-et-fe’s with their tests (not byte-shared) and adapted to the capture app: every control at least 44 × 44px, the 14px working size, bottom sheets as shadcn’s Sheet, the phone’s own date picker. Tailwind v4 without its reset, every colour name mapped onto the --et-* names the capture app’s theme-crm.css declares and the rest onto the --et-* tokens. Its runtime packages grow by radix-ui, class-variance-authority, clsx and tailwind-merge. Screens built before it are moved over one PR each, in the order pwa-shadcn.md gives. The same test enforces it: forge-et-pwa’s src/app/shadcnOnly.test.ts, with its own list of older components and its own src/app/shadcnBackfill.json, which only shrinks; adding an entry is frontend-reviewer’s decision for that PR. It replaces forge-et-pwa’s rule of CSS Modules only, with no Tailwind and no component library; a screen’s layout stays in its CSS Module.
AD #43 — Why (as written): the CRM and the capture app are one product to Empire’s staff, and AD #39’s reason holds here too: the capture app’s own components draw spacing, sizes and states each screen differently, while one library keeps both apps consistent and lets a fix in one be copied to the other. Accepted: four more runtime packages on the phone (about 33 kB more in the entry chunk, mostly tailwind-merge) and a period with two component sets in the capture app while the screens move.
The AD #39 row’s last sentence as it stood before: “Covers forge-et-fe only; forge-et-pwa is undecided (.forge/owed.md)”.
AD #14 — exception for price withdrawal, 2026-10-11
How it was reached. F26-f (Tea Room review, edit and publish) withdraws a published price that has applied to no earlier day (spec FR-1, FR-10, D-2): F26-a Q-7 required a withdrawal design before a publish path shipped, a published row cannot be deleted or returned to draft, and a price starting today or later cannot be closed because an empty validity is refused. The backend-reviewer found on the F26-f wave PR (forge-et-be#234, 2026-10-10) that AD #14 named no exception for it, so the PR carried a block record until the lead decided. The lead accepted the exception on 2026-10-11 (relayed by Dinil).
AD #14 — Exception (as written): a published price that starts today or later can be withdrawn — its row’s publication_status becomes withdrawn with who, when and why (F26-f FR-1, FR-10, each withdrawal audited); its figures and validity never change, the row is never deleted, and no earlier price is reopened.
Why: like the cost exception, a price that starts today or later is in no as-of read for a day before today, so withdrawing it changes no earlier day’s history; and unlike a delete, the row and its figures stay, so the withdrawal itself is part of the record. Lead sign-off: Tharinda, 2026-10-11.
The AD #14 row as it stood before: the 2026-10-05 row above, with the cost exception only.
AD #24 — a manual dev deploy of another branch, 2026-10-18
How it was reached. On 2026-10-18 the lead dropped the branch rule on the dev GitHub Environments of forge-et-be and forge-et-fe, because the deploy workflows already run only from main on a push and the team may need to deploy another branch to dev by hand; forge-et-be’s deploy workflow gains a manual trigger instead (F38 spec Rev 18). F38-d’s spec review found that the AD #24 row still read “dev deploys main”, which a reviewer of the workflow PRs would hold against a manual run on a branch.
AD #24 — Refinement (as written): dev deploys main on every merge, and a manual run may deploy another branch to dev (F38 Rev 18); UAT and production deploy tags only.
Why: dev holds test data only, and a manual run is a deliberate act by a team member; uat and production keep their branch and tag rules (F38-h, F38-i). Lead sign-off: Tharinda, 2026-10-18 — the decision in F38 Rev 18, and the row’s wording confirmed at F38-d’s spec approval the same day.
The AD #24 row as it stood before: “… Releases are annotated tags vX.Y.Z; dev deploys main, UAT and production deploy tags. …”
AD #38 — no image scan in the dev deploy, 2026-10-20
How it was reached. forge-et-be#275 (F38-d wave 2, merged 2026-10-19) added a report-only trivy image step and a wait for a stable ECS service to the dev deploy. In the four push runs after its merge run (39235519408, 39366531250, 39374212302, 39377895770) the deploy job took 252–776 s, of which the wait was 170–693 s and the scan about 45 s. The lead asked whether the scan added any value when it never blocks. ECR scans every pushed image (forge-et-iaac base/ecr/repository.tf, scan_on_push = true), which covers the OS packages trivy fs cannot see, and nobody reads a green deploy log. The lead dropped both from the dev deploy (F38-d spec Rev 3, F38 Rev 22, forge-et-be#286) and kept both in deploy-uat and deploy-prod.
AD #38 — Refinement (as written): Trivy runs on every ready app-repo PR, release-branch push, manual run and nightly run (trivy fs), and in the UAT and production release workflows (trivy image and trivy fs), where it blocks. The dev deploy runs no Trivy scan; ECR’s scan on push checks each dev image.
Why: a report-only image scan in a dev deploy cost about a minute on every merge, blocked nothing and repeated ECR’s own scan; the release check, which keeps the proposal’s §A.4 control, is unchanged. Lead sign-off: Tharinda, 2026-10-20.
The AD #38 row’s sentence as it stood before: “Trivy runs on every ready app-repo PR that changes more than documentation, every push to release/*, every manual run and each app repo’s nightly run on main (trivy fs over the lockfiles), and on every image deploy-dev builds (trivy image), and reports HIGH/CRITICAL findings without failing the PR, the run or the dev deploy; …”
AD #32 — the account briefing moved to user-invoked AI, 2026-10-21
How it was reached. Review Pass 1 of the F13 spec (AI account briefing) found that a briefing a person asks for, gated on account.view, fitted neither half of AD #32: the row listed account briefings as AI the system runs on its own, and AI a user invokes is implied by the manage key it assists, while the PRD says a view-only role never triggers AI work. The Phase 1 acceptance criterion E6 has a person ask for a briefing. Three options were put to the lead: on request under account.view (a new rule on AD #32), on request under account.manage, or prepared in the background under account.view (AD #32 as written; a table, a job and more calls). Dinil chose the second, as inquiry extraction (lead.manage) and email drafts (email.manage) already work, and the lead signed it off (F13 spec decisions 2 and 3, Q-1).
AD #32 — Refinement (as written): the account briefing is AI a user invokes on a record: a person whose role holds account.manage and who reaches the account asks for it, and nothing is prepared in the background. The morning briefing stays AI the system runs on its own. The rule of AD #32 (3) is unchanged; only its examples move.
Why: a briefing is wanted before a particular call or meeting, so it is made when someone asks; a view-only role starting paid AI work would contradict the PRD; and the briefing then works like every other on-demand AI action. Lead sign-off: Tharinda, 2026-10-21.
The AD #32 row’s sentence as it stood before: “AI the system runs on its own (lead scoring and triage, inquiry extraction, account and morning briefings, duplicate/spam detection) shows under the record’s view, controlled by the per-feature {model, enabled} switch (AD #19); AI a user invokes on a record (an email draft, the quote or brief assistant) is implied by the manage permission it assists.”
AD #4 — the temporary uat instance named, 2026-10-23
How it was reached. F38’s OQ-A placed the temporary uat instance in the development account (decided by Dinil on 2026-10-05, confirmed by the lead on 2026-10-15). While F38-h’s spec was drafted, the lead decided that UAT reads dev’s Entra secrets, sends through dev’s SES identity, pulls dev’s backend image and uses dev’s Exa key instead of having its own (F38-h spec decisions 2–4 and 10; F38 Rev 24). The spec review (F38-h Q-5) found that AD #4’s “one AWS account per environment” did not name this case, and offered either a clause on the row or leaving the OQ-A record to stand; the lead chose the clause.
AD #4 — Refinement (as written): the temporary uat instance runs in the development account and reads dev’s Entra secrets, SES identity, backend image repository and Exa key (F38 OQ-A, F38-h). Development and production stay in accounts of their own.
Why: UAT holds test data only and uses the non-prod key, so keeping it out of the production account keeps production’s data and key its own, and reading dev’s long-lived resources means nothing is copied by hand for a round and a uat destroy removes nothing another environment needs. Lead sign-off: Tharinda, 2026-10-23.
The AD #4 row as it stood before: “Hosting: AWS (ECS Fargate, RDS, SQS, S3, Secrets Manager), one AWS account per environment; Fargate carries the backend only, both frontends are static S3 + CloudFront (AD #22) | Broadest managed-service catalog; team’s enterprise-stack familiarity | 2026-07-13”
AD #34 — access.manage folded into settings.manage, 2026-10-26
How it was reached. Design-system Rev 70 (the internal demo of 2026-10-21) moved Users, Roles and the email templates onto the CRM’s Settings page, each card shown to a holder of its own key: settings.manage for the tags, email.manage for the templates, access.manage for Users and Roles. Trying it, Nanndish found that unticking a role’s Emails permission hid the Email templates card while the role still held Manage settings, and decided on 2026-10-26 that the Settings permission alone decides the whole Settings page: a role holding it sees every card, Users and Roles included, and a role without it sees no Settings at all. Because the backend gates Users and Roles on access.manage, and the seeded IT Admin holds only that key, showing those cards on settings.manage alone would have refused every request behind them, and requiring settings.manage for the page would have locked the IT Admin out. Nanndish chose to fold access.manage into settings.manage rather than keep two keys. He also recorded a later option, one permission per Settings page, to build only if Empire asks for it (.forge/owed.md).
AD #34 — Refinement (as written): all user, role and hierarchy administration and all configuration is one settings.manage, which opens every page of the CRM’s Settings page; access.manage is removed from the catalog. A migration (forge-et-be V54) gives settings.manage to every role that held access.manage, the seeded IT Admin included, and removes the access.manage grants, each change audited. The last-admin rule holds on settings.manage. email.manage stays the holder’s own mailbox only and no longer opens anything on the Settings page; a holder of settings.manage without it writes shared email templates only.
Why: Users and Roles became pages of Settings, and a Settings permission that showed only some of its pages, depending on other keys, did not match how an administrator reads the role editor. One key per Settings page is possible but more than anyone has asked for. Lead sign-off: Tharinda, 2026-10-27 (approval reported by Nanndish) — Nanndish’s decision of 2026-10-26.
The AD #34 row’s sentences as they stood before: “… an editable IT Admin role holding access.manage and one active user with it … all user, role and hierarchy administration is one access.manage, configuration is settings.manage, and email.manage is the holder’s own mailbox only. No category axis. At least one active user always holds access.manage: …”; AD #32 (2) “last-admin protection stands (on access.manage, AD #34)”; AD #37 “(under access.manage, audited — AD #36) … keys without an owner-bearing entity (access.manage, settings.manage, …)”.
AD #36 — changes to a user’s own Outlook mailbox state, 2026-10-28
How it was reached. F20-i’s live inbox marks a message read in Outlook when it is opened, offers Mark as unread, and creates one Outlook search folder per mailbox for its All mail view. None of these changes anything the CRM stores. The spec review of 2026-10-28 found that AD #36’s row says “every write”, with no boundary for writes to the user’s own mailbox, while the only precedent, F20-c, audits a send. The lead was asked whether to audit the three changes or to refine the AD.
AD #36 — Refinement (as written): changes to a user’s own mailbox state in Outlook, other than a send, are not audited — marking a message read or unread, and creating or updating the CRM’s All-mail search folder. A send stays audited (F20-c).
Why: they change only the user’s own mailbox, never a CRM record, and opening a message is a read in all but name; an audit row for every message opened would bury the trail that makes unlimited self-escalation acceptable. Lead sign-off: Tharinda, 2026-10-28 (in session, at F20-i’s spec review).
The AD #36 row’s sentence as it stood before: “… sharing and reassignment, and exports; never reads. Kept indefinitely in V1 …”.
AD #38 — where the nightly scan runs, restated 2026-11-03
How it was reached. On 2026-11-03 the lead decided that a test suite runs in one place (.forge/design/harness/test-run-cost.md N-5): CI’s scheduled PR validation run became weekly, kept to refresh main’s caches, and the nightly full run on the lead’s Mac (N-3) scans every repo with Trivy every night. The fresh-context review of that change found that AD #38’s “each app repo’s nightly run on main” had meant CI’s scheduled run, which no longer runs nightly.
AD #38 — Restatement (as written): Trivy runs on every ready app-repo PR that changes more than documentation, every push to release/*, every manual run, each app repo’s weekly scheduled CI run on main, and the nightly full run on the lead’s Mac (trivy fs over the lockfiles). No rule changes: the scan still reports only, and blocks only a UAT or production release.
Why: the row must name the places the scan runs now. Lead sign-off: Tharinda, 2026-11-03 (in session).
The AD #38 row’s sentence as it stood before: “Trivy runs on every ready app-repo PR that changes more than documentation, every push to release/*, every manual run and each app repo’s nightly run on main (trivy fs over the lockfiles), …”.
AD #20 — the capture app moved to Phase 1, 2026-11-11
How it was reached. At the progress meeting of 10 November 2026, Empire asked for the capture app sooner: Sahampathy Dissanayake said trade fairs are Empire’s main source of customer contacts and the app must be usable from January 2027, and Kavindu Anthony asked for it in Phase 1 (.forge/discovery/meeting-notes/2026-11-10-kavindu-crm-progress-update-demo.md §4). Rukshan Salgado, Thilina Abeyrathna and Malinda Wellalage (Altrium) also asked for it to be done in Phase 1. The delivery team and Empire agreed that F36-a to F36-d are delivered in Phase 1, and the tracker recorded it on 2026-11-11 (PRD Rev 91).
AD #20 — Restatement (as written): the capture app is delivered in Phase 1 (F36-a to F36-d), scope unchanged — Gate 3 had placed it in Phase 2, and it moved on 2026-11-11, as agreed with Empire at the 10 November progress meeting. No rule changes: full scope, its own repository and URL, and email-only notifications stand.
Why: the row must say which phase delivers the app now. Lead sign-off: Tharinda, 2026-11-11 (the move); the row’s wording recorded 2026-11-12.
The AD #20 row’s sentence as it stood before: “… with lead notifications by email only (SES); Gate 3 placed it in Phase 2, scope unchanged”.
AD #25 — the Boot line moved to 4.2, 2026-11-20
How it was reached. AD #25 made the Boot pin a moving one and expected a minor about once a year. Spring Boot 4.2.0 reached Maven Central and the Gradle Plugin Portal on 19 November 2026. Spring’s published support dates give 4.2 open-source support to 31 Dec 2027, against 31 Jul 2027 for 4.1, so 4.2 now has the longest support of the 4.x lines. The lead asked for the upgrade once 4.2.0 was released. forge-et-be moved to it with one code change (Framework 7.1 deprecates RestClient.Builder.defaultStatusHandler(ResponseErrorHandler) for removal). Boot 4.2’s BOM manages Groovy 5.1, and Spock 2.5-groovy-5.0 accepts every Groovy 5, so the Spock pin stays.
AD #25 — Restatement (as written): Spring Boot runs on the 4.2 line (4.2.x), a moving pin (expect a Boot minor about once a year), with Spock 2.5-groovy-5.0 and a jcl-over-slf4j bridge. No rule changes: the pin still moves about once a year, and the Spock suffix and the bridge stand.
Why: 4.2’s open-source support runs to 31 Dec 2027, five months past 4.1’s 31 Jul 2027, and the move is a version bump with one deprecation fixed. Lead sign-off: Tharinda, 2026-11-20 (in session).
The AD #25 row’s sentence as it stood before: “Spring Boot runs on the 4.1 line (4.1.x), a moving pin (expect a Boot minor about once a year), with Spock 2.5-groovy-5.0 and a jcl-over-slf4j bridge”.
The whole table as it stood on 2026-09-23, before each row was reduced to the rule in force
On 2026-09-23 every row of CLAUDE.md § Architecture Decisions was rewritten to state only the rule in force now, with a one-line reason and a pointer to any refining decision. The table below is the full text of every row immediately before that change, copied verbatim, so the wording each decision was signed off with is kept. The note at the top of this section (“the decision text is unchanged”) held until 2026-09-23; from then the CLAUDE.md rows state the rule in force, and this table is where the earlier text lives. The “as written” entries for AD #29–#32 above remain the original sign-off text.
| # | Decision | Why | Date |
|---|---|---|---|
| 1 | Backend: Java 21 + Spring Boot | Team’s existing enterprise-backend stack | 2026-07-13 |
| 2 | Frontend: TypeScript + React. Framework refined by AD #21 — React SPA on Vite; Next.js dropped | Client prototype’s own runtime is React-based; strongest ecosystem for Kanban/calendar widgets | 2026-07-13 |
| 3 | Database: PostgreSQL (AWS RDS), single-tenant relational schema | PRD-preferred; structured domain model; mature Flyway/JPA tooling | 2026-07-13 |
| 4 | Hosting: AWS (ECS Fargate, RDS, SQS, S3, Secrets Manager), one AWS account per environment. Refined by AD #22 — Fargate carries the backend only; both frontends are static S3 + CloudFront | Broadest managed-service catalog; team’s enterprise-stack familiarity | 2026-07-13 |
| 5 | Auth: dual-path login (OAuth2 Google/Microsoft + local email/password) onto one User entity; server-side sessions (Spring Session JDBC), not JWT. Login paths refined by AD #28 — Microsoft only; Google + local email/password dropped. The session model stands unchanged |
Reps already need mailbox OAuth for F20–F22; local fallback covers users without a Google/Microsoft account — superseded: OQ-24 established Empire is all-M365, so the fallback protected nobody real (AD #28) | 2026-07-13 |
| 6 | AI integration isolated behind an AIProvider interface; Claude called from the backend (no separate AI service) per PRD mandate. Transport refined by AD #19 — Bedrock in-account, not the direct API; the seam and backend-call shape stand |
Isolates the OQ-15/R-PRD-002 self-hosted-model fork so a “no” swaps an implementation, not a rewrite | 2026-07-13 |
| 7 | Background jobs via AWS SQS + Spring Boot async workers in the same codebase — no separate microservice/orchestrator | Team scale (10–20 users) doesn’t justify microservice/K8s complexity; in-house-first | 2026-07-13 |
| 8 | Admin custom fields (F34) stored as a JSONB column per entity, not dynamic ALTER TABLE/EAV tables |
Keeps core schema stable and query-performant while allowing schema-less extension | 2026-07-13 |
| 9 | Dependency-vulnerability CI gate: OWASP Dependency-Check, CVSS ≥ 7.0 fails build, per-repo suppression file requires justification + expiry. Tool refined by AD #27 — Trivy; the intent (uniform gate, threshold, governed suppressions) stands | One tool works uniformly across the Java and Node ecosystems | 2026-07-13 |
| 10 | CRM→ERP handoff (F19) ships V1 as a manual document behind an ErpHandoffService seam; no live integration until OQ-2 resolves |
R-PRD-001 accepted risk; keeps the seam ready without blocking on an unconfirmed ERP API | 2026-07-13 |
| 11 | Every Stage carries a stable, non-editable stage_type separate from its admin-editable display name |
Prevents admin pipeline edits (F24) from silently breaking AI/automation logic keyed on stage semantics (R-14) | 2026-07-13 |
| 12 | All timed work runs via EventBridge Scheduler → SQS → worker; never in-process @Scheduled. One recorded carve-out (FS-6 spec Q-1, approved 2026-09-03): Spring Session JDBC’s built-in expired-session cleanup stays in-process — an idempotent DELETE whose duplicate firing across tasks is redundant work, not a duplicate outward effect; FS-9 may move it onto the scheduler |
With more than one ECS task, @Scheduled fires on every task — duplicate alerts and duplicate buyer-facing email |
2026-08-06 |
| 13 | Every queued job carries an idempotency key; consumers are replay-safe | SQS standard queues deliver at-least-once; an outreach step sent to a buyer twice is unacceptable | 2026-08-06 |
| 14 | Bulk prices and costs are effective-dated rows, never updated in place | Price history + as-of quoting are PRD requirements (OQ-33/38/42); temporality cannot be retrofitted without rewriting every read path | 2026-08-06 |
| 15 | Authorization resolves as (role, resource, permission-level), not a flat authority check. Refined by AD #30 — the grant tuple becomes (role, permission_key, scope): the four levels survive as catalog metadata on each permission key rather than as a grant column, and scope gains a team value on a reporting hierarchy. “Not a flat authority check” stands unchanged. Further refined by AD #32 (2026-09-11) — the category axis is read / edit / execute, AI is not a grantable level, no templates, one role per user |
OQ-47 requires read-only / edit / AI-use / execute levels layered across six roles — refined: Empire asked (2026-09-07) for a fully configurable role-management system, so the six roles become default templates and the level axis becomes a property of each permission, not of the grant (AD #30) | 2026-08-06 |
| 16 | Microsoft Graph is the only mailbox integration in V1, behind a MailboxProvider seam; Gmail/Exchange/IMAP are out of scope and additive only via change request |
The issued proposal quoted Microsoft 365 via Graph exclusively; OQ-24 confirmed it is all Empire uses. The seam keeps a later provider cheap without paying for one now | 2026-08-06 |
| 17 | Core/domain separation adopted in full: crm-core/domain-tea modules with a build-enforced one-way dependency, typed 1:1 extension tables (never F34 JSONB), all ten extension points, separate core.*/tea.* schemas with a partitioned Flyway version space, four-layer enforcement. Acceptance test: deleting domain-tea leaves a clean, working generic CRM. Superseded by AD #29 — the split is no longer extended: FS-12/FS-13 cancelled, the acceptance test retired as a goal; the modules, schemas and guards already built stay in place and green — and collapsed outright by AD #31 (2026-09-09): FS-14 removes the modules, the schemas and the guards |
P-09 requires first-class typed fields; a partial split leaves tea columns in generic tables, which is not separation. Costs ~+8–15% of V1, accepted as a deliberate investment (see architecture.md § Core / Domain Separation) — superseded: the investment’s return rested on OQ-50’s assumed reuse of the generic layer, which is no longer expected (AD #29). Correct on August’s information; the cost paid is real and is not revisited |
2026-08-06 |
| 18 | Backend build tool: Gradle (Groovy DSL — build.gradle), not Maven |
Team decision; matches every existing Altrium backend’s convention. The core/domain split used Gradle convention plugins; FS-14 collapsed it to a single build.gradle (AD #31) — ./gradlew commands are identical either way |
2026-08-18 |
| 19 | AI runs on Claude via Amazon Bedrock exclusively — Haiku 4.5 (high-volume) / Sonnet 5 (synthesis) served inside the project’s AWS account (us-east-1 — Bedrock’s home region, all pinned models native); no direct-API tier and no second-provider fallback (outages degrade to the manual path); per-feature {model, enabled} runtime config |
One vendor relationship and one bill — AI usage lands on the AWS invoice, so the client holds no separate AI accounts; in-account processing is the strongest data-governance answer; Bedrock’s new-model lag is acceptable because models are pinned; the proposal’s A.3.1 comparison runs on anonymised inquiries via evaluation keys (see ai-provider-strategy.md) |
2026-08-18 |
| 20 | Trade-show capture app ships at full scope inside V1 (Option C) as a parallel work-stream, weeks 8–13 — in its own repository (forge-et-pwa) with its own hosting/URL; lead notifications email-only via SES |
Matches accepted proposal §4; viable because a working prototype exists (~2.5–3.5 wks remaining build). Descope lever back to capture-and-feed retained at the mid-November checkpoint | 2026-08-18 |
| 21 | Both frontends are React SPAs built with Vite — no Next.js, no SSR anywhere | Internal, authenticated apps with zero SEO need; an SPA is simpler to build, test (Vitest pairs natively), and host; matches the team’s existing frontend convention. The prototype is plain React, so nothing is lost in translation | 2026-08-18 |
| 22 | Frontend hosting: static S3 + CloudFront for both apps (each at its own URL, ACM TLS); the backend is the only Fargate service, behind the ALB. FE build-time config via GitHub Actions variables/secrets (non-sensitive values only — the bundle is public); backend secrets via task-definition secrets references → Secrets Manager, AWS access via the task IAM role (no static keys) |
An SPA needs no server, so a frontend container buys nothing; S3+CloudFront is cheaper than the costed Fargate frontend and CI is a build → S3 sync → CloudFront invalidation. Secrets never sit in git, images, task definitions, or the bundle | 2026-08-18 |
| 23 | All AWS infrastructure is Terraform-managed — environment-parameterized modules instantiated per account (dev, prod, and a temporary uat instance applied for each acceptance window and destroyed after it); state in S3 with DynamoDB locking, per account; lives in forge-et-be/terraform/ (team convention) |
The per-phase temporary-UAT commitment is only cheap if an environment is one terraform apply away — dev can’t host UAT (Phase 2 builds there during the round) and production would need a test-data purge before go-live; IaC also guarantees dev and prod stay the same shape |
2026-08-19 |
| 24 | Trunk-based branching: main is the trunk; a release/vX.Y.Z maintenance branch exists only for a release that is live in production, cut from its tag, protected, never deleted. Releases are annotated tags vX.Y.Z; dev deploys main, UAT and production deploy tags. Branch, commit and PR names carry the ticket id (feat(F2): …, feature/F2-…) |
A delivery phase can go to production before V1 signs off, so a hotfix path that excludes in-flight next-phase work is required — but only from the moment something is live. Tags give immutable handover artifacts without a long-lived branch per phase, and keep main the single integration point, so the wave orchestration (WAVE_BASE = main) is unaffected |
2026-08-19 |
| 25 | Spring Boot runs on the 4.1 line (4.1.x), not 3.5 — and the pin is understood as a moving one: Boot minors carry ~13 months of OSS support each, so expect to take a minor roughly annually rather than to settle. Entails Spock 2.4-groovy-5.0 (Boot 4.1 manages Groovy 5) and a jcl-over-slf4j bridge (Spring Framework 7 removed spring-jcl) |
Boot 3.5 left open-source support on 30 Jun 2026 and 3.5.16 is its last free release, so a CVE on 3.5 has no free fix and commercial support is not held. 4.0 was rejected as a target because its OSS support ends 31 Dec 2026, before V1 signs off; 4.1 runs to 31 Jul 2027. Taken while the backend was still a shell — Boot 4’s expensive changes (Jakarta EE 11, Jackson 3, Spring Security 7, starter renames) all fall on code not yet written, so the migration was ~40 lines instead of a project. Java 21 is unaffected (Boot 4.1 needs ≥17) | 2026-08-21 |
| 26 | An authorization check names the permission it needs, never the role that happens to carry it. F7’s sub-floor gate asks user.can(APPROVE_SUB_FLOOR_QUOTE), never user.role == ADMIN. Roles are granted sets of named permissions; who holds a permission is configuration, not code. Refines AD #15 |
Empire may operationally give the Managing Director the Administrator role — that is their call and is fine. What is not fine is F7 learning it that way: role == ADMIN silently converts every future Administrator into a below-floor-pricing approver, and nothing at the point of granting admin says so. An audit log does not catch it, because it records a legitimate approval by a legitimate admin. Naming the permission costs nothing in FS-6 (it is one more entry in the (role, resource, level) model), makes the grant visible and questionable in the role’s permission set, and makes splitting the two later a config change instead of a code change |
2026-08-21 |
| 27 | The dependency-vulnerability gate runs on Trivy in all three app repos — one trivy fs Slow-lane step per repo reading the committed lockfiles (--include-dev-deps, mandatory: Vite puts nearly everything in devDependencies and build tooling is supply chain), gate --severity HIGH,CRITICAL ≡ CVSS ≥ 7.0, phased exit code (report-only now, flips to enforcing once the dependency baseline is clean across all three repos — spec Rev 3, refining Rev 1’s calendar trigger), governed per-repo .trivyignore.yaml (id + purls + statement + tool-enforced expired_at); Dependabot stays as the complementary alert layer. Refines AD #9’s named tool; its intent is unchanged |
OWASP Dependency-Check cannot scan pnpm (measured: 0 npm coordinates from node_modules, 1 from the lockfile parser), so AD #9’s one-uniform-tool intent was unsatisfiable with DC — and DC also needed an NVD API key + cached DB + a JRE on frontend runners, while its own Node wrapper added the only HIGH finding in either frontend. Trivy was the sole free candidate meeting every AD #9 property on both ecosystems (osv-scanner has no severity gating; Grype’s ignore has no expiry and its NVD/CPE mode false-positives; Snyk/Sonar SCA aren’t free for private repos). Accepted trade-off: reviewed-GHSA advisories lag NVD by days-to-weeks for fresh CVEs — tolerable while enforcement is phased, revisit if it ever isn’t |
2026-08-31 |
| 28 | Microsoft (Entra ID) OAuth2 is the sole login path — Google OAuth and local email/password are dropped from V1. Refines AD #5’s login half; its session model (server-side sessions via Spring Session JDBC, not JWT) stands unchanged. local/test profiles authenticate via a profile-scoped stub login, structurally unreachable in cloud profiles (the coding-standards §5 stub pattern), so laptops and CI need no Entra registration. Further providers are additive-only: a spring-security client registration + change request — the core.user_identity (provider, subject) shape is retained |
Team decision. Empire is an all-Microsoft-365 shop (OQ-24/AD #16), so every CRM user already holds an M365 account and AD #5’s “local fallback for users without a Google/Microsoft account” protected nobody real. Dropping the local path removes password storage, reset/lockout surface, and anti-enumeration obligations from the CRM entirely — Entra supplies credential security, MFA and conditional access. Accepted trade-offs: an Entra outage or misconfiguration blocks all login (no local break-glass), and every user (MD and Executive included) must hold an Empire M365 account; the Entra app registration becomes the one hard external dependency for any cloud login | 2026-09-04 |
| 29 | The core/domain separation is no longer extended — reverses AD #17 by stopping it, not collapsing it. FS-12 (extension-point substrate) and FS-13 (core workflow primitives), both not started, are cancelled; AD #17’s acceptance test (“deleting domain-tea leaves a working generic CRM”) is retired as a design goal; no further extension points, typed extension tables or layer deliberations are undertaken for reuse’s sake. Everything FS-1/FS-2 already built stays physically in place and stays green — the crm-core/domain-tea modules, the core.*/tea.* schemas with their partitioned Flyway version space, and the four enforcement mechanisms (build graph, ArchUnit boundary + vocabulary rules, dependency-cruiser import rules, the core → tea FK check) — retained as scaffolding because removing it costs more than keeping it, not because the boundary still buys anything. New code goes where it compiles under those guards, without deliberating over core-vs-tea; an interface added because a guard requires one is plumbing, not a seam designed for a second domain. Each workflow primitive (ChecklistEngine/GateRule, RoundLifecycle, StaleClock, TagSetCompatibility) is built and sized by its first consuming feature. Nothing is refactored. Refined by AD #31 (2026-09-09) — the “stays physically in place” half is reversed: FS-14 removes the scaffolding; the cancellations (FS-12/FS-13, the retired acceptance test) and the first-consumer rule for the primitives stand |
AD #17’s only return was OQ-50’s assumed reuse of the generic layer on future projects; that reuse is no longer expected, so the unspent half (FS-12 + FS-13) is cancelled and the cost already paid is sunk — not an argument either way. Lead sign-off: Tharinda, 2026-09-07 (the approvals on harness PR #52 and forge-et-be PR #15 — required because AD #17 is a DO-NOT-REVERSE row). No change request: internal structure only (L-001). Full rationale and accepted trade-offs as written: .forge/engagement-log.md § AD #29; the history: architecture.md § Core / Domain Separation |
2026-09-07 |
| 30 | Role management is fully configurable, on a code-declared permission catalog — refines AD #15; AD #26 survives intact and is strengthened. The grant tuple becomes (role, permission_key, scope). The catalog is code; the grants are data: each module declares its permissions as constants with metadata (key shaped <resource>.<action> — deal.view, deal.create, quote.issue, price.publish; category; label; description; UI group; whether scope-aware), roughly 100–150 keys covering the system; the database stores only which role holds which key at which scope, and the admin UI renders from the catalog, so an admin can only grant something the code actually checks. Admin-authored roles: Empire creates roles and attaches any catalog permissions. Role templates: built-in templates for the six confirmed roles (plus the seeded managing_director profile) and admin-created ones; creating a role from a template copies the permission rows — a snapshot, never a link — so editing a template cannot silently mutate live roles. The four levels (read / edit / ai-use / execute) survive as the category metadata on each permission, not as a grant column — this is load-bearing: the ai-use-vs-execute split is what makes the PRD’s human-in-the-loop promise structural, and as metadata it becomes more visible (the role editor can warn “this role holds N outward-acting permissions”). A reporting hierarchy: app_user.manager_id, a nullable self-reference; visibility scope becomes own | team | all, where team is the subtree beneath the user. Scope is per-permission, not per-role: a Sales Manager may hold deal.view at team while holding deal.edit and mailbox.read at own — a per-role scope would have a manager reading their reps’ personal mail; the catalog declares which permissions are scope-aware at all. Multiple roles union to the most permissive grant. AD #26 is unchanged in every check: code asks user.can("quote.approve_sub_floor"), never which role or template the user holds. The catalog is not enumerated here — that is FS-6 spec Rev 3’s and F5’s work; only the key shape, the ordering convention (<resource>.<action>, grouped by resource) and the metadata fields are locked. Refined by AD #32 (2026-09-11): no role templates (only the system superadmin ships), one role per user (no union), and AI is not a grantable level — the category axis is read / edit / execute. The catalog, grants-as-data, the hierarchy and AD #26 stand |
Empire asked for fully configurable roles (2026-09-07); a fixed per-role level matrix (PRD Rev 17) cannot express it, and retrofitting configurability after FS-6 ships is the failure AD #15 exists to avoid. Treated as a V1 requirement — no change request (Dinil, 2026-09-07); the proposal §3.2 divergence is stated as a post-issue note (L-001). Lead sign-off: Tharinda, 2026-09-07 (reverses PRD Rev 17, which Tharinda approved). Accepted trade-offs — UI grouping, the orphan-grant check, new keys shipping fail-closed, the superadmin and last-admin guards — and the full text as written: .forge/engagement-log.md § AD #30 |
2026-09-07 |
| 31 | The core/domain split is collapsed — nothing of it remains. Supersedes the module/schema half of AD #17 and the “stays physically in place” half of AD #29; AD #29’s cancellations (FS-12/FS-13, the retired acceptance test) and its first-consumer rule for the workflow primitives stand. Backend: one Gradle module — a single build.gradle (no buildSrc, one gradle.lockfile), feature-first packages com.empireteas.<capability> with no core/tea/app segments (platform, catalog, pricing, then one package per feature as it lands; layers web/service/repository inside each), one Postgres schema (public), one Flyway location with the shipped migrations squashed into a fresh V1… sequence (nothing was ever deployed or migrated — confirmed 2026-09-09). Frontends: forge-et-fe becomes one package (no pnpm workspace, no tsc -b) laid out src/{app, features, ui, lib}; forge-et-pwa mirrors the layout and keeps byte-copies of the shared token files behind a drift check. The split’s guards go (build graph, BoundarySpec’s boundary rule, VocabularySpec, ExplicitSchemaSpec, CoreToTeaFkSpec, CoreOnlyMigrationSpec, the version-band map, the cruiser package rules); every hygiene guard stays (Error Prone/NullAway, -Werror, doclint, @NullMarked, the src/test/java guard, fixture reachability + leak, FS-10’s web → service → repository layering, testid/bundle/Trivy/coverage) and one is added: feature packages and folders must be free of dependency cycles, with platform/ui depending on no feature. Plain Spring Boot — no Spring Modulith. Delivered as foundation slice FS-14 (.forge/specs/foundation/014-single-module-spec.md) |
Opened up, the scaffolding AD #29 had kept was mostly ceremony taxing every feature for a payoff already declared gone, and the cost of removal was at its lifetime minimum — no environments, no feature code, Gate 3 not run. Lead sign-off: Tharinda, 2026-09-09 (the approvals on the FS-14 harness PRs — required because AD #17 is a DO-NOT-REVERSE row and AD #29 refined it). No change request: internal structure only (L-001). Accepted trade-offs — about four working days on the Foundation band, the code freeze, FS-6 Rev 4, the retired split-only ACs — and the full text as written: .forge/engagement-log.md § AD #31 |
2026-09-09 |
| 32 | Role management is simplified — refines AD #30; the catalog/grant model and AD #26 stand. Three changes. (1) No role templates. The role_template concept goes; the only seeded role is the non-deletable system superadmin. Empire’s Administrator creates every other role by hand from the code-declared permission catalog, with Altrium supervising at go-live; the six confirmed roles (plus the Managing Director role) become the recommended day-one set recorded in the PRD’s capability matrix and client/roles-and-permissions.md, not seeded data. (2) One role per user. app_user.role_id replaces the M:N join; the most-permissive union disappears; a person who needs a mix gets a purpose-built role; a role still held by a user cannot be deleted; last-admin protection stands. (3) AI is not a grantable level. The category axis is read / edit / execute (client-facing: View / Edit / Act). AI the system runs on its own (lead scoring and triage, inquiry extraction on intake, account briefings, the morning briefing, duplicate/spam detection) is not a permission — its results are visible under the record’s read, and the per-feature {model, enabled} switch (AD #19) is the control. AI a user invokes on a record (draft an email, the quote assistant, the brief assistant) is implied by the edit/execute permission it assists — whoever may send may ask for a draft. The human-in-the-loop invariant is unchanged: the AI layer holds no permission, and committing any AI output is an execute action a person performs. Grants stay (role, permission_key, scope) over the code catalog; manager_id and own/team/all per permission stand; AD #26 is untouched |
Team decision — Tharinda, 2026-09-11; confirmed by Dinil. Templates, the multi-role union and a grantable ai-use level each added a mechanism nobody had asked for and an Administrator would have to learn; removing all three shrinks FS-6 and F5 rather than growing them. Lead sign-off: Tharinda, 2026-09-11 (required because AD #30 refines a DO-NOT-REVERSE row). No change request (post-issue note on the proposal). Accepted trade-offs — no roles until an Administrator creates them, role sprawl, AI switched per feature — the consequences, and the full text as written: .forge/engagement-log.md § AD #32 |
2026-09-11 |
The whole table as it stood on 2026-10-02, before each row was cut to the rule and one reason
On 2026-10-02 every row of CLAUDE.md § Architecture Decisions was shortened to the rule in force and a one-sentence reason, to reduce what every session loads. The table below is the full text of every row immediately before that change, copied verbatim. It includes everything refined since the 2026-09-23 table above: AD #33 to AD #37, AD #23’s new location and AD #19’s new models. Read it for the detail behind a row; the CLAUDE.md row is the rule in force.
| # | Decision | Why | Date |
|---|---|---|---|
| 1 | Backend: Java 21 + Spring Boot (version line: AD #25) | Team’s existing enterprise-backend stack | 2026-07-13 |
| 2 | Frontend: TypeScript + React, built as a React SPA on Vite (AD #21) | Client prototype’s own runtime is React-based; strongest ecosystem for Kanban/calendar widgets | 2026-07-13 |
| 3 | Database: PostgreSQL (AWS RDS), single-tenant relational schema | PRD-preferred; structured domain model; mature Flyway/JPA tooling | 2026-07-13 |
| 4 | Hosting: AWS (ECS Fargate, RDS, SQS, S3, Secrets Manager), one AWS account per environment; Fargate carries the backend only, both frontends are static S3 + CloudFront (AD #22) | Broadest managed-service catalog; team’s enterprise-stack familiarity | 2026-07-13 |
| 5 | Sessions are server-side (Spring Session JDBC), not JWT, onto one User entity. Login paths: AD #28. Deactivation ends a user’s sessions at once; permission changes apply on the next request without logout (AD #34) |
The session model stands; the original dual-login rationale was superseded by AD #28 | 2026-07-13 |
| 6 | AI integration isolated behind an AIProvider interface and called from the backend — no separate AI service; transport is Bedrock in-account (AD #19) |
Isolates the OQ-15/R-PRD-002 self-hosted-model fork so a “no” swaps an implementation, not a rewrite | 2026-07-13 |
| 7 | Background jobs via AWS SQS + Spring Boot async workers in the same codebase — no separate microservice/orchestrator | Team scale (10–20 users) doesn’t justify microservice/K8s complexity; in-house-first | 2026-07-13 |
| 8 | Admin custom fields (F34) stored as a JSONB column per entity, not dynamic ALTER TABLE/EAV tables |
Keeps core schema stable and query-performant while allowing schema-less extension | 2026-07-13 |
| 9 | Dependency-vulnerability CI gate: CVSS ≥ 7.0 is the build-failing threshold (report-only until the clean-baseline flip — AD #27); per-repo suppressions need a justification and an expiry; one tool across the Java and Node ecosystems — the tool is Trivy (AD #27) | One uniform gate for both ecosystems | 2026-07-13 |
| 10 | CRM→ERP handoff (F19) ships V1 as a manual document behind an ErpHandoffService seam; no live integration until OQ-2 resolves |
R-PRD-001 accepted risk; keeps the seam ready without blocking on an unconfirmed ERP API | 2026-07-13 |
| 11 | Every Stage carries a stable, non-editable stage_type separate from its admin-editable display name |
Prevents admin pipeline edits (F24) from silently breaking AI/automation logic keyed on stage semantics (R-14) | 2026-07-13 |
| 12 | All timed work runs via EventBridge Scheduler → SQS → worker; never in-process @Scheduled. One carve-out (FS-6 spec Q-1): Spring Session JDBC’s expired-session cleanup stays in-process, because its duplicate firing is redundant work, not a duplicate outward effect |
With more than one ECS task, @Scheduled fires on every task — duplicate alerts and duplicate buyer-facing email |
2026-08-06 |
| 13 | Every queued job carries an idempotency key; consumers are replay-safe | SQS standard queues deliver at-least-once; an outreach step sent to a buyer twice is unacceptable | 2026-08-06 |
| 14 | Bulk prices and costs are effective-dated rows, never updated in place | Price history + as-of quoting are PRD requirements (OQ-33/38/42); temporality cannot be retrofitted without rewriting every read path | 2026-08-06 |
| 15 | Authorization resolves as a grant check, never a flat authority check; the grant model is AD #30 as refined by AD #32, AD #34 and AD #37, and a record’s reach is AD #35 as refined by AD #37 | OQ-47 requires layered access across roles, which a flat authority check cannot express | 2026-08-06 |
| 16 | Microsoft Graph is the only mailbox integration in V1, behind a MailboxProvider seam; Gmail/Exchange/IMAP are out of scope and additive only via change request |
The issued proposal quoted Microsoft 365 via Graph only, and OQ-24 confirmed it is all Empire uses; the seam keeps a later provider cheap | 2026-08-06 |
| 17 | Superseded. The core/domain separation (crm-core/domain-tea modules, core.*/tea.* schemas, four-layer enforcement) was stopped by AD #29 and collapsed by AD #31; nothing of it remains |
Its return rested on OQ-50’s assumed reuse of the generic layer, which is no longer expected (AD #29) | 2026-08-06 |
| 18 | Backend build tool: Gradle (Groovy DSL — a single build.gradle), not Maven |
Team decision; matches every existing Altrium backend’s convention | 2026-08-18 |
| 19 | AI runs on Claude via Amazon Bedrock exclusively — Haiku 4.5 (high-volume) / Sonnet 5.5 (synthesis; replaced Sonnet 5 on 2026-09-30, and Haiku 5.5 replaces Haiku 4.5 once it reaches Bedrock), called from the project’s AWS account in us-east-1 through the Bedrock inference profile each model is offered on (ai-provider-strategy.md §4b — neither pinned model runs in-Region on bedrock-runtime); no direct-API tier in production and no second-provider fallback (outages degrade to the manual path); per-feature {model, enabled} runtime config. The one sanctioned exception is the proposal’s A.3.1 comparison, run on anonymised inquiries with Altrium-held evaluation keys (ai-provider-strategy.md) |
One vendor relationship and one bill, with in-account processing as the strongest data-governance answer; Bedrock’s new-model lag is acceptable because models are pinned (ai-provider-strategy.md) |
2026-08-18 (models revised 2026-09-30) |
| 20 | Trade-show capture app ships at full scope inside V1 (Option C) as a parallel work-stream — in its own repository (forge-et-pwa) with its own hosting/URL; lead notifications email-only via SES. Originally weeks 8–13; Gate 3 placed it in Phase 2 with its scope unchanged |
Matches accepted proposal §4 and is viable because a working prototype exists; the descope lever back to capture-and-feed is decided at the capture-app checkpoint (originally Fri 13 Nov; the revised Statement of Work of 2026-09-29 holds it during Phase 2, date to be set — project-timeline.md §2) |
2026-08-18 |
| 21 | Both frontends are React SPAs built with Vite — no Next.js, no SSR anywhere | Internal, authenticated apps with no SEO need; an SPA is simpler to build, test and host, and matches the team’s frontend convention | 2026-08-18 |
| 22 | Frontend hosting: static S3 + CloudFront for both apps (each at its own URL, ACM TLS); the backend is the only Fargate service, behind the ALB. FE build-time config via GitHub Actions variables/secrets (non-sensitive values only — the bundle is public); backend secrets via task-definition secrets references → Secrets Manager, AWS access via the task IAM role (no static keys) |
An SPA needs no server, and S3 + CloudFront is cheaper than a Fargate frontend; secrets never sit in git, images, task definitions or the bundle | 2026-08-18 |
| 23 | All AWS infrastructure is Terraform-managed — environment-parameterized modules instantiated per account (dev, prod, and a temporary uat instance applied for each acceptance window and destroyed after it); state in S3 with DynamoDB locking, per account; lives in its own repository, forge-et-iaac (the DevOps work — Terraform and the rest of the infrastructure code; replaced forge-et-be/terraform/ on 2026-09-29) |
The per-phase temporary-UAT commitment is only cheap if an environment is one terraform apply away; IaC also keeps dev and prod the same shape. The separate repository is where DevOps (Shyamin Ayesh) does this work; the lead confirmed it on 2026-09-29 |
2026-08-19 (location revised 2026-09-29) |
| 24 | Trunk-based branching: main is the trunk; a release/vX.Y.Z maintenance branch exists only for a release that is live in production, cut from its tag, protected, never deleted. Releases are annotated tags vX.Y.Z; dev deploys main, UAT and production deploy tags. Branch, commit and PR names carry the ticket id (feat(F2): …, feature/F2-…) |
A phase can reach production before V1 signs off, so a hotfix path that excludes next-phase work is needed from the moment something is live; tags give immutable handover artifacts and keep main the single integration point |
2026-08-19 |
| 25 | Spring Boot runs on the 4.1 line (4.1.x) — a moving pin: expect to take a Boot minor roughly once a year. Entails Spock 2.4-groovy-5.0 and a jcl-over-slf4j bridge |
Boot 3.5’s free support ended 30 Jun 2026 and 4.0’s ends 31 Dec 2026, before V1 sign-off; 4.1 runs to 31 Jul 2027 | 2026-08-21 |
| 26 | An authorization check names the permission it needs, never the role that happens to carry it. F7’s sub-floor gate asks user.can(APPROVE_SUB_FLOOR_QUOTE) (catalog key quote.approve_sub_floor), never user.role == ADMIN. Who holds a permission is configuration, not code — and no separation of duties is coded either: the recommended configuration keeps sub-floor approval on the Managing Director’s role, and the audit trail records every grant (AD #34, AD #36). Refines AD #15 |
role == ADMIN would silently make every future Administrator a below-floor-pricing approver, and no audit log would catch it |
2026-08-21 |
| 27 | The dependency-vulnerability gate runs on Trivy in all three app repos — one trivy fs Slow-lane step per repo over the committed lockfiles with --include-dev-deps (Vite puts nearly everything in devDependencies, and build tooling is supply chain), gating on --severity HIGH,CRITICAL ≡ CVSS ≥ 7.0; report-only until the dependency baseline is clean across all three repos, then enforcing (FS-4 spec Rev 3); governed per-repo .trivyignore.yaml (id, purls, statement, tool-enforced expired_at); Dependabot stays as the alert layer. Refines AD #9’s tool |
OWASP Dependency-Check cannot scan pnpm, and Trivy was the only free tool meeting every AD #9 property on both ecosystems. Accepted while enforcement is phased: GHSA advisories can lag NVD by days to weeks — revisit when the gate flips to enforcing | 2026-08-31 |
| 28 | Microsoft (Entra ID) OAuth2 is the only login path; Google OAuth and local email/password are out of V1. local/test profiles authenticate through a profile-scoped stub login that cloud profiles cannot reach (coding-standards §5), so laptops and CI need no Entra registration. Further providers are additive only — a client registration plus a change request; the user_identity (provider, subject) shape is kept. Refines AD #5’s login half. Sign-in succeeds only when the verified email matches one active, pre-created user; there is no Entra user sync — Empire disabling an Entra account is a backstop to in-app deactivation, blocking the next sign-in but not a session already open (AD #34) |
Empire is all Microsoft 365 (OQ-24), so a local fallback protected nobody, and dropping it removes password storage and reset/lockout surface. Accepted: an Entra outage blocks all login, and every user needs an Empire M365 account | 2026-09-04 |
| 29 | The core/domain separation is no longer extended. FS-12 and FS-13 are cancelled; AD #17’s acceptance test (“deleting domain-tea leaves a working generic CRM”) is retired; each workflow primitive (ChecklistEngine/GateRule, RoundLifecycle, StaleClock, TagSetCompatibility) is built and sized by its first consuming feature. Its “the built scaffolding stays in place” half was reversed by AD #31 |
The split’s only return was OQ-50’s assumed reuse of the generic layer, which is no longer expected. Lead sign-off: Tharinda, 2026-09-07 (history: architecture.md § Core / Domain Separation) |
2026-09-07 |
| 30 | Role management is configurable, on a code-declared permission catalog — refines AD #15; AD #26 stands. The grant is (role, permission_key, scope) (AD #37 removes the scope). The catalog is code, the grants are data: each module declares its permissions as constants keyed <resource>.<action> (grouped by resource), each carrying label, description, UI group and whether it is scope-aware; the database stores only which role holds which key at which scope, and the admin UI renders from the catalog, so an admin can grant only what the code checks; a new key ships fail-closed, and orphan grants are checked. The catalog itself is enumerated in FS-6 Appendix A, not here — its shape (view/manage per entity plus a short special list) is AD #34. Reporting hierarchy: app_user.manager_id, a nullable self-reference; scope is own | team | all (defined over ownership and shares by AD #35), set per permission, not per role, so a manager can see the team’s leads without being able to edit them (replaced by AD #37: reach comes from the reporting line, an entity’s all key widens it, and view and manage on one entity reach the same records). Role templates, the multi-role union and the ai-use level were removed by AD #32; the category axis, the superadmin and the * wildcard by AD #34 |
Empire asked for fully configurable roles (2026-09-07), which a fixed per-role matrix cannot express. Treated as a V1 requirement, no change request (proposal §3.2 post-issue note). Lead sign-off: Tharinda, 2026-09-07 | 2026-09-07 |
| 31 | The core/domain split is collapsed; nothing of it remains. Backend: one Gradle module (a single build.gradle, no buildSrc, one gradle.lockfile); feature-first packages com.empireteas.<capability> (starting platform, catalog, pricing, then one per feature) with no core/tea/app segments, layers web/service/repository inside each; one Postgres schema (public) and one Flyway location. Frontends: forge-et-fe is one package laid out src/{app, features, ui, lib}; forge-et-pwa mirrors the layout and keeps byte-copies of the shared token files behind a drift check. Every hygiene guard stays (Error Prone/NullAway, -Werror, doclint, @NullMarked, the src/test/java guard, fixture reachability and leak checks, FS-10’s web → service → repository layering, testid/bundle/Trivy/coverage), plus one: feature packages and folders are free of dependency cycles, and platform/ui depend on no feature. Plain Spring Boot — no Spring Modulith. Delivered as FS-14 (.forge/specs/foundation/014-single-module-spec.md) |
The scaffolding AD #29 had kept taxed every feature for a payoff already gone, and removal cost was at its lowest. Lead sign-off: Tharinda, 2026-09-09 | 2026-09-09 |
| 32 | Role management is simplified — refines AD #30; the catalog/grant model and AD #26 stand. (1) No role templates: Empire’s Administrator creates every role from the catalog; the six roles named on 3 August plus the Managing Director role are a recommended set that Empire may rename, change or not create (PRD capability matrix, client/roles-and-permissions.md), not seeded data. (Its “the only seeded role is a non-deletable system superadmin” was replaced by AD #34’s migration-seeded, editable IT Admin role.) (2) One role per user: app_user.role_id; a person who needs a mix gets a purpose-built role; a role still held by a user cannot be deleted; last-admin protection stands (on access.manage, AD #34). (3) AI is not a grantable level. AI the system runs on its own (lead scoring and triage, inquiry extraction, account and morning briefings, duplicate/spam detection) is not a permission — its results are visible under the record’s view, and the per-feature {model, enabled} switch (AD #19) is the control; AI a user invokes on a record (an email draft, the quote or brief assistant) is implied by the manage permission it assists — whoever may send may ask for a draft. The AI layer holds no permission; committing any AI output is an action a person performs. (Its read / edit / execute category axis was collapsed into view / manage by AD #34) |
Each removed mechanism was one nobody asked for and an Administrator would have to learn. Team decision, confirmed by Dinil. Lead sign-off: Tharinda, 2026-09-11 | 2026-09-11 |
| 33 | The backend keeps its own address; the apps call it cross-site. Each environment’s backend stays at api.<env> (api.crm.empire.lk, api.uat.crm.empire.lk, api.dev.crm.empire.lk) behind the ALB; CloudFront serves only the static bundles. So: the frontends call VITE_API_BASE_URL = the api.* address per environment; the backend’s CORS list names that environment’s CRM and capture-app origins, credentials allowed; the XSRF-TOKEN cookie carries Domain=<env's CRM host> so the SPA can read it, and its name differs per environment (crm.empire.lk is the parent of dev. and uat.crm.empire.lk, so prod’s cookie also reaches them); the SESSION cookie stays host-only on api.*. The Entra reply URLs stay on api.*. Resolves register A-4 |
Less AWS configuration than routing the backend through each app’s CloudFront, and the reply URLs already registered on api.* keep working (three new mailbox URLs instead of nine new URLs). Accepted cost: a small cookie change in the backend and both frontends, per-environment settings that must match, and a CORS preflight on writes. Lead sign-off: Tharinda, 2026-09-24 |
2026-09-24 |
| 34 | Access is configured, never predefined, on a minimal catalog — refines AD #30 and AD #32; AD #26 and AD #28 stand. Users: sign-in needs an active, pre-created app_user whose email matches the Microsoft-verified one — no auto-provisioning, no invitation; users are deactivated and reactivated, never deleted; deactivation ends the user’s sessions at once, and nobody can deactivate themselves. No predefined roles: no templates, no superadmin, no non-deletable system role, no * wildcard; a role can be renamed (its key never changes), re-permissioned, and deleted only while no user, active or deactivated, holds it. The first admin comes from a migration: one Flyway migration seeds, in every environment, an editable IT Admin role holding access.manage and one active user holding it; the email is a Flyway placeholder set per environment — the crm01@empire.lk test mailbox outside production, the admin address Empire confirms in production (from Secrets Manager, never in git). Never a real person’s email outside production. The catalog is minimal: each entity has <entity>.view and <entity>.manage — manage implies view and covers every action on the entity (create, edit, share, remove a share, reassign the owner, AI drafting) — plus a short list of special keys (price.publish, quote.approve_sub_floor); all user, role and hierarchy administration is one unscoped access.manage, configuration is settings.manage, and a user’s own mailbox is email.manage (no role can read another person’s mailbox). No category axis. At least one active user always holds access.manage: a deactivation, role change, role edit or role delete that would leave none is refused. Self-escalation is unlimited and no separation of duties is coded — the proposal’s Managing Director approval is met by granting quote.approve_sub_floor only to that role; the audit trail (AD #36) is the control. Permission changes apply on the holder’s next request, with no logout (a delivery-team call under the lead’s delegation — the backend already re-reads grants on every request). Keys are listed in FS-6 Appendix A |
The lead’s design (2026-09-22/24): roles built from scratch, the fewest keys that describe the business, and a migration-seeded admin so the first person can get in; the superadmin, the nine admin keys and the category axis were mechanisms nobody needed. Lead sign-off: Tharinda, 2026-09-24 | 2026-09-24 |
| 35 | A record has one owner and can be shared; a share widens reach, never authority. Each lead, account, deal and quote carries one owner_id (nullable on leads only), and shares are rows in one record_share table (one nullable foreign key per entity type, exactly one set; shared-with, shared-by, shared-at) — never arrays. Reach: own = owned by me or shared with me; team = owned by, or shared with, me or anyone below me in the reporting tree (all levels); all = every record, unowned ones included (AD #37 makes own and team one reporting-line rule with no choice, and all a key). One rule serves both list queries and single-record checks. A user acts on a record only when their role holds the key and the record is in reach. 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, timeline, linked email) follow their parent’s reach. A user who owns records, or has direct reports, cannot be deactivated until they are reassigned. Built once, as a substrate, before any list read-path (F5-f). Refines PRD Rev 29 (OQ-58) |
The lead’s design (2026-09-23): the reporting tree for managers, explicit shares for everyone else. One rule for lists and records removes the list-versus-record mismatch F1-a ships as an interim (its FR-O3, Q-11). Lead sign-off: Tharinda, 2026-09-24 | 2026-09-24 |
| 36 | Every write and every security event is recorded in one audit trail, in the same transaction as the change. One audit_event table and one service record who (a user, or SYSTEM for background work), what, which record, when and the change — for every write, plus sign-in success and refusal, sign-out, deactivation and reactivation, role and permission changes, sharing and reassignment, and exports; never reads. Kept indefinitely in V1, with no viewer screen in V1. Every table also carries created_at / modified_at (framework-owned tables such as Spring Session’s excepted), and created_by / modified_by where a person acts. Built as F39: F5-c and F5-d wait for it, and it retrofits the writes already on main; later writing features call it |
Unlimited self-escalation (AD #34) and transitive sharing (AD #35) are acceptable only because every change can be attributed afterwards. Lead sign-off: Tharinda, 2026-09-24 | 2026-09-24 |
| 37 | A grant has no scope; reach comes from the reporting line — refines AD #30, AD #34 and AD #35; AD #26 stands. The grant is (role, permission_key). A key on an entity that has an owner reaches the records owned by, or shared with, the user or anyone below them in the reporting tree, through every level — for a user with nobody below them, the records they own or that are shared with them. Each such entity has a third key, <entity>.all (lead.all, account.all; deal.all, quote.all and sample.all in Phase 2), which widens the holder’s view or manage on that entity to every record, unowned ones included, and cannot be held without one of them. Given up: a role reaching further with view than with manage on one entity, and a user with people below them reaching only their own records. Setting a user’s manager is therefore an access decision (it stays under access.manage and is audited — AD #36). Unchanged: mailboxes are outside every reach (email.manage is the holder’s own mailbox only); keys without an owner-bearing entity (access.manage, settings.manage, buying_standard.*, price.publish, quote.approve_sub_floor) have no reach; sharing, children following their parent, and one rule for lists and single records (AD #35). The all keys are added to FS-6 Appendix A and the code changed by F5-l |
For a user with nobody below them, team already gave exactly what own gave, so the scope choice only mattered for managers — and the reporting line already records who manages whom; only “every record” needs a setting. Every recommended role holds one reach per entity for view and manage alike, so no recommended role is lost, and the role editor loses a scope choice on every key. Lead sign-off: Tharinda, 2026-09-27 |
2026-09-27 |
Active Context — as it stood on 2026-09-23, before it was compressed
Copied verbatim from CLAUDE.md § Active Context immediately before the 2026-09-23 compression, which moved the completed Gate 3 narrative here, replaced copied counts with pointers, and shortened items whose detail lives in their own documents. Nothing below was re-reconciled against the tracker.
Current state only — last reconciled 2026-09-17. The dated narrative of how we got here (per-slice histories, meeting fold-ins, decision cascades) lives in .forge/engagement-log.md; a paragraph that stops being current moves there rather than being rewritten here.
Where the engagement stands. Gate 1 passed-with-risks (2026-07-07). Gate 2 passed-with-risks-and-spikes (2026-08-06; no spike remains open). Foundation sealed (2026-09-16) — every slice in an exit state; the two cloud halves (FS-1 Terraform, FS-5 CloudWatch/SNS/SES) stay deferred companion specs gated on the AWS account. Gate 3 passed (2026-09-17, Run 1 — verdict Tharinda): the PRD’s 31 in-scope rows are decomposed into 89 features in .forge/features.md / tracker.yaml — 37 in Phase 1 (in-progress, started 2026-09-17), 52 in Phase 2 (locked) — each with a stub spec under .forge/specs/, every blocked_by explicit, the three lanes drawn, setup.status: ready. Engineering starts now: /forge-deliver <id> on a Phase 1 feature; the day-one starts are F5-a and F1-a, then F11-a, F26-a, F4-a, F20-a, F5-c, F5-d. Phase due-dates are set (/forge-set-dates, commit b0252c9): Phase 1 → 2026-10-30, Phase 2 → 2026-11-27.
Commercial frame (binding — L-001). Proposal accepted 2026-08-16: USD 15,500 one-time + USD 360/month support; AWS is Altrium-run under SOW ET-002 at USD 650/month (.forge/client/aws-sow.md); running costs are quoted from .forge/client/sow-cost-annexe.md, never the proposal’s §A.2.2/§A.8. Dates: kickoff Tue 1 Sep 2026; Phase 1 complete Fri 30 Oct, client UAT 2–13 Nov; feature-complete Fri 27 Nov; UAT 30 Nov–15 Dec; sign-off target Tue 15 Dec (.forge/client/project-timeline.md). Each UAT round runs in a temporary environment; development never doubles as UAT. Where the proposal and an internal document disagree, the proposal wins and the divergence is stated as a post-issue note on its header, never absorbed (.claude/rules/source-trust.md). Still unwritten: the SoW text, §17 terms, and the phase acceptance-criteria sets.
Team. Three full-stack developers — Tharinda Rajapaksha (lead), Dinil Gamage, Biseni Perera — each carrying development, QA and harness work; waves are sliced vertically, no backend/frontend split. Pairings and the client-contact rule: .forge/team-guide.md.
Gate-3 standing instruction (team). Decompose into small vertical work items, each verifiable end-to-end across FE + BE and sized for quick review and test; when in doubt, split smaller. Every blocked_by explicit; parallel vs sequential classified — the dependency graph is the work-division plan across the three developers. Phasing intent (2026-09-13, clarified by the lead 2026-09-16): Phase 1 = Microsoft login/logout; users and role management; the reporting hierarchy and what it makes visible; email integration (two-way sync, send, AI draft); leads — add/edit, Pipedrive migration, AI research + ranking (hot/cold), AI summary, following up cold leads; accounts — add/edit, Pipedrive migration, AI briefing; sharing leads and accounts with colleagues; weekly price updates against standards and the per-account send. Phase 2 = everything not in Phase 1 (lead, 2026-09-16): pipeline and deals, samples, quotes, the capture app (F36 — AD #20’s scope unchanged, timing shifts), dashboards, bulk email (F37), and the remaining AI and parity features. Migration is leads + accounts only — a fresh start on deals. F37 is placed in Phase 2 by the lead’s instruction but is not yet commercially committed — the proposal does not cover bulk sending (PRD Rev 28, L-001), so its Phase 2 placement needs a change request or a compensating descope recorded before it is built; nothing in Phase 1 may assume it ships. WhatsApp stays out. The price-lookup page is not a Phase-1 priority. Applied at Gate 3 (2026-09-17) with two Phase 1 pulls the team took and the lead confirmed — F3-a (follow-up tasks on leads and accounts) and F20-d (email templates, seeding a weekly-prices template) — and F12 (AI extraction) in Phase 1 as the first AIProvider consumer. The divergence from proposal §6’s P0/P1a grouping is recorded: post-issue note on the proposal header (2026-09-17), project-timeline.md §2 revision, a drafted line to Empire in engagement-gate-runs.md § Gate 3 Run 1 for Tharinda to send. Eleven borderline splits are marked ◐ in features.md — the first to merge back if the per-feature overhead bites.
Live decisions to build against (each recorded where it lives): Microsoft-only login (AD #28); configurable roles on a code-declared catalog — coarse view/manage per entity plus a short list of sensitive keys, one role per user, no templates, AI not grantable (AD #30/#32, FS-6 Rev 6); record sharing as the third visibility path, riding on manage, landing with F1/F2 beside the list-visibility predicate they owe regardless (PRD Rev 29, .forge/design/data/record-sharing-model.md); no products catalog — the Buying Standard is the sellable record for bulk and private label alike (PRD Rev 27, FS-15); one price per standard per week, effective-dated rows (PRD Rev 23, AD #14; whether private-label standards are weekly-priced is OQ-61), and that price is a four-figure build-up — LKR → + overhead (LKR) → converted to USD → + margin → final USD, all four on the append-only row, only the final USD figure required (PRD Rev 31, Tharinda 2026-09-17; OQ-43 refined not reversed — USD is still the only published currency and still not a price-key axis; whether the FX rate and overhead are per-week or per-standard is OQ-59); every lead is researched before it is ranked, as a background job on a SearchProvider seam shared with F36 — provider still to be chosen (PRD Rev 30, .forge/design/ai/lead-research-source-options.md); single-module, feature-first code layout (AD #31); the AI layer on Bedrock behind AIProvider (AD #19). The four provider seams (AIProvider, MailboxProvider, ErpHandoffService, AuctionPriceProvider) do not exist yet — R-FND-001: the first consuming feature builds each on FS-11’s SeamGuard pattern.
Open risks. R-ARCH-001 (three developers against a committed window; Gate 3 restated the basis — 89 features is a re-slicing of the 30-feature basis, not growth — but the cycle-day band is still owed a re-run once the first Phase 1 specs are wave-decomposed; the forge-estimate baselines measure agent time without human queue time and cannot stand in for it); R-FND-001…004 (seams, the six list-screen states owed by the first screen feature, the cloud-gated halves, the backend Slow-lane trend); R-PRD-001/002 architected around. OQ-9 gates F9. Most other open OQs wait on the Pipedrive audit — closing it removes more calendar risk than any feature cut.
Owed, with owners. The line to Empire on the re-grouped releases (Tharinda — draft in engagement-gate-runs.md § Gate 3 Run 1); Phase 1 acceptance criteria and the SoW text (lead); FS-15’s three framework follow-ups in their own PR (pipe exit-status trap, capability re-check before recording an absence, external-artifact rule for plan test tables); the FS-7 SYSTEM audit principal (owner to name); the SearchProvider provider choice — spike SP-ARCH-004 (Dinil), stage 1 ran 2026-09-18: the query-construction result is settled and F11-c can use it now (name + domain only, never country or industry words), but the provider choice is not — stage 2 waits on the AWS account alone, which carries both the AgentCore Gateway and Bedrock for the scoring (Bedrock uses AWS credentials, not a separate key) (.forge/design/ai/lead-research-source-options.md §10); OQ-63 (past orders) to Empire; a courtesy note to Tharinda that his sharing sketch was read as owner + shared rather than co-owners; forge-et-be/docs/data-model.md §2.2/§2.5 — three nullable build-up columns (price_lkr, price_lkr_with_overhead, price_usd_pre_margin) beside the NOT NULL final USD, §2.10 R2 restated, and docs/proofs/pricing/01-schema.sql moved in the same commit for the drift check (Tharinda, AD #31 — PRD Rev 31); the Trivy enforcement flip — the next routine Spring Boot upgrade bringing embedded Tomcat ≥ 11.0.25 via the BOM (no forced Tomcat override now — team decision 2026-09-17; the only hard deadline is that it lands before the backend is deployed to any reachable environment), watched on the backend’s Trivy report (owner: Tharinda — backend, and the CI flip is his approval; no Gate-3 feature owns it), then a coordinated TRIVY_GATE_EXIT_CODE 0→1 across the three pr-validation.yml files (lead-approved CI change) once be/fe/pwa all read 0 HIGH/CRITICAL, then the RC-1 clean-baseline attestation at Phase 1 handover (FS-4 spec Rev 3). Automated deployment — designed, not yet built: the backend deploy pipeline (GitHub Actions → build → Trivy → container → ECR → new task-definition revision → ECS rolling update) and the two frontend build → S3 → CloudFront pipelines are specified in .forge/design/architecture.md § CI/CD Pipelines and owned by the FS-1 cloud half (the deploy-dev / deploy-prod workflows plus a deployed environment), gated on the AWS account — there is no manual ECS / task-definition console step in the plan; wire it when the account lands (owner: Tharinda — the cloud slice).
Active Context reconciliation — 2026-09-26
- Removed from “Owed”: the
forge-et-be/docs/data-model.md§2.2/§2.5 price build-up columns (PRD Rev 31). It landed in forge-et-bea4984e6on 2026-09-17:data-model.mdanddocs/proofs/pricing/01-schema.sqlboth carryprice_lkr_with_overheadandprice_usd_pre_margin. - Owners cleared on F5-k, F38 and F5-c (lead’s call). F5-k and F38 had not started. F5-c has an approved spec and Decomposition Plan, but its Wave-1 plans are back at draft and it cannot dispatch before F5-k. None of the three has an owner until the work begins. CLAUDE.md’s F38 line was changed to match.
- Added to “Where the engagement stands”: a dated Phase 1 progress line, naming F5-f and F5-k as unowned features on the critical path.
Active Context reconciliation — 2026-09-29: a fourth developer, the revised schedule, and Empire’s own AWS account
Three changes, passed on by Tharinda on 2026-09-29, were confirmed together. All three had been held out of the harness documents since 2026-09-26 while they were unconfirmed.
- Team. Nanndish Satgunarajah (GitHub
nanndish-altrium) joins as the fourth full-stack developer, with the same role as the other three. He is a code owner and a requested reviewer on every PR in all four delivery repos. There are no fixed lanes: each developer takes the next unblocked feature from the tracker (team-guide.md § Working in Parallel — Four Developers). - Schedule. The revised Statement of Work (SOW-ET-001 v1.1, Rukshan Salgado’s Word document) replaces the SOW sent earlier and the proposal’s §7 estimate: Foundation incl. the cloud environments and deploy pipeline Fri 16 Oct 2026; Phase 1 Fri 27 Nov; Phase 1 UAT Thu 10 Dec; Phase 2 with the capture app Fri 8 Jan 2027; Phase 2 UAT, stabilisation and sign-off Fri 29 Jan 2027; an AWS environment ready by Fri 2 Oct, with day-for-day movement after it; a ten-business-day review window for Phase 2 and final acceptance. The lead’s rule is to finish building one to two weeks before each milestone; the lead chose the phase due dates Phase 1 Fri 20 Nov and Phase 2 Thu 24 Dec (
/forge-set-dates, phase dates only). The capture app stays in Phase 2. Two inconsistencies in the Word document were read and corrected inproject-timeline.md: weeks 15–18 end on 5 Feb, not 29 Jan, so the stage is weeks 15–17; and the week numbers count from w/c 5 Oct, not from the 1 Sep kickoff. - AWS. Empire Teas declined SOW ET-002. The AWS account is Empire Teas’ own, held by Kavindu Anthony and paid by Empire Teas’ card; AWS bills Empire Teas directly. Empire Teas gave administrator IAM credentials to Shyamin Ayesh, who is writing the Terraform, the environments and the developers’ logins.
aws-sow.mdis marked superseded and its text kept; the proposal header carries a 29 September post-issue note;sow-cost-annexe.mdbecame an estimate of Empire Teas’ bill. - Capacity (R-ARCH-001, restated in
tracker.yaml). At the pace measured 17–28 Sep, Phase 1 fits its 20 Nov build target with a little slack; Phase 2 is roughly 25 features short of 24 Dec. The lead takes the question of which Phase 2 features Empire will actually use to Empire at the Phase 1 hand-over, Fri 27 Nov. - Deferred, by the lead’s instruction. The Terraform location and review, the account structure and sign-in model, and both GuardDuty decisions wait until Shyamin Ayesh’s setup is finished. The AgentCore-versus-Tavily choice, and who holds a Tavily account if it is chosen, wait for Dinil’s SP-ARCH-004 stage 2.
- Added: AI model-lifecycle rules (
ai-provider-strategy.md§4c), at the lead’s request — newer Claude versions reach Bedrock on dates nobody knows in advance, and older ones are retired, so a model change must be configuration plus an evaluation run, with prompts written to carry across models.
The Active Context paragraphs this reconciliation replaced, verbatim:
Commercial frame (binding — L-001). Proposal accepted 2026-08-16: USD 15,500 one-time + USD 360/month support; AWS is Altrium-run under SOW ET-002 at USD 650/month (
.forge/client/aws-sow.md); running costs are quoted from.forge/client/sow-cost-annexe.md, never the proposal’s §A.2.2/§A.8. Dates: kickoff Tue 1 Sep 2026; Phase 1 complete Fri 30 Oct, client UAT 2–13 Nov; feature-complete Fri 27 Nov; UAT 30 Nov–15 Dec; sign-off target Tue 15 Dec (.forge/client/project-timeline.md). Each UAT round runs in a temporary environment; development never doubles as UAT. Where the proposal and an internal document disagree, the proposal wins and the divergence is stated as a post-issue note on its header, never absorbed (.claude/rules/source-trust.md). Still unwritten: the SoW text, §17 terms, and the phase acceptance-criteria sets.
Team. Three full-stack developers — Tharinda Rajapaksha (lead), Dinil Gamage, Biseni Perera — each carrying development, QA and harness work; waves are sliced vertically, no backend/frontend split. Pairings and the client-contact rule:
.forge/team-guide.md.
- Before the Phase 1 UAT window (2 Nov), confirm in writing how the temporary UAT environment per acceptance round is covered — SOW ET-002 as drafted excludes “additional staging, testing … environments” (Tharinda; OQ-49, owner Dinil — its 2026-09-27 update).
- The cloud bring-up is tracked as F38 (Phase 1, owner Tharinda; split into siblings F38-a to F38-h, plus F38-i in Phase 2) and is blocked externally: the AWS accounts do not exist yet — they wait on a billing discussion between Empire Teas and Altrium management (register §A-5). Until they exist, every feature is
donelocally only; F38 retests everything with code onmainend to end on dev once it is ready. There is no Bedrock without them, so every AI feature is built on the local stub only — a lead decision, not only a constraint: no direct Anthropic API for local development either (ai-provider-strategy.md§5 row 7) — and SP-ARCH-004 stage 2 (the search-provider comparison) waits too. The step-by-step checklist for the day the accounts arrive is at the top of.forge/cloud-gated-validation.md. If the accounts are still missing by mid-October, raise the Phase 1 UAT date with Empire.
Active Context reconciliation — 2026-09-30
A full check of tracker.yaml, features.md and this Active Context against the four delivery repos, after the merges of 28 and 29 September.
- Progress line. F4-a, F40 and F38-c had finished (F38-c on 2026-09-28, the other two on 2026-09-29) but were still listed as in flight, or missing from the line; F26-b and F38-a are now in spec.
- Critical path. F5-l needs only F5-k’s wave 1, on
mainsince 2026-09-28, so itsblocked_byis cleared and it runs beside F5-k’s wave 2; the critical path to the list screens is F5-l → F5-f. - F5-l is not backend-only. The 2026-09-27 stub said neither frontend read
/me’s scope field, from a search that matched nothing (.forge/lessons.mdL-102);forge-et-fedeclares the field and its tests assert it. - Tracker corrections: BUG-038 fixed (forge-et-fe#87 carried no bug id); BUG-022 in progress (forge-et-be#122, open); F5-i’s wave-1 work items closed; F5-j’s
planfield holds a status; stale notes on F5-c, F5-f, F5-h, F5-k, F11-b and F4-c brought up to date.
The Active Context sentences this reconciliation replaced, verbatim:
Phase 1 progress as of 2026-09-28 (
tracker.yamlis the live record): done locally — sign-in and the shell (F5-a, F5-b), the account and contact substrate (F1-a), the lead substrate (F11-a), the mailbox connection and inbox (F20-a, F20-b), the audit trail (F39), the cross-site CSRF cookie (F5-j) and, since 2026-09-29, the standards and price substrate (F26-a — its dev-environment timing check is owed to F38, register §B “F26-a”); in dev — the access-model realignment (F5-k), laptop Entra sign-in (F5-i) and the GuardDuty scan adapter (F38-c, wave 1 merged); in flight — the F38 parent contract (spec approved; delivered through its siblings); decomposed but waiting — F5-c (Tharinda) on F5-k, and F1-b on F5-f. F5-f has no owner yet (it has not started), and F5-f and F5-k sit on the critical path: F5-f blocks every list screen (F1-b, F11-b), and F5-k blocks F5-c and F5-d. F5-l (added 2026-09-27 by AD #37, no owner yet — it has not started) sits between them: it follows F5-k and blocks F5-d, F5-e and F5-f.
2026-10-01 — the crm.empire.lk delegation is live
Dinil Gamage sent the delegation request (F38-a Appendix A.1) to Kavindu Anthony, with Shyamin Ayesh copied. Kavindu first tried to create the subdomain at the LK registry (NIC.lk) and asked whether empireteas.com could be used instead. Shyamin pointed out that empire.lk DNS is served by Cloudflare, so the records belong there, and that NIC.lk moving the domain back to its own name servers would drop the Cloudflare records Empire’s website and email depend on. Tharinda passed this on as a suggestion, with an offer of a call, and noted that empireteas.com would have meant re-registering the Entra reply URLs. Kavindu added the four NS records in Cloudflare the same afternoon, and the delegation resolved publicly. The facts are recorded in environments-and-identity.md §1.1.
The Active Context “Owed” bullet this closed, verbatim:
- The
crm.empire.lkdelegation (Tharinda to Kavindu Anthony, Shyamin Ayesh copied): four NS records namedcrmin theempire.lkzone — the drafted email is F38-a Appendix A.1; the only DNS request Empire IT gets (F38 Rev 2,environments-and-identity.md§1.1).
Active Context reconciliation — 2026-10-02
A check of tracker.yaml, features.md, Active Context, owed.md and the live harness documents against GitHub and the app repos, after F5-l’s Reflect and F5-k’s wave 2 merged.
- Critical path. F5-l is done, and F5-k’s wave 2 (the admin guards) merged on 2026-10-02, so the critical path to the list screens is F5-f alone, with no open blocker. F5-k is out of
blocked_byfor F5-c, F5-d and F38-d, since what each needed from it is onmain; F5-k’s wave 3, the E2E suite, remains. - Tracker corrections: F5-k’s wave 2
merged; F5-f, F5-l, F38, F38-a and F38-d notes; four done features’ follow-ups named with the PRs that landed them (F5-i, F5-j, F38-c, F11-a); the AWS account’s existence in thesetuprecords and R-ARCH-001; R-PRD-002 notes OQ-15’s reopening; BUG-022’s resolved date is its merge date.features.mdrows for F5-l, F41, F5-c, F5-d, F5-i, F5-k, F1-a, F38, F38-a, F38-c and F38-d brought in line. - Owed. The F5-j cookie item was done and is removed; the F38 and automated-deployment items no longer wait on the account.
The Active Context sentences this reconciliation replaced, verbatim:
The critical path is F5-l → F5-f: F5-f blocks every list screen (F1-b, F11-b); F5-l (AD #37) blocks F5-d, F5-e and F5-f and changes the frontend as well as the backend; F5-k’s wave 2 blocks F5-c (it adds the admin guards F5-c relies on) and F5-d.
(AD #37 — code change tracked as F5-l, after F5-k’s wave 1 and before F5-d, F5-e and F5-f)
The owed.md bullets this closed, verbatim. The F4-a handover item closes because Dinil, as F4-a’s owner, has confirmed the rule (confirmed to the lead, 2026-10-02); the code change it names moved from F4-d to F5-f by the lead’s decision of 2026-10-02 (F5-f makes both CrmChangeRule exclusions, the share codes and owner-only changes — tracker.yaml F5-f notes).
- The handover rule for the Pipedrive import (F4-a spec Rev 3, lead decision 2026-09-30): an owner-only change is not a CRM change. F4-d makes the code change before its first write run (F4-b waits for F4-d); Dinil, as F4-a’s owner, to confirm on the harness PR.
- The AD #33 cookie change — F5-j, done locally 2026-09-27 (Tharinda): the backend’s
XSRF-TOKENcookie takes a configurable domain and a per-environment name, and the frontend reads the name from build config. It is onmain, as F38’s first dev deploy needs; the per-environment values are proved on dev by F38 (register A-4).
Active Context reconciliation — 2026-10-04 (project audit)
The whole-project audit (.forge/audits/2026-10-04-project-audit.md) found Active Context’s critical-path sentence stale. As it stood:
The critical path is F5-f: it blocks every list screen (F1-b, F11-b) and the first dev deploy (F38-d), and it has no open blocker. F5-l is done (2026-10-02) and F5-k’s wave 2, the admin guards, merged on 2026-10-02, so F5-c and F5-d no longer wait on either; F5-k’s wave 3, the E2E suite, remains.
F5-k is done (2026-10-03) and F5-f is done (2026-10-04), so the sentence now names the cloud bring-up (F38-a → F38-b → F38-d) as the critical path.
2026-10-05 — the mobilisation-week agenda, moved from the team guide
The second project audit moved this section out of team-guide.md, which states only current practice. As it stood:
What the team confirms before kickoff (1 Sep). Each item names the artifact it lands in — an agreed item updates its artifact the same week:
- Ceremonies + communication channels — (done — agreed as proposed 2026-08-19, ahead of the week; day-to-day chat is the private
et-teamSlack channel). - Coding standards incl. the §7 quality toolchain — walk
.forge/design/coding-standards.mdend to end (its status header says “confirm before Foundation slice 1”; this is that conversation). §7 is the biggest piece: Spotless/Biome formatting, Error Prone + NullAway, ArchUnit boundary tests, coverage policy (report → gate at the phase boundary), commitlint, suppression discipline, and the §7.9 do-not-run list. §8 (logging: Micrometer trace propagation incl. async/SQS, levels, the deny-list) and §9 (Javadoc + Spock-spec documentation) ride the same walk. (Done — walked and confirmed as-is 2026-08-19, ahead of the week; the doc’s status header reads confirmed.) - DevOps/admin settings request — (Applied 2026-08-20 by the lead under a temporary admin grant, ahead of the week: rulesets on all four delivery repos per
git-conventions.md § Branch Protection; required CI checks —Repo hygieneon the harness, bootstrappedFast lane+Slow laneon the app repos (FS-1 fills the steps; never rename the jobs); merge commits only — squash and rebase merges disabled; auto-delete-on-merge enabled — revises the earlier keep-it-manual decision,release/*exempt via its deletion rule; Dependabot alerts + security updates; Actions token read-only + Actions barred from approving PRs. Secret-scanning push protection dropped — paid add-on, decided against; gitleaks in the fast lane is the layer instead (coding-standards.md §7.7). Grouped weekly Dependabot version updates land with the app repos’ manifests at FS-1 — needs only write access. Admin is revoked after this; any future required-check or ruleset change goes to the org admins.) - Slice 1’s non-cloud half starts — repos gain their skeletons per
architecture.md § Foundation Backlog; the cloud half waits on the AWS account (dependency-register row 1).
2026-10-08 — lines to Empire closed in owed.md
The lead closed these owed.md rows, or parts of rows, as already told to Empire. The drafts stay where they were written (engagement-gate-runs.md § Gate 3 Run 1; this log’s § AD #34, AD #35, AD #36 and § AD #37).
- The re-grouped releases — told in the progress update of 6 October (
client/weekly-updates/2026-10-06.md, its next steps). - The 2026-09-24 access-model changes — told in the same update (its items 3 and 4: users and roles, owners, sharing, the audit trail). The ask for the production administrator’s email, which was part of this row, was not in the update and stays owed under the Empire IT asks in
owed.md. - Background AI (the proposal’s 27 September post-issue note) — the lead confirmed Empire has been told that the system runs some AI work on its own while a person approves every AI output.
- The temporary UAT environments on Empire’s AWS bill — the lead confirmed Empire has been told each acceptance round needs one and knows what it costs. No UAT environment exists yet (F38-h builds the first). The rest of that row, who at Empire receives the AWS Budgets alerts and OQ-49’s “staging” wording, stays owed.
- Corrections to the SOW-ET-001 v1.1 Word document — the lead confirmed the SOW sent to Empire already carries them: Phase 2 UAT and stabilisation as weeks 15–17, the Phase 1 UAT date, the scope column as re-grouped at Gate 3, and the capture-app checkpoint. The Word document is kept outside this repo.
The lead also removed rows that another file already tracks, so that each item is tracked in one place:
- The
SearchProviderchoice, spike SP-ARCH-004 (Dinil) — tracked intracker.yaml’s SP-ARCH-004 entry, whoseblocked_onalso holds who holds the Tavily account and whose card pays if Tavily is chosen, and incloud-gated-validation.md’s “Start here” step 14. Stage 2 waits on Bedrock being set up in Empire’s account.
2026-10-09 — bulk email committed to Phase 2
Kavindu Anthony asked over WhatsApp whether the CRM will have email campaigns, listing newsletters with engagement tracking, product promotion, trade-fair invitations and follow-ups, contact grouping and campaign analytics. Dinil identified the request as F28, deferred since 2026-08-20. The lead replied that Phase 2 includes bulk email for these uses with opens and clicks per send, and that Phase 2’s features will be prioritised with Empire at or before the Phase 1 hand-over. F37, a stretch candidate since 2026-09-16, became F37-a (the weekly price broadcast) and F37-b (bulk email to a saved contact list, with a per-send summary) in Phase 2 — PRD Rev 57. Before the reply, every item promised for Phase 1 and Phase 2 was checked against an owning feature; the gaps found were F37 itself, the per-send summary, and saved contact lists as a send audience (F32-a, F34-b scopes widened). The newsletter questions (OQ-62) were drafted but not sent. Record: discovery/meeting-notes/2026-10-09-kavindu-bulk-email.md.
2026-10-11 — scope trims to fit Phase 2, and the GuardDuty line closed
The lead reviewed the open features against Phase 2’s build window (R-ARCH-001) and decided, in one working session:
- Dropped from V1: global search (F31, PRD Rev 60), AI similar past quotes (F7-e), the AI product-brief assistant (F16) and the price-lookup page (F26-e) — PRD Rev 61. Each is recorded as
droppedin Phase 1, where the decision was taken. The proposal carries post-issue notes for global search and the product-brief assistant, the two it names; the client documents were revised the same day (PRD Rev 62). - Merged back (no scope change): F15-b into F15-a, F17-b into F17-a and F18-b into F18-a — three of Gate 3’s borderline
◐splits, to save one spec, plan and review each. - Narrowed: F1-c drops the computed lifetime value, because V1 has no order data (OQ-63); the entered Est. LTV that F1-a ships stays. F38-b and F38-d become “check and close” items, because the DevOps team built most of the dev estate and the backend deploy before their specs were written.
- Kept, deliberately: the GuardDuty scanner adapter (F38-c) stays on
main, switched off by F38-j’s setting, so that enabling GuardDuty later is Terraform plus two settings. - The F38 tracker row was removed (F38 spec Rev 8); the spec stays as the requirements F38-a … F38-j narrow.
- Closed in
owed.md: “Tell Empire Teas that GuardDuty is off”. The lead decided Empire is not told separately; the proposal’s post-issue note of 9 October and the client-facing PRD (revised 9 October) already state it. If Empire asks for GuardDuty, F38 Rev 7 andarchitecture.mdRev 52 list what to restore. - Left for a later decision: four further Phase 2 candidates — F36-f (same-day follow-up email from the capture app, waiting on OQ-60), F23-c (creating custom fields during import), F22 (contact sync, named in the proposal) and F36-e (the capture app’s offline queue).
- Later the same day: F23-c and F36-f were dropped (PRD Rev 63; OQ-60 closed, client question Q15 withdrawn); F36-e was dropped and F36-a gained a keep-and-retry for failed uploads (PRD Rev 64); F22 stays in Phase 2. F38-b and F38-d gained item-by-item work lists. An independent consistency review then found places the day’s revisions had missed — chiefly that F26-f already shows each standard’s price history, so only the separate price-lookup page is dropped — corrected in PRD Rev 65.
- Later still: the five Pipedrive add-on equivalents, out of V1 since 2026-08-20 and listed as deferred, were dropped with no later phase planned (PRD Rev 66): F27 chatbot and live chat, F28 email campaigns, F29 data enrichment, F30 LinkedIn and F35 sales goals. Each gained a
droppedPhase 1 row intracker.yaml, so the dashboard lists every PRD feature; the proposal carries a fourth post-issue note of the day. F37 (bulk email) and the AI lead research are not affected. The same change made the dashboard’s pace rate count shipped features only. - Closed in
owed.md: “Decide whether to tell Empire that the Pipedrive add-on equivalents are dropped”. Decided the same day: Empire is not told separately about these add-ons or about any of the day’s drops; the proposal’s post-issue notes and the client-facing PRD record them.
2026-10-12 — R-ARCH-001 restated: Phase 1’s room goes to Phase 1 work first
A capacity re-run after the 11 October changes (pace measured from the tracker: 31 Phase 1 features done in 18 working days) gave Phase 1 about 14 to 26 features of room before its 20 Nov build target, and Phase 2 between about 14 features over and about 3 spare against 24 Dec, depending on the rate. The lead then set how Phase 1’s room is used: it is not Phase 2 capacity. It goes first to the remaining Phase 1 features, bug and UI fixes, the issues and improvements Empire Teas and Altrium stakeholders raise once the Phase 1 work is shown to them, thorough regression testing, the Phase 1 release work and the cloud work; Phase 2 features come into Phase 1’s duration only when all of that is done. The lead also noted what the figures leave out: personal leave (roughly 45 days left across the four developers, timing unknown), offset in part by the team’s work at nights, weekends and on public holidays. The restatement is in tracker.yaml (R-ARCH-001); the work-order rule is in team-guide.md § Working in Parallel — Four Developers.
2026-10-13 — two gate follow-ups of BUG-153 and BUG-179 closed in owed.md
- Closed: “Decide whether the browser gate checks that the CRM page itself never scrolls vertically”. Tharinda decided yes. forge-et-fe#243 makes the size matrix assert that every signed-in page state’s page is no taller than the window, from
bp/tabletup in both engines. The rule leaves out the 320 px zoom size and the signed-out screens. It sits outside the shared page check, because forge-et-pwa copies that check and its phone screens scroll the document. With BUG-153’s fix removed, the rule fails 71 page states at 1024 × 768. - Closed: “Clear forge-et-fe#235’s two gitleaks findings before it merges”. Tharinda chose an ignore file on
mainover changes to Dinil’s branches. forge-et-fe#241 adds.gitleaksignorewith the two exact fingerprints (testIdempotency-KeyUUIDs). The flagged commits are on five F20-c branches, and a file onmaincovers whichever of them ships. Dinil was told on #235. Each later change to the file is reviewed as a security change.
2026-10-14 — dev sign-in works; the lead’s decisions on the dev account
On 13 Oct Shyamin Ayesh put the Entra values into Secrets Manager, pointed the backend at them, and built the CRM frontend’s hosting and deploy, and CRM01 signed in on https://dev.crm.empire.lk (register A-5 closed). He also built the AgentCore Gateway, which Dinil used for SP-ARCH-004 stage 2: AgentCore came last and Exa first, and the lead leans towards Exa, pending Thilina’s approval and Empire’s, since Empire would pay for it outside AWS (owed.md). The lead then decided, for the dev account:
- The DevOps team’s direct pushes to app-repo
mainare accepted. Shyamin is a GitHub organisation administrator and will not route deploy files through PRs; the delivery team checks each such push after the fact (git-conventions.md§ Branch Protection). All seventeen pushed so far (fourteen toforge-et-befrom 5 Oct, three toforge-et-feon 13 Oct) were checked on 14 Oct: they change only the deploy files, no secret is in git, and the gaps in the current files are recorded inenvironments-and-identity.md§4 rows 9 and 15. - One administrator CI key and
svc-harness’s broad access are kept for dev (F38 Rev 9). Claude usessvc-harnessfor reads only and asks the lead before any change. Production follows FR-19 and NFR-1. - Shyamin raises the Bedrock quota increase. The 5.5 models’ agreements were accepted on 14 Oct, but both models still have a quota of 0 tokens a minute.
- Backups on the dev database: the lead thinks dev does not need them; the proposal promises 3 days in development, so it is an open question in
owed.md. - Database access for the team was asked for; the proposal and the laptop setup are
environments-and-identity.md§4 item 15 and.forge/guides/aws-setup-explained.md§5. - Later the same day:
- What dev costs. Shyamin shared a cost estimate. Measured, dev runs at about USD 62 a month, against the cost annexe’s USD 34 (
environments-and-identity.md§4 “What dev costs”). - No off-hours schedule while development is under way. The lead decided this because the team runs work against dev overnight (F38 Rev 10, plus a post-issue note on the proposal, whose §A.2.1 promised the schedule). After development, dev is scaled down, scheduled off or decommissioned. The annexe is to be re-derived (
owed.md). - BUG-136. The frontend deploy’s missing cache headers were filed as a bug.
- AWS non-read calls need asking. Claude must ask before any AWS call that is not a read, a single model test call included (
.claude/CLAUDE.md§ ASK FIRST), after a test call made without asking that day. - Optional in dev, required in production. Database backups, and MFA on
svc-harness’s console password, are optional in dev and left to the DevOps team, without pushing them. Production keeps both. Recorded in F38 Rev 11 and a post-issue note on the proposal. - CLI access in dev stays on access keys. The team uses
svc-harness’s key through theet-devprofile, shared through the password vault. There are no personal Identity Center logins for dev. This was Shyamin’s suggestion whenaws loginfailed on 13 Oct, and he asked that no more IAM users be created. Production keeps personal logins with MFA (environments-and-identity.md§4 item 8). - Database access is not urgent. It is set up only when a real need comes, and the chosen way costs nothing: a Session Manager tunnel through the running backend (ECS Exec), with a read-only login for people. This replaces the earlier proposal of a USD 7-a-month access host. Production gets break-glass access only (
environments-and-identity.md§4 item 15; F38-i Open Questions;.forge/guides/aws-setup-explained.md§5).
- What dev costs. Shyamin shared a cost estimate. Measured, dev runs at about USD 62 a month, against the cost annexe’s USD 34 (
2026-10-16 — two F20-h rows closed in owed.md by its WI-2.1 run
- Closed: “Create the missing
crm03@empire.lkMicrosoft 365 mailbox”. During F20-h’s WI-2.1 on 2026-10-16, CRM03 signed in to Outlook on the web and received send 3, so the mailbox now exists, asenvironments-and-identity.md§5 already says. - Closed: “Correct F20-h’s WI-2.1 run sheet before it is run”. The sheet was run without the revision, and the record applied both corrections as deviations. R-12 names the secret check’s pattern by reference (L-192’s update). Every test account was signed in before the step that used it, and each one worked.
2026-10-16 — owed.md second prune, and the DevOps cards on Trello
Each owed.md row was re-checked against its source on 16 Oct: the code, the PR states, the dev AWS account (read-only, as svc-harness) and forge-et-iaac’s log. The rule for removing a row changed during the pass (the lead, 16 Oct): a row is removed only when its work is done and checked, or when the lead marks it won’t-do or asks for it to go — not because another file also tracks it. That reverses the 2026-10-08 practice of removing rows that another file tracks. The pass first removed such rows, then restored every one that was still open; the rule is now in owed.md’s header.
-
Removed, because done:
- Putting the DevOps asks on Trello, which the lead did on 16 Oct.
- The GuardDuty part of the account-structure “on hold” row, settled on 9 Oct (both off, Altrium management) and 11 Oct (Empire Teas not told separately, the lead). The row’s production account and sign-in part is kept.
- Item (1) of F12’s framework follow-ups: Active Context’s provider-seams sentence now says
AIProviderexists (forge-et-be#229, checked onmain). The row’s other three items are kept.
-
Moved to a bug: LoginRoute’s service-unavailable notice has no trace id, so it was filed as BUG-212. The other screen in that row, the role editor’s failed Reload, was fixed by BUG-091.
-
Merged:
- The two
InertWhileOpenrows: three copies are now onforge-et-femain. - The F20-c converted-lead re-run and the offboarding test: both are added when F11-h and F11-e ship.
- The Pipedrive questions, the template question and the deals export.
- The search-provider choice and the removal of
spike-invoke-gateway.
- The two
-
Shortened, with nothing open lost:
- The AI commitments row leads with the AI switch and monthly ceiling, which still need a Phase 2 owner; the extraction stays as a closing sentence.
- The 9 Oct test-failure row notes that BUG-110’s fix (forge-et-fe#184) merged after those runs and that the
RowSelectiontimeouts are BUG-128; both sub-items stay until a run confirms them.
-
Refreshed to 16 Oct’s facts:
- the frontend audit row (
useMediaQueryis now inforge-et-fe; three hand-made stores remain); - the contract renumbering (F1-f’s revisions are on
main, so F1-e renumbers); - the F1-c revision (its spec merged as forge-et-harness#646 without the F3-a rows);
- the F11-h owner (Dinil, spec and plan open);
- the merged forge-et-fe#201;
- the F4-d migration list.
- the frontend audit row (
-
The DevOps cards (the lead, 16 Oct):
- Three Trello cards:
- “[ET] Misc tasks”, twelve items listed for reference, not as a commitment to do them all. Some may not be needed and will be skipped; which are needed, and in what order, is reviewed as the work goes on, mostly after the other cards.
- “[ET] et-iaac repo fixes”: the broken rotation line and the commented-out apply step.
- “[ET] Consider dropping DB password rotation”: the lead’s question.
- Shyamin has done none of them yet. Read as
svc-harnessand inforge-et-iaacat76fce06: nothing has changed since 15 Oct (no SES identity, no customer KMS key, no attachments bucket, no mailbox queues, schedules, trail, budget or alarms; the task definition’s placeholders unchanged). He may take them up the week of 19 Oct. - Bedrock: AWS’s replies to the six closed quota cases never reached Shyamin, because no email address was set up for them. He has set one up and will resubmit the requests.
- SES: Shyamin goes ahead with
noreply@dev.crm.empire.lkandnoreply@crm.empire.lk.mail.crm.empire.lkhad been shared only as an example. - Rows: the carded work has rows in
owed.md, kept until done or marked won’t-do:- the
forge-et-iaacand rotation fixes; - the dev database fixes, with the values sent on 2 Oct;
- the rest of the dev estate and the capture app’s hosting;
- the other “[ET] Misc tasks” items;
- the Bedrock quotas;
- SES in dev, which had no row though it has been on Trello since 14 Oct;
- production’s account and sign-in.
- the
- These are recorded in
environments-and-identity.md§4.
- Three Trello cards:
-
The database password is not rotated on a schedule (the lead, 16 Oct; planned, not yet applied). The lead chose option 1 of three: no scheduled rotation in any environment. RDS keeps managing the password. Its automatic rotation is set in Terraform, in the shared module, to the longest interval (or off). No restart is built. The password is changed by hand with a redeploy when a leak is suspected or someone who could read it leaves. The options not chosen were reading the password at connect time, and restarting the backend after each rotation.
The rotation promise came from the issued proposal (§A.2.3 “secrets held in AWS Secrets Manager with rotation”; §A.4’s Secrets Manager row “database credentials, with rotation”), so a post-issue note records the departure.
The decision is recorded in F38 Rev 14 (which answers OQ-K) and
architecture.mdRev 61. It also changes register §C-3,environments-and-identity.md§4 item 1 and row 1,.forge/guides/aws-setup-explained.md§7 (with the runbook for a change by hand), the F38-b and F38-i drafts, Active Context’s open risks and theowed.mdrow. Shyamin Ayesh applies it through the two rotation cards.
2026-10-17 — a plan for system and non-functional testing before each UAT round
The lead asked for every function to be tested thoroughly and for the non-functional areas to be checked: performance, load, stress and security. A review of .forge/test-strategy.md against the PRD’s non-functional requirements and the issued proposal found the following:
- What exists. Feature-level testing is thorough: every acceptance criterion maps to a test, the always-test list covers access, audit and the AI rules, the browser gate runs every page at every supported size with an accessibility scan, and every security-sensitive PR gets a security review. The performance targets are written down, with a measuring method.
- What was missing. Nothing stated how the assembled product, the deployed environment and the non-functional requirements are checked before each UAT round. In addition:
- Phase 1’s round, 30 Nov – 10 Dec, falls outside the release lifecycle, which is written for the period after the last phase seals.
- No threat model exists.
- No check of the deployed system’s headers was planned, and the CRM sends no HSTS or Content-Security-Policy header (the capture app has no hosting yet).
- The restore rehearsal the proposal promises (§A.5) is planned only for production.
- What was added (
test-strategy.mdRev 22): § System Verification to V1 Sign-off, with seven functional steps before each round and a matrix of every non-functional requirement with its method, environment, owner and state. Load and stress were assessed against the PRD’s scale of 10–20 users: no standing suite, and a one-off concurrency check per round is proposed. No separate stress test is proposed either, because the heavy work (the mailbox scan, the AI batch triage, the imports) is checked at volume in its own rows. Both are for the lead to decide. A second reviewer then checked every claim against its source, and its corrections were applied. They added: a row for the proposal’s infrastructure controls (§A.4); readings from the offices’ locations, since every API call goes tous-east-1; and real-device checks of the capture app in Phase 2. - Also changed: a line in the phase-boundary checklist, and the Reference Map row in
.claude/CLAUDE.md. - For the lead (
owed.md): who runs Phase 1’s verification and when; how Phase 1’s round is modelled in the release track; the proposed checks (concurrency check, threat model, ZAP scan, a timed restore on dev, a screen-reader pass); and the security headers. - Corrected on the way: F38’s Phase 1 UAT dates (Rev 15), the review-gate row’s missing owner, and the F38-a WI-2.1 plan’s pointer to a renamed
owed.mdrow.
2026-10-21 — the backend health check is applied on dev
- Closed in
owed.md: “Shorten the backend target group’s health check”. forge-et-iaac#3 merged on 2026-10-20 (d230b133) with commita359b61, and itsdev.yamlrun 39475850266 applied it. Read on 2026-10-21 withaws elbv2 describe-target-groups --names et-dev-backend: a 10 s interval, a 5 s timeout, two healthy and three unhealthy checks on/actuator/health/liveness. A new backend task now takes traffic about 20 s after it answers, instead of about 2.5 minutes (F38-d spec Rev 3).
2026-10-21 — forge-et-iaac#3 merged and applied; the harness brought up to date
- What happened. Shyamin Ayesh approved the delivery team’s forge-et-iaac#3 (F38-b wave 1) at 11:06 UTC on 2026-10-20 and Dinil’s forge-et-iaac#4 (F11-d’s lead-triage queue, stacked on #3) at 11:01 UTC. The lead then merged #4 into #3’s branch (
59b43d2, 18:32 UTC) and #3 intodev(d230b133, 18:33 UTC; 00:03 on 21 Oct in Sri Lanka), so both reacheddevtogether. #3’s last commit,a359b61(the faster health check), was pushed after Shyamin’s approval, at 13:44 UTC, and the PR says so. The merge’sdev.yamlrun 39475850266 succeeded, itsterraform::applystep included: “Apply complete! Resources: 28 added, 5 changed, 1 destroyed” (the one destroyed is the ECR lifecycle policy, replaced).dev.yamlnow runs only on a push todevor by hand and applies only ondev. - Checked in the account on 2026-10-21 (read-only, profile
et-dev): the RDS-managed secret showsRotationEnabled: falseand no next rotation date; the KMS aliaseset-dev-storageandet-dev-mailbox-token; the bucketet-dev-attachments(storage-key encryption, all public access blocked, versioning on); the queueset-dev-mailbox-ingestandet-dev-lead-triagewith their dead-letter queues, every dead-letter queue keeping 14 days; five enabled schedules in the groupet-dev; the task role’ss3,kms,bedrock,sqsandsqs-sendpolicies; the CRM distribution’s response-headers policy (four headers on/and/leads, no CSP); the ECR rule keeping 100build-*images; the service in one subnet inus-east-1b, the database’s zone; and the faster health check. The backend’s task definition still holds the bucket, mailbox URL and token-key placeholders (F38-b wave 4). - Closed in
owed.md: “Stop rotating the database password on a schedule, and fixforge-et-iaac” (its “done when” — #3 merged, the post-merge run applied,RotationEnabled: false— is met), and “When forge-et-iaac#3 merges, update the harness’s description ofdev.yaml” (this change). Updated, not closed: the rest of the dev estate (the task-definition values and the capture app’s hosting are left), the Content-Security-Policy, the F11-h model override and the “Keep the harness in step” reconcile point. - Rewritten as current fact:
.claude/rules/forge-et-iaac.mdandgit-conventions.md § forge-et-iaac(no[skip ci]needed on a review branch cut after the merge),environments-and-identity.md§4 and §5, the register’s “Start here”, A-2, A-5 and the rows that waited on the apply, Active Context,architecture.md, the AWS setup guide,test-strategy.md,et-repo-cleanup, and the status lines of the F38, F38-b, F38-d and F38-g specs; the tracker records F38-b wave 1 as merged. F38-b’s WI-2.1 still records the applied resources in its evidence section, and its plan’s## Notessays what this change already did. - Decided by the lead, 2026-10-21: who merges a
forge-et-iaacPR. A PR merges only after Shyamin Ayesh has approved it, and after his approval anyone with write access may merge it, with a merge commit. Before this the rule said the DevOps team merges; the lead merged #3 and #4 after Shyamin’s approval. Recorded in.claude/rules/forge-et-iaac.md, theprotected-paths.shcomment,environments-and-identity.md§4 (“The delivery team’s side”), the F38-b spec’s Context and a note in the F38-d WI-3.1 plan.
2026-10-21 — a table’s first column is pinned from bp/tablet up only (BUG-232)
- Decided by the lead, 2026-10-21: the CRM keeps its 320px reflow (WCAG 2.1 SC 1.4.10, which the PRD’s AA target needs for zoom), and a table’s first column is pinned only from
bp/tabletup, across every table — not a redesign of the row actions belowbp/tablet, and not a narrower rail. Recorded as design-system §9 Rev 68 and BUG-232’sDecision:line; built by forge-et-fe#320. - Closed in
owed.md: “A keyboard-focused row action can scroll under a table’s sticky first column at 320px” (raised by F1-f-WI-1.5’s browser runs, 2026-10-15). Its question was whether §9 adds ascroll-padding-inline-start; with nothing pinned belowbp/tablet, no control can sit under a pinned column at 320px, so the question no longer applies.scroll-paddingalone would not have been enough: it keeps a control scrolled into view beside the pinned column, but not the end of the scroll (BUG-232’sCauseline).
2026-10-21 — the CRM’s screens restructured, decided at an internal demo
- Decided at the internal demo, 2026-10-21, by Tharinda, Nanndish, Dinil, Biseni and the UI/UX engineer, and approved by the lead: every CRM list screen except Email becomes a table like the Users list, each row ending with a ⋯ menu of View, Edit and one action specific to the screen, and the whole row, not only the name, opening the record in view mode; every record page (account, contact, lead) becomes one centred column like the user editor, opening in view mode with its own Edit action, while the menu’s Edit opens it in edit mode; Users and Roles leave the sidebar for the Settings page, each Settings item keeping its own permission; every create flow opens in a modal like the create-user dialog, so the account’s New page becomes one; every form field’s placeholder becomes Enter and the field’s name (Enter company name), with no example values, reversing §5’s format-examples rule; the email templates move from the Email page to Settings; Settings becomes a page of links, each opening its own page; and the sidebar puts Leads first and Pricing before Email, which also makes Leads the landing page for a role that reaches it. Recorded as design-system §5, §6 and §8 Rev 70 and
shadcn-backfill.md § Target layouts. The work goes in this order: the Leads list as a table first, then the lead page, then the other screens one PR each. - Superseded before merging: the Leads list’s two-pane layout on shadcn (forge-et-fe#303, a draft; forge-et-harness#783, its backfill row and design-system Rev 67) and the tabbed lead detail built on it in the same week (branch
feature/shadcn-lead-detail, Option B of the three layouts shown to the UI/UX engineer). Both are kept for comparison with the table; the lead page is designed afresh. - Opened in
owed.md: the rest of the demo’s decisions to record, each list screen’s third row action, the approved specs to revise (F11-b, F11-f, F20-d, F1-e, F1-b, F1-d, F1-f, F26-b, F5-b, F5-c, F5-d), telling Empire, and reconciling the parked two-pane work.
2026-10-25 — every forge-et-iaac PR merged and applied; the capture app’s GitHub Environment complete
- What happened. Shyamin Ayesh approved forge-et-iaac#6 (F38-d wave 3: immutable ECR tags, a 30 s deregistration delay), #7 (F38-e wave 1: the alert topic and the failed-deploy rule) and #8 (F11-c: the lead-research queue and the Exa key’s secret) at 09:59–10:00 UTC on 2026-10-23. Dinil merged #8 at 10:07 UTC and the lead merged #6 and #7 at 10:41 UTC, each with a merge commit; each
dev.yamlrun applied only what its PR named. Shyamin also added the deploy key’s two secrets toforge-et-pwa’sdevEnvironment at 11:49 UTC. When he approved the three PRs he asked for every Secrets Manager secret to sit in one shared module (.claude/rules/forge-et-iaac.md;owed.md“Fold the Secrets Manager modules into one”). - Checked in the account on 2026-10-25 (read-only, profile
et-dev, no secret value read): what each PR created; the runningbackend:62with forge-et-be#300’s bucket and mailbox values; every Secrets Manager secret with anAWSCURRENTversion; the schedules’ 173 messages of 24 Oct all consumed; the Bedrock quotas unchanged. Recorded inenvironments-and-identity.md§4 and the register’s 2026-10-25 “Start here” update (harness #902), and the wave records (#900, #894). - Closed in
owed.md: “Plan and write F38-b wave 5 — the capture app’s dev hosting” (its “the row goes when the Environment exists” is met: forge-et-iaac#5 applied on 22 Oct, andforge-et-pwa’sdevEnvironment holds bothVITE_*variables and both key secrets). The capture app’s deploy workflow is F38-d wave 5, in the tracker.
2026-10-25 — F38-b AC-1’s state search replaced by a code check
- Decided by the lead, 2026-10-25: the DevOps team’s search of the
et-opsstate for the database and Entra secrets’ values is not needed. The request to Shyamin Ayesh (a “found” or “none found” comment on forge-et-iaac#5, asked on 23 Oct) went unanswered. The state cannot hold the values: onforge-et-iaacdevat1590009no resource writes one, every secret is an empty container filled by hand, and RDS manages the database password. F38-b spec Rev 12 replaces the search in AC-1 with that code check, and WI-4.1 plan Rev 2 records it. - Found while checking: from 5 to 9 Oct the state did hold a database password. The first RDS commit (
87bac05) generated one withrandom_passwordand stored it in the secretdev/rds/password, untilac1efdcmoved the password to RDS. RDS’s own secret dates from 9 Oct 14:02 Colombo time, anddev/rds/passwordwas scheduled for deletion at 14:07. Older versions of the state file may still hold that first password, but it no longer opens the database. - Closed in
owed.md: “Agree where the DevOps team posts F38-b AC-1’s state search”.
2026-10-26 — the capture app deploys on dev; the dev-estate row closed
- What happened. F38-d’s waves 4 and 5 merged on 25 Oct (harness #889 and the wave 5 PRs). forge-et-be#306 set
ET_DATASOURCE_SSL_MODE=verify-full, and dev now runsbackend:65, registered at 20:04 UTC.forge-et-pwa’s newbuild.yaml(f7d6b3f) deployed the capture app by hand (run 40224118047, 19:02 UTC) and on a push tomain(run 40228839882, 20:02 UTC).https://capture.dev.crm.empire.lk/answers200. The DevOps team’s Trello board, as exported on 25 Oct (last activity 19:55 UTC), has the cards for forge-et-iaac#6, #8 and the capture app in Done. It also has two new cards: “[ET] Alert topic and failed-deploy email on dev (forge-et-iaac#7)” in Done, and “[ET] One Secrets Manager module (base/secrets)” in In Review for forge-et-iaac#9. The UAT card is on hold until Empire answers (theowed.mdrow “Empire decides whether Phase 1’s UAT round gets its own temporary environment”). - Closed in
owed.md: “The rest of the dev estate and the capture app’s hosting” (Shyamin Ayesh, with the delivery team’s PRs). Everything it listed is done:- the KMS keys, bucket, queues, scheduler and grants (forge-et-iaac#3, 20 Oct);
- the task-definition values (forge-et-be#300, 22 Oct);
- the capture app’s hosting (forge-et-iaac#5, 22 Oct);
forge-et-pwa’sdevEnvironment and key (23 Oct);- its deploy workflow (25 Oct).
- What stays open, in its own homes: proving uploads and the mailbox by use (register §B F38-g
FR-6/bucketandFR-6/mailbox, F38-f), and recording the capture deploy (F38-d WI-7.1, the tracker).
2026-10-26 — one Secrets Manager module on dev; F38-b AC-13 ticked
- What happened. forge-et-iaac#9 (F38-b wave 6) merged as
c728e06bon Shyamin Ayesh’s approval.dev.yamlrun 40271292253 moved the five secrets intobase/secretswith nothing added or destroyed (0 to add, 5 to change, 0 to destroy), and each kept its ARN and value. No plan of the branch was read before the merge; the lead merged on the approval and a reading of the code. The lead then asked for a manual backend deploy to prove the next deploy:forge-et-bebuildrun 40274424861 onmainredeployed the image ECR already held and rolled outbackend:67healthy. - Closed in
owed.md: “Fold the Secrets Manager modules into one” (Tharinda; Shyamin Ayesh’s request of 25 Oct). A new secret is now a key inbase/secrets’s list (.claude/rules/forge-et-iaac.md). - Also shown by the same deploy, for F38-d WI-6.1 (AC-2): a manual run on
maindeploys without a new commit, and a run whose commit ECR already holds skips the image build and push and deploys that image’s digest. Recorded in §4 and the register’s one-image-per-commit row; WI-6.1 still owns its other AC-2 items.
2026-10-26 — F38-b’s dev estate recorded (wave 4)
- What happened. F38-b wave 4 (WI-4.1, run in the lead’s session; forge-et-harness#934) recorded the network, the database and both frontends’ hosting in
environments-and-identity.md§4 “F38-b — the dev estate, checked”: AC-2, AC-3 and AC-7 met, the capture app’s half included. AC-1 is met except its no-changedev.yamlplan, which no run has shown yet. The sweep found nothing outside Terraform. - The start condition. The DevOps team made no written report that it had finished; the lead took the Trello board of 25 Oct, with every dev card done and the database fixes optional, and the absence of any DevOps push since
0eee623as the DevOps team making no further optional dev changes. - Opened in
owed.md: “Record F38-b AC-1’s no-changedev.yamlrun”. - Later the same morning: at the lead’s request Claude started
dev.yamlonforge-et-iaacdev(run 40278225094, 06:10 UTC, atc728e06b). Its plan printedNo changes.and its apply changed nothing, so AC-1 is ticked, register A-2 closes, and thatowed.mdrow is closed. F38-b’s acceptance criteria now wait only on wave 3’s close-out (AC-4, AC-5, AC-12 and the closing sweep, AC-10). - Wave 3 closed the same day. Nanndish Satgunarajah ran the write checks on 23 Oct and recorded them (R-0 to R-9), but the wave was never closed. The lead confirmed in session that he ran and recorded every step, so the lead’s session closed it:
mainmerged intofeature/F38-b-wave-3, AC-4, AC-5 and AC-12 ticked, and the closing sweep recorded (AC-10). Every F38-b acceptance criterion is ticked; F38-b goes to Reflect next. The merge also restored a line break that forge-et-harness#935 had removed, which had put AC-2 on AC-1’s line in the spec. - F38-b closed, and its two framework follow-ups made. Reflect (forge-et-harness#942) set F38-b to
doneand promoted L-232 and L-233. The follow-up PR then made both framework changes the lead chose at Reflect:check-done-acs.pyfails on a criterion joined onto the line before it (with a self-test, and the rule in.claude/rules/specs.md), and/forge-deliverM1 adds anowed.mdrow naming the person who runs a manual wave, which M3 removes, while the hand-off block tells them to re-run/forge-deliverstraight after pushing the record. Closed inowed.md: “F38-b Reflect: framework follow-ups”.
2026-10-26 — the test-run cost design: Drafts 1 to 4
- What was asked (Nanndish, 2026-10-25). The three app repos’ test runs take too long, use too much of the machine, fail more often on Windows, and stop developers working in parallel. Make them faster and lighter in the backend and both frontends, using measured run times, the bug record and how long work takes because of the runs. Find out whether anyone is told when a nightly run fails, and set up a way to be told.
- What was written.
.forge/design/harness/test-run-cost.md, Drafts 1 to 3 (forge-et-harness#904) and Draft 4 (#931). It measures where each suite spends its time and proposes changes in nine tracks and three phases, with § Open questions Q-1 to Q-11 for the lead. Two fresh-context reviews checked it: one on Draft 1, and one on Drafts 3 and 4, which recounted every figure. All their findings are applied. - What it found (figures as of 2026-10-25 and 2026-10-26, in the design’s § Evidence):
- The CRM browser gate takes about 50 minutes on an 8-core Mac and hours on Windows, and 68% of it is the size matrix.
- 3.9% of the backend’s tests take 68% of its test time.
- Only the person who last edited a nightly schedule line hears of a failure (E-7).
- Draft 1 counted bug titles only. Draft 4 read every flaky, intermittent and Windows bug, open and closed (E-10):
- 47 flaky bugs. 16 of the 20 still open are on Windows, and WebKit is behind most of the oldest. They make up about 40% of the bugs filed in the last two weeks.
- The fixed ones were mostly races in the tests that load exposed.
- One product defect was first seen as a flaky test (BUG-261).
- One closure as machine overload came back ten days later (BUG-195 → BUG-259).
- The Windows bugs that are not flaky were tooling written for macOS, machine limits, and one real layout defect (BUG-246).
- Lesson L-231 records the title-count mistake.
- Still open. The lead’s answers, in the
owed.mdrow “Review and decide the test-run cost design”. The design’s § Where this stands, and the next steps says how to continue. Nothing is built until it is approved.
2026-10-26 — open items re-audited against the latest state
- What was done. At the lead’s request, every open item was checked again against the five repos (
origin/main;origin/devforforge-et-iaac) and the dev account (read calls assvc-harness), after the documentation review of the same day (forge-et-harness#936) had merged. The 17 Oct open-items report this replaces is stale. - Closed in
owed.md: “Clean up F26-d’s merged branches and worktrees” — no F26-d branch on any remote or local checkout, noworktrees/F26-d, and the spec PR #742 and plan PR #749 merged on 17 Oct; and BUG-128’s bullet in the 2026-10-09 test-failure row (fixed by forge-et-fe#229). #936 had already closed the BUG-217 shared-fix, top-bar search and comment-pointerD-<n>rows. - Read on dev: the Bedrock quotas are unchanged (Haiku 4.5 at 10 requests a minute on both quotas; Sonnet 5.5 and Haiku 5.5 at 0; no request after 21 Oct); the RDS-managed secret’s rotation is off (
RotationEnabled: false); SES has production access; the CRM and the capture app both send HSTS,X-Content-Type-Options,X-Frame-Optionsand a referrer policy, and neither sends a Content-Security-Policy. - Later the same day, the lead removed the
owed.mdrow “The dev database fixes” (forge-et-harness#938 had left it for this decision): none of the optional dev changes was made, and the DevOps team makes no more there (F38-b wave 4). As found on dev:db.t3.micro, gp2 20 GiB, public subnets, 5432 open to the VPC, deletion protection off, no final snapshot, backup retention 0, not encrypted,rds.force_ssl1(environments-and-identity.md§4 “F38-b — the dev estate, checked”). Nothing it carried is lost, because each production half has a home:- private subnets, port 5432 open only to the backend, gp3 with autoscaling, and deletion protection with a final snapshot are in the F38-i spec (“What dev leaves out and production requires”);
- the database alarms are in the
owed.mdrow “Decide the UAT and production alarm sets”; - encryption at rest is in the row “Decide whether production’s database is encrypted at rest”;
- 14-day backups and the production instance class are in the row “The other ‘[ET] Misc tasks’ items” and
environments-and-identity.md§4.
2026-10-26 — AWS keeps Bedrock at new-account limits
- What happened. AWS Support answered the lead’s reply of 22 Oct, which had asked for smaller quotas, with no increase, and resolved the case. Its reason: Sonnet 5.5, Haiku 4.5, the other 5.5 models and several newer models need a consistent usage and spend history on the account over a few billing cycles, and a new account has lower requests-per-minute quotas than Service Quotas shows. AWS reviews the account automatically and lifts the limits when usage and spend are enough. Two more Service Quotas requests filed by Shyamin Ayesh the same day (Opus 5.5’s and Sonnet 5.5’s cross-Region tokens a minute) closed unchanged within 16 minutes.
- Where it stands. Dev keeps Sonnet 5.5 and Haiku 5.5 at 0 and Haiku 4.5 at 10 requests a minute, with no date for a change, probably past Phase 1 UAT. F38-a WI-2.1 and every register item that waits for a raised quota have no date. Dev already runs lead research, email drafts and the account briefing on Haiku 4.5 by configuration.
- Recorded in:
environments-and-identity.md§4 item 4 and AC-4; the register’s §C-5; the two quota rows inowed.md, and a new row, “The AI layer under Bedrock’s new-account limits”. - The lead’s decisions, the same day (
ai-provider-strategy.md§5 row 10): Haiku 4.5 runs every AI feature in every environment until AWS lifts the limits, set by each feature’s model key in the task definition; the backend paces its Bedrock calls to stay under the requests-per-minute quota; no escalation through Empire Teas, who the lead does not expect to have an AWS account contact, but Empire Teas is told of the answer; and the production account’s date (the lead expects the end of November or December) is decided by Shyamin Ayesh, Malinda Wellalage, Thilina Abeyrathna, Rukshan Salgado and Empire Teas. Left to do, in theowed.mdrow: build the pacing (the lead: keep it there and take it up later), tell Empire Teas, give production the Haiku 4.5 overrides, decide how F38-a closes now that its AC-4 has no date, and re-read the quotas weekly. - The lead’s approach for the rest of the engagement, the same day (
ai-provider-strategy.md§4d): no Phase 1 feature waits on the 5.5 models; the code is made ready so a switch is a configuration change (BUG-248, Haiku 5.5’s price row and handling, the task role’s grant); the team checks the quotas weekly, because AWS does not promise to say when it lifts the limits; and each feature is tested on a new model before it moves, with Dinil’s Haiku-only evaluation (model-choice-evaluation-plan.md) setting which model each feature ends on. - Stated to Empire Teas’ records: because proposal §A.3.2 puts the writing and synthesis actions on Sonnet, the interim model is a post-issue note of 26 Oct on the proposal header (L-001), and
client/dependencies.md’s Bedrock row carries a dated note. The design records that said “dev overrides to Haiku 4.5” now say every environment (ai-provider-strategy.md§2, the register’s §D rows,architecture.md,guides/tech-stack-reference.md). AWS’s suggestion to use other Bedrock models to build spend is not taken without the lead (AD #19; the spend is Empire Teas’). - Later the same day, the lead decided that the 5.5 models hold no feature open, and that everything they still owe is tracked in one place. F38-a spec Rev 4 and parent F38 Rev 29 moved F38-a’s two model calls (its AC-4, wave 2) to a new register §C-5 row, as F38 Rev 25 had done for F38-f’s Sonnet 5.5 call; wave 2 left the tracker, and F38-a goes to its close.
ai-provider-strategy.md§4d gains a table of every AI feature’s design model, the model it runs on now, what must happen before it moves and the evidence that decides the move, with a list of every register row, bug and plan that waits on the 5.5 models. The lead also declined running the model comparison on Anthropic’s API (no per-token account, for cost), and asked that BUG-248 and the two Haiku 5.5 readiness rows be tracked and done when the team takes them up.
2026-10-26 — F38’s in-progress state checkpointed to main
- What happened. Four F38 harness branches held state that
maindid not show:feature/F38-e-wave-3at41e1a599(wave 3’s run sheets approved and handed to Tharinda),feature/F38-f-wave-2at1c307cfd(wave 2 handed to Tharinda),feature/F38-g-wave-4at21503b5d(wave 4 handed to Biseni, WI-4.1’s record started) andfeature/F38-h-wave-1at0af96c4a(the lead’s decision to build waves 1, 3 and 4 as code before Empire’s answer, forge-et-iaac#11, and wave 3’s plan). They were merged intomainthrough the copy branchchore/F38-checkpoint-2026-10-26, somainreads each feature’s current state. The four branches were not changed and stay live: each wave still closes through its own wave PR. - Conflicts resolved.
.forge/metrics/events.jsonlkept every line from both sides;.forge/engagement-gate-runs.mdkept both entries at each conflict; F38-g’s trackernoteskept main’s 25 Oct reconciliation entry inside the branch’s newer notes;.forge/owed.md’sforge-et-iaacroute row took the branch’s F38-h wave 3 update onto main’s newer text. - Why. Until a wave PR merged,
mainshowed an older state of every F38 feature, which misled a reading of what was left to do. A standing rule for these checkpoints goes to the framework PR that carries the F38 Reflect follow-ups in.forge/owed.md.
2026-10-27 — the test-run cost design: the lead’s answers (Draft 5)
- Why now. The developers on Windows (Nanndish, Biseni) reported that a full browser gate takes hours there, two gates on one machine fail each other, and PRs wait in a queue overnight for their gates; Dinil added that fewer workers are needed on Windows to finish at all. The lead asked for a plan that saves the team’s time without lowering what is checked.
- What the lead decided (2026-10-26 and 2026-10-27; each answer in the design’s § Open questions):
- The full run of all three app repos moves to a scheduled job on the lead’s Mac at 02:00 Sri Lanka time, which raises a failure as an issue assigned to the team. No spare machine exists for a self-hosted runner; a cloud machine and GitHub-hosted runners were offered and not chosen. CI’s scheduled run keeps only its
Fast lane, for AD #38’s nightly Trivy scan. - A PR runs less, because the night runs everything: four sizes per PR gate, Chromium only on Windows, one retry reported as flaky (more than 5 fail the run), no new gate for a unit-test-only change, heavy runs on one machine queue, and the timing tests and coverage only in the nightly and CI runs.
- Selected records and gates on PRs follow once the nightly run has run for two weeks. The Test record stays.
- Not adopted: WSL 2 for Windows runs, dropping the Test record, and ego(lite), an AI-agent browser a teammate suggested (it is not a test runner).
- The full run of all three app repos moves to a scheduled job on the lead’s Mac at 02:00 Sri Lanka time, which raises a failure as an issue assigned to the team. No spare machine exists for a self-hosted runner; a cloud machine and GitHub-hosted runners were offered and not chosen. CI’s scheduled run keeps only its
- Where it stands. Draft 5 records the answers; the build is the
owed.mdrow “Build Phase 1 of the test-run cost design”.
2026-10-27 — the test-run cost design: the first build
- Built and merged.
- The CRM’s PR profile, the gate’s counted retry and the unit-test exclusion: forge-et-fe#346 and forge-et-pwa#97, with the hook and rules in forge-et-harness#978 (PRD Rev 80).
- The nightly full run of the three app repos: forge-et-harness#979.
- The backend’s in-memory test database, and the timing tests and coverage moved to full-suite builds: forge-et-be#317.
- Every PR had a fresh-context review, and its findings were fixed before merge.
- Measured (the design’s § Measurements):
- The CRM’s PR-profile gate ran 4,004 tests in 33.7 minutes on an 8-core Mac and passed at its first attempt, against 48–51 minutes for the full gate before.
- The backend build record ran 10,335 tests in 18 min 55 s, against a 21-minute median before.
- Found on the way. The trial nightly run caught a load-sensitive test on
forge-et-pwamain(sharedDrift.test.tsran the real load check), fixed in forge-et-pwa#97. Two harness reviews hardened the nightly job: its lock, its cleanup under launchd, and its reporting. - Then. The first full nightly run, the LaunchAgent on the lead’s Mac, and the workflow PRs that switch off CI’s scheduled
Slow lane(forge-et-fe#347, forge-et-be#318, forge-et-pwa#98), merged after that run with the rule changes in the same harness PR.
2026-10-27 — F3-a wave 1 merged
- Merged on 2026-10-27: forge-et-be#273, forge-et-fe#296, and the harness’s plan PR #766 and wave PR #767. The Activities page on
mainlists and creates follow-ups. Mark done, edit and the timeline row come in wave 2. - The overnight decisions stand. They are listed in
.forge/plans/F3-a/F3-a-overnight-log.md(chiefly the browser-gate skip on forge-et-fe#296 for BUG-261). Nanndish reviewed them and merged the PRs. Theowed.mdrow asking for that review is removed. - The migration is
V53__activity.sqlonforge-et-bemain, with no duplicate version (git ls-tree origin/main src/main/resources/db/migration, read 2026-10-27). Theowed.mdrenumbering row is removed.
2026-10-27 — the test-run cost design: the rest of Phase 1
- Why. The first nightly full run was green, and the lead asked for the remaining items of the design to be built in the same day, thoroughly reviewed, with everything that saves developer time and resources. The lead also set the Mac to wake at 01:55 for the nightly run.
- Built (forge-et-fe#350, forge-et-pwa#99, forge-et-be#322, forge-et-harness#995; the design’s § Where this stands lists each decision):
- one heavy run at a time on a machine, by waiting, and the machine kept awake while one runs (M-5, M-2);
- one counted retry in both records, the flaky names published, and the weekly flaky report (F-3, F-2);
- the slowest tests in every record and gate result, and slow-test counts in the nightly log (H-1, H-2);
- selected test runs for the development loop and a work item’s own checks, and the delivery flow’s re-runs (S-1, S-3, S-5, S-7, W-1, W-2, W-4);
- the CRM’s Vitest files split into Node and jsdom projects (V-1), the capture app’s shared-file tests cut from three minutes to 22 seconds (V-3), and the full size matrix’s axe scan left out at 1440 Chromium (P-2);
- the reviewer rules that keep new tests fast and portable (H-2, H-5, F-5, M-8).
- Found on the way. Gradle’s JUnit XML still counts a retried attempt in its suite totals, which would have made the build record refuse a passing build, so the record counts each test case. Following every reference linked all 20 backend packages, so the selection follows production code.
VITEST_MAX_WORKERStakes a whole number:50%ran 50 workers on 8 cores.main’s newsettingsPermissions.test.tsneeded the jsdom tag after the merge, the first instance of what the new rule asks of every*.test.tsthat touches the DOM. The reviews found that the full-profile axe skip as designed would have left an engine-specific axe finding (BUG-271) unchecked, so P-2 was narrowed. - Decided against. V-4 (half the cores by default): the run queue removes the contention it was for. The split of the CRM’s longest Vitest files (V-3’s other half): the longest takes 38 s of a 168 s run.
- Left. The Windows checks (Nanndish,
owed.md), the lead’s weekly reading of the flaky report, and Phase 2 from about 10 November.
2026-10-29 — F38-i’s spec revision: the lead’s decisions after approval (moved from owed.md)
Moved from .forge/owed.md by F38-i-WI-2.1 once the spec PR (#999) had merged: the F38-i, F38-h and parent F38 specs cite its numbered items as the record of the lead’s decisions, with their costs and checks. The row as it stood, verbatim:
-
Revise the F38-i spec for the lead’s decisions of 2026-10-27, then decompose it (Tharinda; raised during
/forge-deliver F38-iStage 5, 2026-10-27). Done 2026-10-29: the spec’s Rev 1 (reviewed by a fresh-context reviewer) and the Decomposition Plan, approved after a 3-pass/forge-plan-review, are onfeature/F38-i-spec(PR #999). The row stays until that PR merges, because the spec cites its items 1–29 as the record of the lead’s decisions, with their costs and checks; it is then moved to.forge/engagement-log.mdand removed here. PR #999 merged on 2026-10-29. The move is made in F38-i wave 2’s harness PR (F38-i-WI-2.1, the Decomposition Plan’s## Notes), which repoints every citation of this row —git grep -n "Revise the F38-i spec"lists them, the F38-i, F38-h and parent F38 specs and the tracker among them — at the engagement-log entry in the same PR. The decisions, made after the spec’s approval, change it, so it gets a## Revisionsentry and a fresh-context review before the Decomposition Plan is written:- No AWS infrastructure outside dev until it is needed. Nothing is created for production or UAT now; F38-i writes documents and code only. Production’s AWS resources are created when the lead says production is needed. So production’s automatic apply is added only then: merging
overlays/prodmust create nothing. - No Multi-AZ, WAF or cross-region backup options are built now (FR-4’s two module options and AC-4’s check of them are removed). Empire Teas, or Shyamin Ayesh, Thilina Abeyrathna and Malinda Wellalage, ask for them if they want them.
- Production stays as close to dev as possible. Database: a larger instance and backups are fine, but there are no keys of its own. Production’s database is encrypted at rest with the AWS-managed
aws/rdskey (the lead, 2026-10-28, replacing the same day’s “not encrypted, as in dev and UAT” once its cost was set out): RDS charges nothing for encryption and an AWS-managed key has no monthly fee, so it costs about USD 0 a month; the automated backups and snapshots are encrypted with the same key, so there is no database or backups key of production’s own. Dev and UAT stay unencrypted. It meets proposal §A.4’s encryption at rest, so no departure is raised with Empire Teas; the spec revision adds a post-issue note closing the 17 October note’s “production’s is undecided”. Accepted with it: who may decrypt cannot be narrowed by a key policy, and a snapshot cannot be shared with another account (a restore in the same account and a copy to another Region still work). Encryption cannot be switched on later without a snapshot, an encrypted copy and a restore, which means downtime, which is why it is set when the database is first created: abase/rdsoption whose default keeps dev unencrypted. Deletion protection and a final snapshot are free Terraform settings inbase/rds; dev has both off. Production’s size, storage and backups (the lead, 2026-10-28, at AWS list prices read from the Price List API that day):db.t4g.small(about USD 23.36 a month, the annexe’s production class; dev isdb.t3.micro, about USD 13.14); 50 GB of gp3 storage with autoscaling (about USD 5.75 a month, the same price per GB as gp2; dev has 20 GB of gp2 and no autoscaling); automated backups kept 14 days with point-in-time recovery, as proposal §A.5 promises, free up to the database’s size (dev keeps none: its retention is 0, read withdescribe-db-instanceson 2026-10-28). Each is abase/rdsvariable whose default keeps dev’s value. - Deploys: anyone with write access may create a release tag; there is no named-deployer list or tag ruleset. CI users are configured as in dev, not narrowed and not rotated every 90 days, unless Shyamin Ayesh sets that up himself. The image pull uses dev’s existing key, with no new pull user (Q-7). Pushing a correct release tag deploys automatically (the lead, 2026-10-28; this replaces decision 2’s manual dispatch). By decision 1, the tag trigger is switched on only when production is created, so a tag pushed before then starts no run.
- Terraform for production applies automatically on a push to
dev, with no appliers list (decision 10 and FR-5’s iaac check are removed); reviews go through PRs that Shyamin Ayesh approves. - No database tunnel in any environment (FR-12 item 7 and Q-6 are dropped); one is built later only if a real need comes.
- The seeded admin’s email is a plain value in each environment’s task definition, production’s included (the lead, 2026-10-28: one way in every environment, and no secret, at about USD 0.40 a month, for a value that is not sensitive). AD #34 says production’s address comes “from Secrets Manager, never in git”, so the spec revision adds an AD row refining AD #34, and changes FR-9, register step 28 and the
base/secretsentry the spec planned. “Never a real person’s email outside production” still holds. - KMS keys: production keeps dev’s two customer-managed keys,
storage(the attachments bucket) andmailbox-token(the stored mailbox refresh tokens), at about USD 1 a month each; there is no database or backups key. These two are explained to the lead (2026-10-28): Secrets Manager does not fit many items, and S3’s free built-in encryption gives no control over who may decrypt. Not challenged by the lead. - Deletion protection and a final snapshot for production’s database: on in production (the lead, 2026-10-28). Both are free settings in
base/rds, and both stay off in dev (deletion_protection = false,skip_final_snapshot = true), so they are module options whose defaults keep dev’s values. FR-4 keeps them as written. Automated backups are free up to the database’s allocated storage, so 14 days of a small database costs about nothing. - The Entra tenant ID, client ID and certificate are plain task-definition values in every environment (the lead, 2026-10-28, with item 7; the row “Decide whether the Entra tenant and client IDs stay in Secrets Manager”): none is secret (the certificate is the public half of the key pair), and each costs about USD 0.40 a month per environment as a secret, so USD 1.20 a month is saved in each. Only the Entra private key, the Exa key and the RDS-managed database password stay in Secrets Manager. It applies to dev (
forge-et-be.aws/td.dev.json;forge-et-iaacbase/secretsdropsentra-tenant-id,entra-client-idandentra-certificatewithremovedblocks, since the module’s secrets carryprevent_destroy), to UAT (.aws/td.uat.json, F38-h) and to production (.aws/td.prod.json); F38-i builds it in its waves 1 and 7, and register §D is changed to match. - Production’s source maps are built but not uploaded (the lead, 2026-10-28; the row “Decide whether the two frontends publish their source maps”): each frontend’s
deploy-produploads with--exclude "*.map", so the bundle is the same build and the original code is not public in production. Dev and UAT keep uploading them. - The monthly report to Empire leaves F38-i (the lead, 2026-10-28; spec Q-2): it would be manual work after go-live, with nothing built in AWS or the app, so FR-13 and AC-13 are removed and wave 13 does not check it. Register §C-8’s row “Monthly environment-health and usage reporting to Empire” stays open, owned by Altrium operations, for the lead to settle with Altrium management (whether a report is sent under the support fee, and what it holds). An automated version, if ever wanted, would be a scheduled job reading Cost Explorer and CloudWatch and sending by SES, under USD 0.10 a month, and is not built.
- Alarms (the lead, 2026-10-28; the row “Decide the UAT and production alarm sets”): production’s alert topic is not encrypted, as dev’s (
base/alerts/topic.tf; a customer-managed key would be USD 1 a month for text that leaves AWS as plain email). UAT gets no alarms; F38-h stays as built. Production’s set, about USD 1.50 a month at list price: the load balancer’s unhealthy-host alarm (uptime, PRD § Observability and Audit; USD 0.10); its 5xx alarm (backend errors,client/dependencies.md§1; USD 0.10); the failed-deploy email (free,base/alerts); one metric filter and alarm on the backend’sERRORlog lines (USD 0.40: USD 0.30 for the filter’s metric, USD 0.10 for the alarm) —MODEL_UNAVAILABLEis logged at WARN today with every other failed Bedrock attempt (forge-et-beBedrockAiProvider.java, “Bedrock Attempt Failed - [feature=…, model=…, kind=…]”), and F38-i wave 7 changesBedrockAiProviderto log theMODEL_UNAVAILABLEkind atERROR(the lead, 2026-10-28: a model not found, access denied or a request refused as invalid never passes on its own and needs a person; the retryable kinds stay WARN), with a test, so the one filter covers it and its log line names the feature and the model asai-provider-strategy.md§4c rule 3 requires. The lead’s condition (2026-10-28): only code and server faults are logged atERROR, never a user’s ordinary action, so the alarm does not flood the recipients. Checked that day: the 27ERRORmessages inforge-et-bemainare all faults undercoding-standards.md§8.3 (“an expected business outcome is never an ERROR”) — unhandled exceptions, framework 5xx only (a 4xx goes throughApiExceptionHandler.logOutcomeat WARN or below), failed dependencies, audit writes not recorded, a batch job whose every unit failed; failed sign-ins, permission denials, validation errors and a user cancelling Microsoft consent are notERROR. A CloudWatch alarm emails on a change of state, not per line, so a burst of errors sends one email. Dev’s realERRORlines, read 2026-10-28 for the 14 days before (/ecs/dev/backend, filter{ $.log.level = "ERROR" }): 43 lines, all faults — 20Mailbox Consent Completion Failed [reason=NotFoundException](15–21 Oct, ending the day before forge-et-be#300 gave dev’s task definition the mailbox token key’s id), 9Search Provider Not Configured [provider=exa](22–23 Oct, at each start while the Exa key was unset), 4 database certificate checks failed with 4Application run failed(26 Oct, a backend that could not start), and 6 from Spring Cloud AWS’s job listener (Error processing message,Error converting message, 23 Oct). None came from a user’s ordinary action. A database unique-rule clash from an ordinary action (one in the 14 days, a duplicate user email on 27 Oct) is logged by Hibernate at WARN (org.hibernate.orm.jdbc.error), without the value, so it never reaches the alarm. A failed background job is therefore logged atERRORby the framework (AbstractMessageProcessingPipelineSink), so no dead-letter alarm is added and the set stays at about USD 1.50 a month. The Exa line staysERROR(the lead, 2026-10-28): Empire’s own Exa key is a go-live requirement (spec W-7), so production’s backend logs it at each start only until the key is set, and wave 13 checks the key is set before go-live; the worker stopped: the age of the oldest message on each of the four main queues (scheduler, mailbox ingest, lead triage, lead research; USD 0.40); the scheduler not delivering its tick (USD 0.10); and the database’s free storage, free memory, swap and CPU credits (USD 0.40). Not built: the mailbox alarms (a user inRECONNECT_REQUIREDsees the reconnect prompt on the Email screen,forge-et-feMailboxRoute.tsx, and reports it), the Entra-key alarm (nobody can sign in, so it is reported at once), the F20-b dashboard, and a separate dead-letter alarm per queue — unless the plan finds that a failed background job is not logged atERROR(by the job framework, Spring Cloud AWS 4.1), in which case one dead-letter alarm per queue is added (USD 0.10 each). Recipients: production’s alert email goes to the four delivery-team members (tharinda, dinil, biseni and nanndish @altrium.io, dev’s list inforge-et-iaacoverlays/dev/env.auto.tfvars) plus Shyamin Ayesh, Thilina Abeyrathna, Malinda Wellalage and Kavindu Anthony, and any further Empire Teas address they give; their addresses are confirmed before production is created. Dev and UAT keep the four delivery-team members. - Bedrock quota requests for production go into a quota request template (the lead, 2026-10-28; the row “Decide what the requests-per-minute targets for Sonnet 5.5 and Haiku 5.5 become in production”): Shyamin Ayesh is asked to set up a Service Quotas request template in the management account holding dev’s six requests of 15 October (tokens per minute for Sonnet 5.5 and Haiku 5.5, requests per minute for Haiku 4.5), so production files them automatically when it is created. Free, and nothing is created in production. Service Quotas has no requests-per-minute quota for the 5.5 models, so their targets are tokens per minute, at dev’s figures.
- Accepted: anyone with write access to an app repo or to
forge-et-iaaccan reach production’s admin CI key (the lead, 2026-10-28) by pushing a release tag, or a push todev, whose workflow file they changed, because there is no tag ruleset and no named-deployer list (item 4) and the one CI user hasAdministratorAccess(item 15). The controls are the team rule that every change reaches a trunk by PR and GitHub’s record of who pushed each tag; a tag ruleset (free, a repository-admin change) would close it, and was not chosen. The spec revision records it as old decision 10 recordedforge-et-iaac’s half. - The
crm.empire.lkzone import runs only when production is created (the lead, 2026-10-28; spec Q-5, FR-3): wave 4 writes the root and validates it now, and the import runs in wave 10. Where the root, its state and its identity live is asked of Shyamin Ayesh in the row “Answer F38-i’s three questions for the DevOps team before its plan”, with the delivery team’s proposal (overlays/dns, state atet-opsdns/terraform.tfstate, a hand-madedns-prodrole for production’s records). - Production’s database is in private subnets (the lead, 2026-10-28). Dev’s database sits in public subnets (
publicly_accessible = false, with 5432 open only inside the VPC), andbase/networkinghas no private subnets. Production gets them:base/networkinggains private subnets as an option that is off by default, so dev’s plan shows no change, and production’s database uses them, with no NAT gateway, so at no cost. The proposal’s post-issue note of 27 October 2026 (“stays in private subnets”) and spec FR-4 stand as written. - Account basics (Identity Center, root MFA, password policy, alternate contacts) are the DevOps team’s console steps, not our code. Production keeps the CloudTrail trail to a locked bucket and the alarms (the lead, 2026-10-28: kept if the cost is minimal — one trail of management events is free, and its storage and each alarm cost cents). Production keeps the account-wide S3 public-access block (the lead, 2026-10-28): a free setting that proposal §A.4 lists as a standing control (“S3 public access blocked at account level”), on top of each bucket’s own block; dev goes without it (the proposal’s post-issue note of 15 October).
- Production’s Terraform state bucket uses S3’s own encryption (SSE-S3), at no cost, not a customer-managed key (the lead, 2026-10-28): the state holds no secret values (spec NFR-2), and the bucket policy limits who can read it. FR-1’s “encrypted with a customer-managed KMS key” changes; production has only dev’s two keys (item 10).
- The CloudTrail trail with its locked bucket and the account-wide S3 public-access block are built by our Terraform in
overlays/prod(the lead, 2026-10-28), written now and applied only when production is created (item 1), so they are in Terraform (NFR-5) rather than console steps. The other account basics stay the DevOps team’s console steps (item 8). - Production has one CI user, as dev has
svc-github(the lead, 2026-10-28): one IAM user in the production account withAdministratorAccess, its key a secret of theproductionEnvironment inforge-et-be,forge-et-fe,forge-et-pwaandforge-et-iaac, used for the deploys and the Terraform apply. With item 4’s image copy,forge-et-be’sproductionEnvironment also holds dev’ssvc-githubkey to read dev’scrm/backend. FR-5’s separate deploy and Terraform users and the narrowed permission list are dropped, which closes the row “Addecr:DescribeImagesandecs:DescribeServicesto the narrowed deploy user”. - On a release tag, each frontend’s
deploy-prodwaits for the backend (the lead, 2026-10-28): the same tag pushed in the three repos starts three runs at once (item 4), so each frontend run pollshttps://api.crm.empire.lk/actuator/infoevery 30 seconds for up to 20 minutes, deploys once it reports the tag’s version, and stops naming the version it last saw if it never does. A release costs a few more Actions minutes.
Progress of the revision (2026-10-28, stopped part-way; resume here). Every open decision is answered (items 1–22; nothing left to ask except the new question below). The spec on
feature/F38-i-spechas: the header’s Revised line; inline Rev 1 notes on decisions 1, 2, 4, 5, 10, 11; the new decisions 12–31 in § Context; Rev 1 notes on FR-1 – FR-7, FR-9, FR-11, FR-12 (item 7 dropped), FR-13 (removed), FR-15, FR-17, NFR-1, NFR-2, NFR-5, NFR-7; and a new FR-19 (the Entra values and admin email as plain values in every environment). Answered by the lead, 2026-10-28 (item 23, the last question): every UAT candidate is taggedvX.Y.Z-rc<N>from the start, Phase 1’s round included (v0.1.0-rc1,-rc2, …), anddeploy-uatrefuses a tag without the suffix; a plainvX.Y.Zgoes only on the commit Empire accepts and is production’s, deploying there once production exists (decision 19). One tag format per environment, with no date on which the rule changes. The version checks already ignore the suffix, so manifests are unchanged. This replaces the release rules’ plainv0.1.0for Phase 1’s round (.claude/rules/release-and-branch-protection.md§ Release Process, lines 27–30 and the handover sequence) and parent FR-35’s “the Phase 1 candidatev0.1.0carries no-rcsuffix”, and changes F38-h’sdeploy-uat(its spec FR-1/FR-2 tag rules and the wave 4 work in progress) to accept only-rctags. Item 24 (the lead, 2026-10-28): the tag format decides the environment, and pushing the tag deploys — one rule, so a person tags without choosing a workflow: pushingvX.Y.Z-rc<N>deploys to UAT automatically; pushing a plainvX.Y.Zdeploys to production automatically; merging tomaindeploys dev, as today; a branch deploys nothing (a manual dev deploy of a branch stays, AD #24). This makesdeploy-uata tag-push workflow too (v*-rc*), replacing F38-h’s manual dispatch, anddeploy-prod’s trigger isv*without-rc(decision 19). Both triggers keep decision 12: production’s is added on the day production is created, and while no UAT environment is applied a-rcpush stops at its first step with a message saying UAT is not up, deploying nothing. Chosen over “a person runs Deploy and picks the environment”, which the lead declined. Item 25 (the lead, 2026-10-28): a fix inside a UAT round is the next-rcof the same version (v0.1.0-rc1,-rc2, …), manifests staying at0.1.0with no bump PR; the plainv0.1.0goes on the accepted candidate’s commit; patch bumps only for hotfixes to a live release. Replaces F38-h decision 12’s patch bump per fix. Done 2026-10-28: the spec’s ACs, scope, constraints, open questions and § Revisions Rev 1; AD #40 (.claude/CLAUDE.md, AD #34’s pointer, the archive); parent F38 Rev 32;architecture.mdRev 82;.claude/rules/release-and-branch-protection.md§ Release Process. Also done 2026-10-28 (steps (a)–(d) complete): F38-h spec Rev 6 and a re-review note in its WI-4.1 and WI-4.2 plans; the register’s step 28, §D, §C-8 and a## Logline;environments-and-identity.md(secrets table, §5 rows);coding-standards.md§7; a dated note inclient/dependencies.md; the proposal’s post-issue note of 28 October (production’s database encrypted). Harness checks green (check-unique-ids.py,check-md-frontmatter.sh,check-features-index.py,yq). Step (e) done 2026-10-28: the fresh-context reviewer found no Blocker; its Important and Nit findings are fixed in the commit after this line, and four questions it raised were answered by the lead the same day — item 26: pushing the plainvX.Y.Zmeans “go live”: it is pushed when Empire wants the accepted release live, and acceptance is recorded against the accepted-rctag, the immutable handover record (before production exists a plain tag deploys nothing); item 27: the rehearsal keepsv0.1.0-rc1and Phase 1’s round starts at the next free-rc(v0.1.0-rc2or higher); item 28: an existing tag is deployed to a freshly applied UAT (or production) by re-running that tag’s workflow run from the Actions page (GitHub allows a re-run for 30 days; after that, the next-rc), with no manual workflow; item 29: AD #40 stays a general rule — any setting that is not secret is a plain task-definition value. Next: step (f). (Earlier:) Paused 2026-10-28 for the lead’s travel, at step (e): a fresh-context reviewer was dispatched overgit diff 7573570b HEADof the changed files against items 1–25; its result may not have come back. Resume: if no review result is recorded here, run step (e) again (one fresh-context reviewer: old text at7573570b, new at HEAD, class each change faithful/narrowed/widened/dropped/reversed against items 1–25, check dropped detail survives, check the AD #40 row, the client-facing notes and the release rules), apply its Blocker and Important fixes, record the outcome here, then step (f). Still to do, in order: (a) fold items 23 and 24 into the F38-i spec as decision 32, FR-6, FR-7, FR-15, FR-18 (the capture app’sdeploy-uaton the same trigger) and AC-6, AC-15, AC-18, FR-15 and AC-15; into.claude/rules/release-and-branch-protection.md§ Release Process; into parent F38 Rev 32 at FR-35; and into a revision of F38-h’s spec (and its wave 4 plans if they name the tag rule), telling whoever works F38-h wave 4; (b) the spec’s ACs — AC-1 (state bucket SSE-S3), AC-4 (no Multi-AZ/WAF check; the database settings; the apply on a push todev, merged code creating nothing), AC-5 (one CI user; drop the deployer, ruleset and appliers checks; keep the Environments’v*/devrules), AC-6 (a tag push deploys; an-rctag starts no run), AC-9 (plain admin email and Entra values), AC-11 (the set of decision 26), AC-12 (seven checks, no break-glass), AC-13 (removed), AC-15, AC-16 (the Rev 1 records), a new AC-19 for FR-19; § Scope, § Constraints and § Open Questions (Q-2, Q-4, Q-6, Q-7 resolved; Q-5 restated with theet-opscorrection; W-4, W-8 and the encryption entry resolved); the## Revisionsentry (Rev 1, listing each change as faithful, narrowed, widened, dropped or reversed, approved by Tharinda 2026-10-28); © the AD row refining AD #34 (.claude/CLAUDE.md, with a pointer on AD #34’s row and the full text in.forge/engagement-log.md’s archive); (d) parent F38 Rev 32 with inline notes at FR-3, FR-8, FR-19, FR-35, AC-39;architecture.mdRev 82 (thedeploy-prodrows and the GitHub Environments rule); the register’s step 28 (lines ~192, ~383), §D (~658, ~2078) and the two §C-8 client-decision rows;environments-and-identity.mdline 19 and §5 (~3506, ~3530);coding-standards.md~544;client/dependencies.mdline 48 (client-facing:.claude/rules/client-docs.md); a proposal post-issue note dated 28 Oct 2026 (production’s database encrypted with the AWS-managed key, closing the 17 Oct note’s open point); (e) one fresh-context reviewer given the old and new text (CLAUDE.md § Compounding Engineering rule 6); (f) then/forge-deliver F38-i --manual-approve, Stage 5, on the agreed layout below, revised for decisions 12–31 (FR-19 adds dev and UAT changes: the task-definition change before thebase/secretsremoval; wave 7 also carries theBedrockAiProviderlog level), and lock waves 9–13’s ship declarations with the lead.Agreed in the session before these decisions (to keep unless the revision changes them): 13 waves. Waves 1–8 are build-ahead: 1
base/options; 2 release rules; 3overlays/prodand its workflow; 4 the zone-import root; 5 production alarms; 6 the capture app’s hosting inoverlays/uat; 7deploy-prodand the FR-18 halves in the three app repos; 8 the October bill comparison, run by the main session in early November. Waves 9–13 are manual and gated on.forge/design/environments-and-identity.mdonmaincontaining “The production account exists:”. Waves 1–8’s ship declarations were accepted. Waves 1, 3 and 7 shrink with decisions 2–5. Gates: wave 6 waits on F38-h wave 3 merged (wave_merged, repos[forge-et-harness], since a gate cannot nameforge-et-iaac); wave 7 waits on F38-h wave 4 merged (repos[forge-et-be, forge-et-fe]). Manual waves and the ACs each owns: 9, the account — AC-1 (wave 10 records the SES half of AC-2); 10, the zone import and production apply — AC-2, AC-3, AC-4, AC-5; 11, the first deploy, the failure cases and the alarms tripped — AC-6, AC-7, AC-8, AC-9, AC-11, AC-17; 12, the capture app in UAT — AC-18, gated on F38-h atdone; 13, go-live — AC-10, AC-12, AC-13, AC-16. Wave 2 owns AC-15 and wave 8 owns AC-14. Each manual wave’s checks shrink with decisions 4–6 (no named-deployer, tag-ruleset or appliers checks, and no break-glass test). - No AWS infrastructure outside dev until it is needed. Nothing is created for production or UAT now; F38-i writes documents and code only. Production’s AWS resources are created when the lead says production is needed. So production’s automatic apply is added only then: merging
Closed with it on 2026-10-29:
- Settle the ECR fallback for a hotfix tag on
release/*— F38-i FR-15: a hotfix commit with no dev-built image gets one from the dev deploy dispatched on the release branch; stated in.claude/rules/release-and-branch-protection.md § Release Processand/forge-releaseby F38-i wave 2. - Decide whether production’s database is encrypted at rest — decided by the lead on 2026-10-28 (item 3 above): the AWS-managed
aws/rdskey, about USD 0 a month; F38-i spec Rev 1, decision 14.
2026-10-29 — the test-run cost design: Phase 2 brought forward
- Why. The 2026-10-29 nightly run was red on two flaky browser tests (BUG-275 and BUG-282, both fixed that day), and full gates on the shared laptop kept being invalidated by load, sleep and a stopped backend: forge-et-fe#356 was merged on a gate skip after two such runs.
- Decided by the lead. Phase 2 of
.forge/design/harness/test-run-cost.mdis built now and switched on after seven green or explained nightly runs in a row, about 5 Nov, in place of Q-1’s two weeks. Until the switch-on, a small contained PR may carry a browser-gate skip after its changed specs and its screen’s specs pass at every size in both engines. An ad-hocplaywright testtakes the machine’s heavy-run lock through a Playwright global setup in both frontends. - Built the same night. The selected browser gate (S-2:
pnpm e2e:gate --selected,e2e/feature-map.json) and the ad-hoc run’s lock, in forge-et-fe#361 and forge-et-pwa#102, both merged on 2026-10-30. A live selected run of a one-line activities change ran 240 tests in 2 min 51 s, against about an hour for a full PR-profile gate. S-4’s selected records and its one-feature limit go into the switch-on PR (owed.md).
2026-10-30 — F20-l shipped: several email addresses per contact
F20-l merged in three waves:
- Wave 1, 2026-10-29: forge-et-be#335, the other-address store, the API, validation, search and audit. forge-et-fe#358, a test-only PR, merged just before it.
- Wave 2, 2026-10-30: forge-et-be#341, lead triage matching by every address, and the Pipedrive migration keeping, comparing and writing every address.
- Wave 3, 2026-10-30: forge-et-fe#363, the contact form’s Other email addresses group and the contact page’s Other emails row.
Wave 3’s PR skipped the full browser gate, by the lead’s decision of 2026-10-29. WI-3.2’s targeted runs on its final head stood in for it, against a clean baseline at main.
Two owed.md rows closed with it:
- Land a contact’s other email addresses before the first production run of the Pipedrive migration. The change is merged, so the first load, whenever it is agreed with Empire, keeps every address.
- Tell Nanndish that F20-l’s contact screens wait on forge-et-fe#355. #355 merged on 2026-10-29, and wave 3 was planned on its screens (spec Rev 5, Decomposition Plan Rev 2). F1-d’s form test ids carried over.
2026-11-02 — the lead agrees the UI revamp preview’s reversals (moved from owed.md)
forge-et-fe#364 merged on 2026-10-30 before the lead had agreed three of its reversals. On 2026-11-02 the lead agreed all three:
- Design-system Rev 77: record pages are full width, not a centred column, and the account, contact, user and role pages edit in a dialog over the page. This reverses Rev 70 (the lead’s own centred record page of 2026-10-21) and Rev 74. The approval lines of Rev 77 and of F1-b Rev 11, F1-d Rev 10, F1-f Rev 6, F5-c Rev 12 and F5-d Rev 8 now record the agreement. BUG-137, which asked for regression checks of the centred column on the account page, the message view and the offboarding page, closed as won’t-fix.
- F5-g Rev 1: the Shared with card and its access dialog show the record’s owner, reversing F5-g decision 2 of 2026-10-10.
- F5-d AC-19: the Edit role dialog keeps All records hidden while None is chosen (F5-d Rev 9). BUG-284, a defect of the shown-and-blocked form it replaced, closed as fixed by #364.
Two sub-items of the owed.md row “Change requests from the 2026-10-08 manual test pass” were removed the same day, each found done on main: sorting on Users, Roles and the Standards book (BUG-170, fixed by forge-et-fe#355), and the Roles table’s permission-count column (gone since F5-d’s UI/UX review; the Roles test asserts the columns Name, Description, Users and Actions).
2026-11-02 — open items re-audited against the latest state
- What was done. At the lead’s request, every open item was checked again against the five repos (
origin/mainatde55c5ecfor the harness;origin/devforforge-et-iaac) and the dev account (read calls assvc-harness). The 26 Oct report this replaces is stale. - Closed in
owed.md, each checked: “Review F3-a wave 1’s overnight decisions before merging its PRs” — forge-et-be#273, forge-et-fe#296, forge-et-harness#766 and #767 all merged on 2026-10-27; and “Renumber F3-a’s migration before it merges” — #273 merged withV53__activity.sql, which is onforge-et-bemainbetween V52 and V54. - Kept, although proposed for closing: “Decide whether the Entra tenant and client IDs stay in Secrets Manager”. AD #40 decided it on 2026-10-28, but the row closes when dev’s task definition and
base/secretscarry the change, and dev still holds the tenant ID, client ID and certificate as secrets (aws secretsmanager list-secrets, 2 Nov). - Corrected: the CSP row (forge-et-iaac#14 merged and applied on 2026-10-28; the signed-in check is what is left), the cloud bring-up row (F38-i is in Phase 1 and owned by Tharinda, and every AI feature runs on Haiku 4.5), the F11-f Rev 5 row (#364 has merged), the Haiku 4.5 quota row (still 10 a minute on both quotas, 2 Nov), and
test-strategy.mdRev 34 (the dev restore rehearsal is a restore of its own, because dev’s database stays unencrypted). - Read on dev: the backend runs
backend:90; six schedules are enabled; the lead-triage, lead-research, mailbox-ingest and scheduler queues exist with their dead-letter queues; the database isdb.t3.microon gp2, unencrypted, with backup retention 0 and the managed secret’s rotation off; SES has production access; the CRM sends its Content-Security-Policy and HSTS. - Found in passing: the nightly full run has been red on all three app repos since 2026-10-31 (forge-et-be#343, forge-et-fe#370, forge-et-pwa#104), and the Phase 1 acceptance criteria are still not issued.
2026-11-02 — the nightly red explained, and the browser gate taken off PRs into main
- The red nights were a closed lid.
pmset -g logshows “Clamshell Sleep” on the lead’s Mac from 02:19 on 31 October, 01:55 on 1 November and 01:14 on 2 November, each until the morning, while the lead was travelling. The 01:55 wake then gives only dark wakes of a few seconds every 15 minutes, so the backend build crawled until 10:09, about 25 tests took 750–940 s each, timing tests failed (ScanResultQueueIT,ScheduledJobRoutingIT,PriceExpirySweepIT) and the frontend suites hit the deadline; 1 November did not run. Not a code defect: forge-et-be#344, which containsmain’s headef022576, passed the full build locally that day (10,980 tests, none failed). The cause was posted on forge-et-be#343, forge-et-fe#370 and forge-et-pwa#104. forge-et-harness#1068 (merged) makes the runner count sleep in a suite’s time limit and report a red suite the Mac slept through as not run, naming the sleep (test-run-cost.md, revision line of 2026-11-02). - Decided by the lead. Without waiting for seven green nights, a PR into
main, a wave PR included, runs no browser gate, and the build and test records run the tests the change needs (every test for shared code); as much as possible is left to the nightly full run, whose findings are fixed together the next morning. A PR intorelease/*keeps the full gate, because the nightly run tests onlymain. Recorded as PRD Rev 81, S-4 revised, F40 spec Rev 9,test-strategy.mdRev 35,architecture.mdRev 83, and the rules, skills and guides that ran the gate; the harness hook ongh pr create/gh pr readyis unregistered. The app-repo halves (each frontend’sFast lanelast step only on a PR intorelease/*, and the selected records in all three repos) are their own PRs, named intest-run-cost.md’s revision line. - Recommended, then accepted by the lead the same day: run
pnpm e2e:gate --selected(about 3 minutes for one feature) before marking a screen-changing PR ready, expected and not enforced (the Browser QA rule’s development check); cut a release tag only on a commit the nightly run passed in full (.claude/rules/release-and-branch-protection.md § Release Process,/forge-release); keep the full gate on PRs intorelease/*; keep the secret scan, theFast lane’s static checks and the review record on every PR. Risks named: the nightly run on one laptop is a single point of failure, and a red night covers several PRs whilemainand dev carry the break for up to a day (owed.md, “Keep the nightly full run reliable”). - The nightly run made to carry what PRs dropped (the lead: PR gates as light as possible, everything removed run at night, plus what PRs skip): a secret and dependency scan of every repo every night (gitleaks fails on a secret; Trivy reports, AD #38), and each frontend’s static checks and build on
main. Their first run passed and found one HIGH Trivy finding in the backend (Guava,owed.md)./forge-deliver’s final-wave e2e run was narrowed to the item’s own specs (test-run-cost.md, revision lines of 2026-11-02). - Windows. Nanndish reported why the backend build is slower on Windows (Defender, NTFS small files, Docker through WSL 2, the search indexer, one test JVM). It matches M-1 and Q-6; the recommendation stays a Dev Drive first with a before-and-after record, and parallel test JVMs stay B-7 in Phase 3.
owed.md’s two Q-6 rows were merged into one. - Also corrected:
owed.md’s wake row closed (the repeating 01:55 wake is set,pmset -g sched), its stale BUG-275 row removed (fixed on 2026-10-29 in forge-et-fe#356), the UI-revamp browser-test row updated (forge-et-fe#364 merged; forge-et-fe#371, a draft, updates the specs and is the next thing the CRM gate onmainneeds), and thetype: e2eStage 7 row removed, settled by narrowing that run to the item’s own specs under the lead’s direction to leave as much as possible to the nightly run.
2026-11-03 — a flat battery, nine new CRM failures, and each test suite run in one place
- The night was lost to the battery. The lead’s Mac ran on battery and hibernated at 02:56 on a 1% charge, 18 minutes into the CRM browser gate; it woke at 09:46. The backend build passed (11,251 tests); CRM Vitest failed one test (BUG-325, a flake); neither browser gate ran.
- A full run by hand from 09:51 (every suite forced, on mains power, 1 h 28 min) passed everything but the CRM browser gate: 5,880 passed, 9 failed, 129 known failures. Its gate first could not start because another session’s hand-run Playwright spec held port 5173; that run was stopped with the lead’s agreement and the other sessions were asked to leave the machine free.
- The nine failures, triaged and fixed in forge-et-fe#385: four specs left behind by forge-et-be#342’s AD #41 keys (BUG-324); BUG-309’s dialog body, now failing at 1024 and 1280 too, fixed for real as the lead chose (the body is a named, focusable region with an inset focus ring); BUG-313’s mark, which no longer failed; BUG-308, the contact name that could not wrap at 320px (not a Windows flake). On the way,
mainfailed its typecheck twice from PRs that crossed (BUG-326), and two more tests failed onmain(BUG-327, BUG-328). Claimed in forge-et-harness#1090; recorded in.forge/bugs.md. - Decided by the lead (test-run-cost.md N-5, forge-et-harness#1092): a test suite runs in one place, never in two. CI runs the suites only on a Dependabot PR and a manual run that asks for them; a push to
release/*runs the Fast lane; the scheduled CI run is weekly, kept only to refreshmain’s caches, and skips a quiet week; a PR intorelease/*records every test and must be up to date (theprotect-releasesrulesets changed by Claude with the lead’s admin rights); a tag onmainchecks the Fast lane only (-f tests=false, honoured onmainonly). The nightly run gained every check CI ran onmain(run-nightly.py, forge-et-harness#1092); the workflows changed in forge-et-be#352, forge-et-fe#387 and forge-et-pwa#107. Guava raised to 33.7.2 for CVE-2026-102554. The nightly run stays on the lead’s Mac, and a missed or interrupted night is run again by hand the next morning (forge-et-harness#1099). - Recorded for later (
owed.md): checking a backend response change against the frontend’s specs before merge; a dev-server port of the browser gates’ own; an/et-nightly-triageskill; twoblock-dangerous-bash.shfalse refusals; small leftovers. The capture app’s dev smoke check is owed by F38-g before it closes (its decomposition plan and tracker note); its UAT and production deploys are F38-i work items, from Phase 2’s round.
2026-11-04 — background AI work on Haiku 4.5’s Global profile (moved from owed.md)
The owed.md row “Decide whether background AI features run on Haiku 4.5’s Global profile” (raised by the design check of F42 on 2026-10-27) is removed, its decision taken and built. On 2026-11-02 the lead asked to try it, and it became F43’s point 4 (.forge/specs/F43-ai-quota-backlog-and-busy-answer-spec.md). Haiku 4.5 has two request quotas of 10 a minute each, the cross-Region one for its us. profile (L-CCA5DF70) and the Global one (L-E5084BBA), and the backend paces each profile separately, so putting lead triage and lead research on the Global profile gives the calls a person waits for the whole us. quota and doubles the total. The row’s three conditions were met by F43: (a) where requests are processed — the lead’s direction of 2026-11-02, under OQ-15’s default, recorded in the PRD (Rev 82), OQ-15’s row, client question Q18, the client-facing PRD and a post-issue note on the proposal; (b) the task role’s grant — forge-et-iaac#16 for dev and 6596205 on forge-et-iaac#11 for UAT (F43 wave 3); © the configuration — six price and pacing rows in application.yml and dev’s two model keys in .aws/td.dev.json (F43 wave 4, F43-WI-4.1). Whether Bedrock enforces the two quotas separately under load is register §B F43 item 2, proved by F43’s dev run (F43-WI-5.1).
- Empire is not told separately (the lead, the same day): client question Q18, the client-facing PRD’s § 3.3 and the proposal’s post-issue note of 4 November state it, as with GuardDuty and the add-ons on 9 October (F43 spec Rev 2).
- OQ-15 closed by the lead: processing in any commercial AWS Region is accepted (PRD Rev 82, which moves the row to
project-prd-history.md). Client question Q18, unanswered since 30 September, is answered with this decision and closed, kept in the list with the answer and the reasons; the proposal’s post-issue note of 4 November states it. The grounds come from the AWS Bedrock documentation, read the same day, and hold on every route:- every call is made from Empire’s own account;
- data between Regions stays on the AWS network, encrypted;
- Anthropic has no access to prompts or answers;
- neither AWS nor Anthropic trains on them.
- Which model to try first, and which route (
ai-provider-strategy.md§4d):- When the 5.5 models answer, Haiku 5.5 is evaluated first for every feature, and Sonnet 5.5 stays only where Haiku 5.5 fails
model-choice-evaluation-plan.md§4.3. That plan’s D-4 is decided too: the lead signs off each result. - Both profiles of a model are used while its quotas are tight. Every feature moves to its
global.profile once one profile’s quota covers peak demand.
- When the 5.5 models answer, Haiku 5.5 is evaluated first for every feature, and Sonnet 5.5 stays only where Haiku 5.5 fails
2026-11-06 — the dev database’s operating-system update applied (moved from owed.md)
The read-only scan of 4 Nov found an operating-system update (system-update) pending on et-dev, with no date by which AWS would apply it itself. On 6 Nov (Sri Lanka time) the lead asked for it to be applied at once. svc-harness holds ReadOnlyAccess and IAMFullAccess but no RDS write, and the first attempt was refused (AccessDenied). At the lead’s request, svc-harness then gave itself a temporary inline policy, temp-apply-et-dev-os-update, allowing only rds:ApplyPendingMaintenanceAction on et-dev. It applied the update with --opt-in-type immediate at 18:59:54 UTC on 5 Nov and deleted the policy straight after. aws iam list-user-policies again lists only spike-invoke-gateway.
- RDS events: offline patching started at 18:59:56; the database shut down at 19:00:03, restarted at 19:02:11 and accepted connections at 19:02:13; patching finished at 19:02:17. It was
availableagain at 19:03:53. - Unchanged afterwards: the instance, its creation time (2026-10-05), endpoint, PostgreSQL 18.3,
db.t3.micro, 20 GiB andus-east-1b. No maintenance action is pending. - The backend recovered by itself: readiness returned 503 during the restart and 200 from 19:02:17, with
dbUP. The ECS task was not replaced, because the load balancer checks liveness, which does not read the database. The target is healthy. The backend’s 15 WARN lines, from 19:00:10 to 19:01:44, are all closed-connection and health-check messages from the restart, and there were no ERROR lines. - Smoke run:
pnpm e2e:smokefromforge-et-feorigin/mainpassed all nine checks (SMOKE_EXIT=0), signed in asCRM05. - Backups: dev’s backups are off (a dev decision,
environments-and-identity.md§4), so no snapshot was taken first. An operating-system update does not touch the database’s storage.
2026-11-06 — the DevOps Trello board brought up to date (moved from owed.md)
The ET cards on the DevOps Trello board were checked on 3 Nov and 6 Nov against forge-et-iaac’s PRs and dev history, the app repos’ deploy files, CloudTrail’s write events and the harness. Claude wrote the text, and the lead posted it on 5 Nov (19:22–20:19 UTC). The last export, of 5 Nov at 20:19 UTC, matches GitHub, the dev account and the harness.
- Open cards and what each waits on:
- “[ET] Review forge-et-iaac#11” (In Review): Shyamin Ayesh’s review.
- “[ET] Review forge-et-iaac#17” (In Review): the F38-i WI-4.1 change list, then Shyamin’s review.
- “[ET] UAT environment…” (On Hold): Empire’s answer.
- “[ET] Production environment and go-live” (Project ET TODOs): Q-5, the DNS zone question.
- “[ET] Bedrock quota increase…” (Blocked): AWS lifting the account’s limits.
- Done cards added: the dev deploy pipelines (F38-d), the delivery team’s task-definition lines, the temporary
svc-harnesspolicies, forge-et-iaac#10, #15 and #16, and the dev database’s operating-system update. - The lead’s decisions (2026-11-06):
- Senuthmi Thimansa is not added to the #17 card.
- forge-et-iaac#13, merged on 28 Oct with no approving review on GitHub, was approved by Shyamin Ayesh outside GitHub.
environments-and-identity.md§4 andowed.mdsay so.
- Still asked of Shyamin on the board: Q-5, and the reviews of #11 and #17. The question asked there about the 23 Oct console sign-in as
svc-harnesswas answered by the lead the same day: it was Nanndish Satgunarajah, who holdssvc-harness’s credentials for his testing work (environments-and-identity.md§4), so the owed row “Find out who signed in…” is closed. - Later card changes come from each item’s own owed row, for example “Finish forge-et-iaac#11…”.
2026-11-06 — open items re-audited against the latest state
- What was done. At the lead’s request, every open item was checked again against the five repos (
origin/mainatbbe93dc0ffor the harness;origin/devatb8489c6forforge-et-iaac) and the dev account (read calls assvc-harness). The 2 Nov report this replaces is stale. - Closed in
owed.md, each checked:- “Start the nightly run’s backend with the verify bucket, before F20-i wave 2 merges”.
run-nightly.pypassesBACKEND_ARGStobootRun; the change landed in55ae7f5a5on 3 Nov. The row’s done condition is a green nightly run after the merge. F20-i wave 2 merged on 4 Nov (forge-et-be#356, forge-et-fe#395, forge-et-harness#1103). The night of 5 Nov ran on fead901ba, which contains #395, and the CRM browser gate passed, its seam specs included (nightly-logissue #981). - “Review F3-a wave 2’s overnight decisions before merging its PRs”. The row’s done condition is that the wave 2 PRs merge, and forge-et-be#327, forge-et-fe#353 and forge-et-harness#1005 all merged on 3 Nov.
- “Start the nightly run’s backend with the verify bucket, before F20-i wave 2 merges”.
- Corrected: risk R-PRD-002’s description in
tracker.yamlno longer calls the decision pending, because OQ-15 was settled on 4 Nov (PRD Rev 82). Whether the risk closes is the lead’s decision. - Left as it is: on
main, the tracker shows F3-a wave 2 aspr-open, F43 atspecand F11-g in backlog. Their branches (feature/F3-a-wave-3,feature/F43-plan,feature/F11-g-plan) hold the current state, and merging them correctsmain. - Read on dev:
- The backend runs
backend:109, six schedules are enabled, and the ruleet-dev-backend-deployment-failedis enabled. - The database is
db.t3.microon gp2, unencrypted, with backup retention 0 and no pending maintenance. The managed secret’s rotation is off. - SES has production access, and ECR’s
crm/backendtags areIMMUTABLE. - Haiku 4.5 is at 10 requests a minute on both quotas.
- The Entra tenant ID, client ID and certificate are still secrets (AD #40 not yet applied), and
svc-githubstill holdsAdministratorAccess. - Both the CRM and the capture app send a Content-Security-Policy and HSTS.
- The backend runs
- Still open, found again: the Phase 1 acceptance criteria are not issued; the header still reads “DRAFT, 8 October”.
2026-11-06 — F38-i WI-4.1’s plan settles two owed rows (moved from owed.md)
F38-i WI-4.1’s plan (.forge/plans/F38-i/F38-i-WI-4.1-plan.md) was approved on 2026-11-06 after one /forge-plan-review pass. It takes forge-et-iaac#17, Senuthmi Thimansa’s overlays/prod, as the work item’s implementation, and its D-1 is the list of changes #17 must reach. Two owed.md rows closed with it, each on its own close condition (the plan’s D-10):
- “Three points for F38-i WI-4.1’s
overlays/prod, from the review of forge-et-iaac#15” (2026-11-04). The row closed when WI-4.1’s plan had decided each point. All three are decided:base/rdsgainscopy_tags_to_snapshot(defaultfalse), settruein production (D-1 (1) and (15)).private_subnet_cidrsgains avalidationblock: empty, or at least two subnets and no more than the Region has zones (D-1 (16)).overlays/prodstatesrequired_version = ">= 1.9"(D-1 (4)).
- “Allow the backend’s task role to call Haiku 5.5” (2026-10-26, widened on 2 Nov to all six routes of the three planned models). Dev’s grant is applied (forge-et-iaac#13 and #16), and UAT’s is on forge-et-iaac#11. The row tracked production only, and closed when F38-i’s plan for the production overlay named all six profiles. WI-4.1’s plan does: its D-1 (11) keeps on #17 dev’s
bedrock_invoke_arnsas it stands after #16, which holds theus.andglobal.profiles of Haiku 4.5, Sonnet 5.5 and Haiku 5.5 and one foundation-model wildcard per model. Production’s read of the six (aws bedrock get-inference-profile) waits for the production account, and register §B F43 item 4’s production part carries it. That #13 was approved outside GitHub is kept inenvironments-and-identity.md§4.
At the same review, the lead confirmed two of the plan’s decisions:
- production’s Terraform state bucket is in
us-east-1(D-3, spec NFR-5); - production’s ECR keeps 10 release images and expires
v0.0.*images 7 days after they are pushed (D-4).
2026-11-06 — the current CRM prototype brought up to the built CRM (moved from owed.md)
At Nanndish’s request, .forge/design/prototypes/crm-current/ was compared with forge-et-fe origin/main (4a91ed9c) and every built screen that had moved past the 2026-11-05 redraw was drawn as built. Nothing not built was removed: it stays, marked Not built yet where it sits inside a built screen. What was drawn, kept and left is in design/prototypes/README.md. The Email screen now has everything three owed.md rows asked for, so they were closed: “Bring the crm-current prototype’s Email screen up to F20-i wave 4” (Tharinda), “Draw the live inbox in the current CRM prototype” (Tharinda) and “Draw the Email folder pane’s rail in the current CRM prototype” (Nanndish). What was not drawn has a new row, “Finish the current CRM prototype’s 2026-11-06 catch-up”.
2026-11-07 — one Deactivate User entry point (moved from owed.md)
The owed.md row “Decide whether a user’s Deactivate and Offboard become one entry point” (Nanndish, raised 2026-11-03) was settled by design-system Rev 100 (Nanndish, 2026-11-06): one Deactivate User on the user page deactivates at once, after an sm confirmation, when the user owns nothing and has no direct reports, and otherwise opens the lg Deactivate /users/:id/offboard route are gone. The backend’s refusals and the offboarding endpoints are unchanged (AD #35). Written into F5-c Rev 13 and F5-h Rev 3, and built on forge-et-fe branch feature/ui-rev100.
2026-11-08 — a phase’s build target is one week before its milestone
The lead (Tharinda) set the rule: a phase’s due_date in tracker.yaml is the internal build target, one week before the phase’s milestone_date, the Statement of Work date Empire was given. It replaces “finish building one to two weeks before each milestone”. Phase 1 already matched it (build target Fri 20 Nov, milestone Fri 27 Nov). Phase 2’s build target moved from Thu 24 Dec 2026, set on 2026-09-29 to leave two weeks for the Christmas and New Year break, to Fri 1 Jan 2027 (milestone Fri 8 Jan 2027, unchanged). R-ARCH-001’s capacity figures were worked out against 24 Dec and were not re-run. The question came up when a portfolio report gave 20 Nov as Phase 1’s due date without the 27 Nov milestone; .claude/CLAUDE.md § Active Context now says to report a phase against its milestone, with the build target beside it.
2026-11-08 — every forge-et-iaac PR gets a review; the merged ones audited
The lead (Tharinda) asked for an audit of the forge-et-iaac PRs and set the rule that every PR there gets a review, the DevOps team’s included, with its findings tracked in the harness so that a PR merged without them leaves a row. Until then nothing required one: the app repos’ Forge review check does not cover forge-et-iaac, which has no required checks, and Shyamin Ayesh’s approvals carry no comment.
What the audit found (all 18 PRs, read 2026-11-08):
- #3, #5, #6, #7, #9 and #11/#12 were reviewed by the delivery team, either on the PR or in the plan’s pre-PR or independent review. Their deferred findings already had homes in
owed.md. - #15 and #16 were reviewed on the PR. #15’s three Nits went into F38-i WI-4.1’s change list.
- #4, #8, #13 and #14 merged with no review, only an approval with no comment, and #13 had no approval on GitHub at all. Each got a post-merge review on 2026-11-08, posted on the PR. #8, #13 and #14 were clean, with #8’s one Nit fixed since by #9. #4 has one Nit still open: the triage queue’s own visibility timeout is 30 s while the backend asks for 150 s, now an
owed.mdrow. - #10 changed only documentation and was not reviewed. #1 and #2 were closed without merging.
- The DevOps team’s direct pushes to
dev:- those up to 15 Oct were covered by F38-b’s review of #3 (18 Oct), and F38-d reviewed the workflows;
- the last,
0eee623(dev’s SES identity, 21 Oct), was checked by F38-a WI-3.1 against its AC-5. Its code was read again on 2026-11-08 with nothing to raise; its DMARC record has no report mailbox, which F38-i’sdmarc_report_emailoption adds for production; - none has been pushed since 21 Oct.
The open PRs:
- #18 (F11-g) was reviewed, with no Blocker.
- #17’s change list (16 items, the 16th added today) is open against its unchanged head.
- #11 was reviewed through
f66b7d8.
Every finding from the three that is still open is an owed.md row:
- the lead-ranking queue in the UAT and production overlays;
- #17’s change list;
- three points for production’s first apply;
- validating every overlay in
dev.yaml.
The F11-d and F11-g dead-letter alarm rows in the register were closed as superseded by F38-i decision 26.
What changed in the harness:
- a new
iaac-revieweragent (.claude/agents/iaac-reviewer.md), whose checks cover what the merge’s-auto-approveapply replaces or destroys,base/defaults, the other overlays, IAM, data exposure, cost, the backend’s contract, the workflows and Terraform hygiene; /forge-review-prnow takesforge-et-iaacPRs. It runs the checks in every overlay, dispatches the agent, and posts the verdict as the record. A merged PR that was never reviewed gets a posted post-mortem, with each finding checked againstdev;- the rule is in
.claude/rules/forge-et-iaac.md, with a line each in.claude/CLAUDE.md § Quality Gatesandgit-conventions.md.
2026-11-09 — Pipedrive runs may update an archived or made-primary record (moved from owed.md)
The owed.md row “Confirm the Pipedrive runs may update an account or contact a person archived, or made primary” (raised by the F4-b-WI-1.2 plan and its review, 2026-11-06) is settled: Dinil, owner of F4-b, accepted the behaviour as F4-b spec FR-15 states it. Only a person’s change to a field the mapping carries makes a record changed in the CRM, so (a) a later Pipedrive run still writes Pipedrive’s name and field changes to an imported account or contact that a person archived (it stays archived), and (b) when a person made a contact primary and Pipedrive later moves that person to another organisation, the run moves the contact and ContactService clears its primary flag, leaving the old account with no primary contact. No spec, plan or code changes.
2026-11-09 — a Change Owner result keeps silent about a record that left the list (moved from owed.md)
The owed.md row “Decide whether a Change Owner result should mention a selected record that the run did not send” (raised by the F32-c WI-2.2 plan review, 2026-11-08; F32-c finding F-002) is settled: Tharinda, as lead, kept the current behaviour. With an “all N” selection, runChangeOwnerPass (forge-et-fe src/lib/bulkReassign/changeOwnerPass.ts) reads the rows again on confirm with the list’s filters, so a record that left the filter after the selection is not sent (and one that joined it is), and the result reports only what moved, was already the new owner’s or failed — as F32-c FR-9 states. The rare mismatch between the dialog’s count and the result is left unexplained; a person can re-filter the list to check. No spec, plan or code changes; F32-c WI-2.2’s journey already asserts this behaviour.
2026-11-11 — the client demo’s local setup cleaned up (moved from owed.md)
The owed.md row “After the client demo of 2026-11-10, clean up the demo’s local setup” is done. On
2026-11-11 Tharinda had the leftovers removed: the workspace’s pwa-poc-demo/ folder, the merged
worktrees/demo-kit/ and worktrees/pwa-current-data/ worktrees and their branches, and
forge-et-be’s .local/postgres.demo-with-test-rows-2026-11-10, the demo database a triage run had
filled with test fixtures. The database decision: keep .local/postgres, which holds the demo’s CRM
set for the next demo, and keep .local/postgres.before-demo-2026-11-10, the test database from
before the demo, to restore when wanted (demo-kit/README.md § A local CRM as a fallback). Later
demos run from demo-kit/ on main.
2026-11-12 — a selected browser run before a frontend PR into main is ready (moved from owed.md)
The owed.md row “Decide how to stop the nightly run finding the same kinds of failure” is settled.
The lead accepted the three recommendations of .forge/design/harness/fewer-nightly-reds.md
(Draft 2): a frontend PR into main runs pnpm e2e:gate --selected on its final head before it is
marked ready, with the line in its test evidence (R-1); runs it again when main gains a merge in the
same feature area (R-2); and frontend-reviewer searches the tests for every string, test id and
token the diff changes (R-3). PRD Rev 93 records it; still no full gate on a PR into main. A CI
check of the line was left for a later decision, because it changes a workflow file.
2026-11-12 — a failed AI Draft chunk asks for a reload (moved from owed.md)
The owed.md row “Make a failed load of the compose dialog’s AI Draft button recoverable” is
settled. A browser keeps a failed dynamic import for the life of the page (BUG-139), so Try Again
could never load the button. The lead chose to say so rather than retry: when the chunk cannot load,
the place shows “AI draft couldn’t load. Reload the page to use it.” with no Try Again; any other
failure still reaches the place’s error fallback with Try Again. Built in forge-et-fe#512, with test
rows for a failure before and after the place mounts, the other-failure path and the latest-load guard.
2026-11-12 — no other CRM dialog loses focus on Tab as BUG-402 did (moved from owed.md)
The owed.md row “Check the CRM’s other dialogs for a node removed while focus leaves a field” is
done. BUG-402’s cause (L-284: a node removed while focus is leaving a field makes Radix’s focus scope
focus the dialog itself) was checked in the seven dialogs that have blur handlers. First by reading
the code: their blur errors and hints go through Field, which updates a text node in place rather
than removing one. Then by a browser probe on forge-et-fe main (fe35c3d), Chromium, against a
main backend. It walked each dialog by Tab from every control, twice: once with the fields left
empty, so errors appear on blur, and once with a character typed into each text field first, so
suggestion lists open and close. The page states were account-detail-add-follow-up
(FollowUpDialog), leads-new-form and leads-lead-edit (LeadFormDialog),
pricing-weekly-correct (CorrectPriceDialog), pricing-edit-dates (EditSaleDatesDialog),
pricing-import-new-sale (NewSaleDialog), pricing-add-dialog (StandardFormDialog) and
pricing-weekly-withdraw (WithdrawDialog). Focus never went to the dialog element in any of the 16
walks, so no bug was filed. The probe was not committed. L-284 and frontend-reviewer dimension 18
keep the pattern in view for new dialogs.
2026-11-12 — Empire’s Pipedrive exports hold no _xHHHH_ escapes (moved from owed.md)
The owed.md row “Find out whether a Pipedrive export writes _xHHHH_ escapes” (raised by
BUG-405’s fixture probe) is settled. Tharinda ran the check on Empire’s three Pipedrive exports
(organizations, people as Contacts.xlsx, leads), held on the lead’s machine and not in any repo,
and on a weekly auction-prices workbook. None holds an _xHHHH_ escape in its sheets or shared
strings, so fastexcel-reader not decoding them loses nothing, and no bug was filed. The same pass
counted what BUG-405’s cleaning (forge-et-be#413) changes in the real data. Of about 51,000 text
values, two people’s values hold a tab or a line break. None holds a C1 control, U+2028, U+2029 or
any other control character. The leads export writes its text as t="str" cells (the text in
<v>), not shared or inline strings. Counts only were read; no value left the machine.
2026-11-12 — the capture app’s screens drawn and accepted (moved from owed.md)
The owed.md row “Draw the capture app’s intended design in pwa-current before F36 is specified”
(Nanndish, assigned by Tharinda on 2026-11-11) is settled. pwa-current is on the CRM’s theme
(version 2, the brand accepted 2026-11-11) and is built from pwa-current/source/; it now draws the
screens and flows agreed on 2026-11-12 — Microsoft sign-in with capture.use, Leads in To Review
and Completed with their own search and filters, one capture at a time with Submit for Research,
in-app notifications, a campaign-first Plan with search, filters, sort and exhibitors added, edited
and archived, the list upload without AI, booth visit notes, and Settings of install and account
only (.forge/design/prototypes/README.md § The capture-app screens and flows agreed on 2026-11-12).
F36-e and F36-f were dropped, so F36-a to F36-d are the screens drawn. Tharinda accepted them on
2026-11-12 (reported by Nanndish), in forge-et-harness#1325. demo-kit still runs the POC’s own
screens. What the decisions change in the PRD and the F36 specs stays in owed.md.
2026-11-13 — the minute scheduled-email-send sweep is budgeted against the queue’s timeout (moved from owed.md)
The owed.md row “Fit the minute scheduled-email-send sweep to the scheduler queue’s 30-second
visibility timeout” (Dinil, raised by the review of forge-et-iaac#19 on 2026-11-09) is settled by the
first of its two options: the handler is budgeted, and the queue’s timeout stays 30 s. forge-et-be
main’s docs/messaging/scheduler-cloud-contract.md (the scheduled-email-send entry and the
paragraph “Each run budgets itself”) says the sweep starts no new send after half of
et.messaging.visibility-timeout. It also says why a run can still outlast the timeout: up to 4 sends
can be under way, each with F20-c’s 2-minute limit when it carries files. Such a run is received again
while it is still running, and the two runs overlap safely, because every claim and outcome write is a
conditional update (F20-g WI-1.4 plan Decision 15). A firing dead-lettered after 3 receipts loses
nothing, because the next minute’s firing reads the same rows. forge-et-iaac#19 merged on 2026-11-12
(4b3d883e) with no change to base/sqs/scheduler.tf. The F20-g WI-1.4 plan’s ### For the orchestrator item (a) asked for this row to be removed, and nobody had done it. The post-merge
review on 2026-11-13 checked the contract entry against the row and removed it. The row for applying the UAT and production overlays with a backend that
has F20-g wave 1 stays in owed.md.
2026-11-13 — a converted capture is not researched twice (moved from owed.md)
The owed.md row “Decide whether a converted capture is researched twice” (raised by F36-a’s spec
review) is settled by F36-c’s spec (FR-CV1, FR-CV2, decision D-6). The spec was drafted under
Nanndish’s overnight delegation, approved after /forge-spec-review on 2026-11-13, and confirmed by
him the same day. When a person converts a captured lead whose research is complete for the same
company, website, country and contact name, the conversion copies that research into the new CRM
lead’s lead_research row. F11-c’s queued job then finds it complete and makes no search and no AI
call. F11-g still ranks the CRM lead and F11-d still triages it. The copy saves about 1.25 US cents a
converted lead (one Exa search and one research call).
2026-11-13 — weekly pricing is finished without more input from the Tea Room
A review of the weekly pricing features (F26-a, F26-b, F26-c, F26-d, F26-f, F26-g) against the meeting notes found that the Week 35 workbook was never walked through with Empire’s Tea Room (the 9 September action item), so five points about their practice were never confirmed:
- what a blank cell in the workbook means — about half the cells are blank each week — “not offered this week” or “same as last week”;
- whether a sale’s prices are set before the sale or after it, from its results;
- the unit of the workbook’s figures (OQ-59; the CRM reads them as rupees per kilogram);
- whether their online auction system, which they said is linked to their ERP and has a public API
(
2026-08-03-requirements-clarification.md), could supply prices (theAuctionPriceProviderseam answers “no suggestion” in V1); - whether two auction sales can ever start on the same day (the CRM accepts it, and takes the sale with the higher number as the current sale).
The lead decided that no more input is expected from Empire on these, and that the CRM stays simple
and flexible for them to use as they need, with nothing built on a guess. The CRM already works either
way on the first two: Carry Forward All keeps every price missing from a round, and a round
published after its sale has started applies from that day. A rule refusing two sales on one day was
considered and not built. The Tea Room guide, .forge/client/user-guide-weekly-prices.md, describes
both ways of working. A change follows feedback from use or from UAT.
No screen text was added to explain withdraw, correct and carry forward: each round row already offers
only the action that fits the price (Withdraw before it starts, Correct once it applies, with
“In effect since
Settled under the rule below, and moved from owed.md: the row “Ask Empire how the weekly price
email should name the week, and confirm the unit of the final price” (Tharinda, raised by the F26-d
spec on 2026-10-16) is not taken to Empire. The email keeps naming the week by the sale, the week of
13 October 2026 (Colombo auction sale 42), and states each final price in US dollars per kilogram,
as built; a different wording or unit is a small change to F26-d if Empire asks at UAT. Also decided
on 2026-11-14 and recorded in BUG-422’s plan: a past or today start stays allowed on Add a sale
and becomes allowed on Edit sale for a sale with no published price, and there is no Start now
or End now button.
The same review checked the daily price-expiry-sweep on dev (read-only AWS calls on 2026-11-12):
it completed every night from 6 to 12 November (.forge/cloud-gated-validation.md § Log).
2026-11-13 — no questions to Empire before UAT
The same day, the lead widened the pricing decision above to the whole engagement: no questions go to
Empire for now. The delivery team implements what it judges best: the simplest option for Empire’s
staff to understand, minimal, practical for how they are likely to work, and flexible enough to
support the ways they might use it. Changes Empire asks for at UAT are made then. The rule is in
.claude/CLAUDE.md § Active Context and .forge/active-context.md. F37-a’s three questions that
were to be taken to Empire at the 27 November meeting are now the delivery team’s, each with a
suggested starting point in the F37-a spec’s ## Open Questions; the meeting itself stays in
owed.md.
2026-11-14 — corrections to the weekly-pricing records after a fresh review
A fresh-context review of the documents the 2026-11-13 entries above produced, checked against the
code on main, found these points, all now corrected in place:
- Pricing after the auction does not work without a gap. The entry above says the CRM already
works whichever way the Tea Room sets prices. From a sale’s first day the sweep ends every earlier
price the sale’s round does not replace, so a round published later in the week leaves those
standards with no current price from the sale’s start until the publish (F26-g FR-2, FR-15’s own
warning text). The Tea Room guide now advises publishing before the sale starts, using
Carry Forward All and then Correct when the round is not ready, and
active-context.mdsays the same. BUG-423’s notice keeps this consequence instead of dropping it. - The guide now quotes screen labels as they are shown (Title Case), splits Withdraw and Correct at today (a price that starts today shows Withdraw), and uses the price email’s own left-out reasons.
- BUG-422’s plan gained the sweep’s lock (it assumes a started sale’s dates cannot change) and the
sale list’s
canEditDates/earliestStartsOn, which decide what the screen offers; its Fix and Regression test lines now cover the end-date edit and the other new cases. - F26-d spec Q-1 and Q-2 record the 2026-11-13 decision (wording and unit kept as built).
active-context.mdno longer calls the Exa choice provisional (Empire chose Exa on 2026-11-10), and says the existing “Ask Empire …” rows inowed.mdand the open OQs wait for work to reach them, as the delivery team’s decisions.
Two 2026-11-14 decisions were written into the 2026-11-13 entry above by mistake rather than here: a past or today start stays allowed on Add a Sale and becomes allowed on Edit Sale for a sale with no published price, and there is no Start now or End now button (both in BUG-422’s plan).
2026-11-14 — forge-et-iaac#19’s approval was given outside GitHub (moved from owed.md)
owed.md’s row “Confirm Shyamin Ayesh approved forge-et-iaac#19” is closed by the lead: Shyamin
approved the PR outside GitHub, as he did for forge-et-iaac#13, so the merge met
.claude/rules/forge-et-iaac.md. Its approve review record (38cfc37, 2026-11-09) is on the
merged head, with no open finding; the one follow-up it raised, the sweep’s fit to the scheduler
queue’s 30-second visibility timeout, was settled by F20-g decision 15. Read on dev on 2026-11-14:
the schedule is ENABLED at rate(1 minute), et-dev-scheduler and et-dev-scheduler-dlq both
hold no message, and the backend’s log has no ERROR line naming scheduled-email-send in the
past 24 hours.
2026-11-14 — one release per phase’s UAT round (moved from owed.md)
The lead settled how Phase 1’s UAT round is tracked, which owed.md held for him before Phase 1
seals. The tracker’s single release: object, written for one round after the last phase seals,
became a releases: list with one release per phase’s round: P1 (Phase 1’s round, 30 Nov – 10 Dec,
run while Phase 2 is built) and P2 (the final round, whose sign-off is V1 sign-off). What Empire
raises is still logged first as a UAT-NNN issue and sorted by kind. An accepted defect becomes a
BUG-NNN scheduled into the phase being built, so Phase 1’s defects get delivery_phase: 2 and keep
Phase 2 from sealing until they are fixed, and only a round run after the last phase seals gives
delivery_phase: null. An accepted change request becomes a feature in Phase 2 or later, never a
bug, and whether it is priced under the proposal’s §16 is the lead’s call for each one. RC-n and
UC-n cycle ids now run across releases. The rules are in .claude/rules/tracker.md § Release & UAT Lifecycle and § Bug Tracking, and /forge-release, the dashboard, check-unique-ids.py and
id-numbering.md follow the list.
In the same session the lead decided that P1 may stay open while Phase 2 is built and P2 opens
(its fixes are re-tested as UC-1 round 2, on the round’s environment while it is up or on a later
one), and that a UAT environment is removed by hand, never on a schedule: the round’s end date
(10 Dec for Phase 1) is a planned date, and a person runs uat.yaml destroy once the lead decides
the environment is no longer needed. uat.yaml already runs only when started by hand, so no
infrastructure changed; the docs that said “destroyed after the round” now say how.
2026-11-15 — a price email whose sale changed is refused before it is sent, and the sale’s foreign keys are indexed (moved from owed.md)
The lead settled the two owed.md rows forge-et-be#430’s review raised. A price email being written when
its sale is deleted: the send is refused before it leaves, rather than recorded against the current sale.
The check also refuses when another sale has become this week’s, because such an email lists the wrong
week’s prices. It is BUG-435, fixed in forge-et-fe#538 (F20-c Rev 14, F26-d Rev 5, F26-g Rev 6). The
price_email(auction_sale_id) index: approved and added in forge-et-be#437 (V72). The same migration
indexes buying_standard_cost(anchor_sale_id), partially, because a sale delete’s foreign-key check scans
that table too.
2026-11-16 — the three type-scale PRs merged in order (moved from owed.md)
The six-size type scale (12 to 24px, design-system Rev 109) landed in the order the hand-over set:
forge-et-fe#485 on 2026-11-15 (cb6b48b), forge-et-pwa#116 on 2026-11-16 (de2d671), then this
harness record, forge-et-harness#1266. forge-et-fe main changed two shared test files before #116
merged (BUG-425, BUG-427), so #116’s shared-file record was re-taken from #485’s merge commit, as the
row foresaw. #116 also merged main in (F36-a waves 1 and 2) and moved every capture-app h1 onto
PageTitle.module.css alone, with a test that fails on an h1 without it (pageTitleOnly.test.ts).
2026-11-16 — the nightly run’s backend has the card-read queue keys (moved from owed.md)
At Dinil’s request, Tharinda added et.messaging.card-read-queue: et-card-read and
et.messaging.card-read-dlq: et-card-read-dlq to the application-local.yml of the primary
forge-et-be checkout on the Mac that runs the nightly full run, which .claude/lib/nightly/run-nightly.py
copies into the nightly backend’s worktree. The names are the ones F36-b-WI-2.1’s approved plan adds to
application-local.yml.example (Decision 14), and the ones F36-b-WI-3.5’s plan passes on its bootRun
line (Decision 15). The file was checked by key names only, and still parses with the two keys under
et.messaging. This is the lead’s confirmation that F36-b-WI-3.6’s plan asks for before F36-b wave 3’s
forge-et-pwa wave PR is marked ready (/forge-deliver Stage 12); WI-2.1 has not merged, so .example
on main does not have the keys yet, and if WI-2.1 changes the names, the nightly run’s config_note
names the missing key.
2026-11-18 — F11-i’s overnight decisions reviewed (moved from owed.md)
Dinil reviewed F11-i’s overnight decisions on 2026-11-18 and confirmed all of them, and every approval made
under his overnight delegation of 2026-11-17 (the spec, the Decomposition Plan, the WI-1.1 to WI-1.4 plans and
the multi-plan answer), except D-9, which he replaced: the person-search switch is on in every environment with
no precondition, because Empire agreed to this approach on 2026-11-10 (F11-i spec Rev 3;
.forge/plans/F11-i/F11-i-overnight-log.md § Morning review). The rule that asked for Empire’s written
agreement and Exa’s data processing agreement, or the switch off, before Empire’s leads entered an environment
is withdrawn; the agreement and the DPA stay owed in owed.md, not as a gate.
2026-11-18 — a budget-deferred F37-a item keeps its first_attempted_at (moved from owed.md)
At F37-a’s Reflect, Tharinda decided to leave the price broadcast sweep as built: an item the
price-broadcast-send run claims but defers unsent, because the run’s 15-second budget ran out, keeps
first_attempted_at, so FR-S5’s 30-minute rate-limit window can start before any send was tried. It is
harmless at the expected pace (one sender’s batch at 20 a minute fits the budget), and a change Empire
needs after UAT is made as ordinary work. Raised by the F37-a-WI-1.3 build on 2026-11-16 (its plan’s
## Notes); the wave PR’s review (forge-et-be#446) did not take it up.
2026-11-18 — open Reflect follow-ups settled (moved from owed.md)
Tharinda asked for the open Reflect follow-ups in owed.md to be checked and settled. These rows were
settled without a code change:
- Stage 14 and a repo whose work-item PRs merged into the plan branch (F1-c finding F-005) no
longer applies. Since 2026-10-26 (
d13654e6, “let /forge-deliver run a harness-only sub work item”), a work item may listforge-et-harnessonly as its sole repo (forge-worktree-uptreats a harness row beside an app-repo row as a plan defect). Its branch is cut fromorigin/main, and Stage 11 Pass 1 merges it into the harness wave branch. Stage 14 then reads that wave’s PR like any other (F37-a wave 1’s harness half shipped as forge-et-harness#1441), so it needs no rule for a harness work item merged intofeature/<TICKET>-plan. - The lead half of the Pipedrive write run (F4-b) is built: forge-et-be#383 merged on 2026-11-07,
with
MigrationLeadWritertaking the run’s up-front locks and resolving labels throughMigrationTagResolver, and F4-b closed with all its criteria ticked. - Closing F3-a: AC-30d now cites the first scheduled green night after forge-et-fe#445 (2026-11-15), and Biseni was told of F1-c Rev 4 (her spec, written at F3-a’s close) in a comment on the PR that added this entry.
- F3-a’s three points from forge-et-fe#353’s review are recorded as intended, as the row allowed:
N5, a page change on
/activitieskeeps the page notice, matches WI-2.2 plan Decision 10, which clears the notice only on its Dismiss, the next row action and a filter change; N6, a row kept during a filter change keeps Mark done until a re-read succeeds, and a second press is a harmless200; the edit dialog’s load error is titled Follow-up because, with the record unread, it cannot yet show an edit form. - F3-a’s count tests at Colombo midnight (
ActivityCountsIT,ActivityVisibilityParityIT) are left as they are, as the row allowed: the window is the milliseconds between the fixture and the request, crossing 18:30 UTC exactly; the nightly full run starts at 02:00 Colombo time. A failure seen in a run is a bug (.forge/test-strategy.md § Flaky Tests), and its fix is the existingcolomboDatesSincehelper inActivityBaseIT, which other activity tests already use.
2026-11-18 — the compose dialog’s early “Enter at least one address in To” explained (moved from owed.md)
F20-h finding F-006 saw the To field’s error on one compose open before anything was typed. The
code explains it, and it is not a defect. The dialog opens with focus in To (forge-et-fe
ComposeEmailDialog.a11y.test.tsx, “starts on To”). ComposeFields.tsx marks To as touched on its
blur, and useComposeFields.ts shows a field’s error once it is touched. So anything that takes
focus out of To before typing shows the error: a click elsewhere in the dialog, or switching to
another window, which also blurs the focused field. That is the “validate on blur” rule in
design-system §5, Form fields and validation: the field was focused and left. Read on 2026-11-18 at the request
of Tharinda, who asked for the open Reflect follow-ups to be settled; the row was Dinil’s.
2026-11-18 — a campaign focus for the capture app’s ranking, and the ranking carried into the CRM
Dinil (F36-c’s owner) and Claude discussed how the capture app’s ranking reaches the CRM, and the lead (Tharinda) agreed the outcome the same day, as Dinil reported it; PRD Rev 101 records it. Until now a captured lead was ranked twice: the app ranked it Hot, Warm or Cold with a 0–100 score (F36-c), and at conversion the CRM discarded that ranking and ranked it again (F11-g; PRD Rev 98), so one lead could get two priorities. Decided:
- At conversion the app’s ranking becomes the CRM lead’s priority (Hot P1, Warm P2, Cold P3) with its confidence, reason and next action; the CRM does not rank it again then. The 0–100 score stays in the app, because nothing in the CRM sorts or filters by it.
- A campaign can carry an optional focus, a short note such as Private-label buyers in the EU, that the AI ranks the campaign’s exhibitors and captured leads for, on top of the standard rules (the POC’s campaign “lens”, which F36-c’s spec had left out). It is passed to the AI as data, with a length cap the spec sets.
- The focus may change the tier, and so the priority (option A). The alternative, keeping P1–P3 on the standard rules and showing the focus as a separate “focus match” badge (option B), was set aside: to the sales team P1 means “chase this first”, which is what a show’s focus is for.
- A ranking made with a focus shows it: the AI’s reason mentions it where it mattered, a fixed line gives the focus text and the campaign’s name, lists mark the lead with a tooltip that opens on hover, tap and keyboard focus, and the CRM’s lead list filters on it.
- The focus text is kept with the ranking, so a later ranking in the CRM uses the same focus.
- Editing a campaign’s focus ranks its exhibitors and its leads still to be reviewed again (the ranking only, not the research); converted leads keep theirs.
- Not raised with Empire Teas: the delivery team decides it inside F36’s agreed scope (Dinil).
- Built now, in Phase 1, as a further F36-c wave after wave 2, which another session is building and which
carries on unchanged; not a separate feature. The work owed is in
owed.md.
The iOS install card was discussed in the same conversation; Nanndish (F36-a’s owner) is already changing it.
2026-11-18 — owed.md triaged; 17 rows checked done and removed (moved from owed.md)
At the lead’s request, every top-level row of .forge/owed.md (372 on origin/main d61821de1) was
listed with its owner, kind, priority, features, date raised and a status in
.forge/audits/2026-11-18-owed-triage.md. Each row a script flagged, and each with a written close
condition, was checked against its source (forge-et-be, forge-et-fe and forge-et-pwa main,
forge-et-iaac dev, GitHub and tracker.yaml, fetched that day). Seventeen were done and are removed;
the audit file says how each was checked:
- UI rows done by merged
forge-et-fePRs: the Rev 77 confirmation order and the danger-outline triggers (#476, 10 Nov); the Rev 90 frame’sComboboxcheck (#476); the tag-table Colour column, the Deactivate User flow and the lead page’s card order (#442,feature/ui-rev100, 8 Nov); the tag rows’ ⋯ menu (#355,feature/ui-revamp, 29 Oct); the Email folder column’s selected row, which now has the inbox list’s fill and bar; and the F20-h seam spec’s header, which now says 60 tokens. - F38 rows: Empire’s yes to a UAT environment, recorded in F38-h spec Rev 8; forge-et-iaac#11 merged
(13 Nov), F38-h waves 1 and 3
mergedandfeature/F38-h-wave-1deleted; UAT’s database zone, ondevwith #11; F38-i’s plan for FR-19 namingoverlays/uat(WI-8.1); F38-i’sdeploy-prodwave gated on F38-h wave 4; the narrowed deploy user’s two actions, overtaken by one CI user withAdministratorAccess; and where the deploy workflows read their targets, closed by F38-h wave 4 (the dev half stays in its own row). - The per-page Settings permissions, which
client-facing-prd.md§2 androles-and-permissions.mdnow state.
Four rows were narrowed to what is left: the convert line’s brackets (the capture app is done; the
prototype is not), the file-size check (the two frontend checks are on main; the backend’s is not),
the seeded-administrator wording (forge-et-be CLAUDE.md is done; two documents are not), and the
folded Settings permission (now only whether the proposal gains a note). Forty-three rows that look
stale but could not be shown done are listed in the audit for the lead.
2026-11-19 — the lead’s stale owed.md rows decided (moved from owed.md)
The lead decided the ten rows of their own that the 2026-11-18 triage marked as looking stale
(.forge/audits/2026-11-18-owed-triage.md, rows 39, 131, 132, 141, 142, 160, 218, 239, 282, 296):
- Won’t-do, removed: the F32-d saved-view name’s two
INVALIDrefusals keep one code, and the CRM telling them apart by the message is accepted as built; F20-d’s three general starter templates stay as seeded, for Empire to edit or delete on the Templates screen; F11-h’s draft price check keeps its plan’s list (Decision 15), with the prompt and the dev evaluation set as the other controls. - Closed on evidence, removed: F38-d AC-11 is ticked on the repository’s setting —
aws ecr describe-repositoriesreadcrm/backend IMMUTABLEon 2026-11-19, and the lead accepted it as the evidence (F38-d spec Rev 6,environments-and-identity.md§4 row 8). F11-c AC-29’s WebKit source-link walk ran on a Mac in the scheduled nightly full run of 2026-11-18 (forge-et-fe6b53f6dd, the CRM gate passed, both tests oflead-research-keyboard-webkit.spec.tspassed), recorded in.forge/plans/F11-c/F11-c-WI-1.6-test-verify.md. - Reassigned: F11-d’s duplicate rule for the final Pipedrive run and its two-word legal-form match to Dinil; email from the contacts page and for a contact with no account to Biseni, F1-f’s owner.
- Kept as they are: the two rows on applying the UAT and production overlays with the
scheduled-email-sendandprice-broadcast-sendschedules. They name done features, but their production half, and UAT’s next-rcfor F37-a, are still ahead.
2026-11-19 — the lead’s first owed.md decisions for UAT and the hand-over (moved from owed.md)
The lead went through the first of their own open owed.md rows by multiple-choice questions:
- The hand-over meeting: the Phase 1 hand-over and UAT drop 1 are one meeting, about Mon 30 Nov at
Empire’s office; Phase 2 scope follows if time allows. The things to tell Empire and the questions to
ask it are collected in one new
owed.mdrow with drafted points; nothing is sent automatically. The detailed sales-team presentation Kavindu asked for on 16 Oct is replaced by UAT drop 1 (row removed). Empire IT’s production asks wait until production is needed. - The Phase 1 acceptance criteria: issued at that meeting, after the delivery team rewords H3, C5 and I3, adds criteria for every completed Phase 1 feature the draft does not cover, and adds each Phase 2 feature built early once it is done.
- The non-functional checks: all six adopted, ZAP approved as a new tool (
test-strategy.mdRev 44; row removed). - Criterion D1: shown with an empty Unassigned filter (
uat-data-checklist.mdrow D1; row removed). - The smoke after a DevOps push to
main: run by whoever checks that push after the fact (git-conventions.md § Branch Protection; row removed). - Deploy workflow step names:
area::action, recorded incoding-standards.md§7.1 (row removed). - Closed as done: the UAT and production alarm sets (F38-i spec decision 26 and FR-11 record
them); the Haiku 4.5 quota and pacing row, since F42 paces the backend’s Bedrock calls and the quota
stays in the Bedrock new-account-limits row. (The question put to the lead also named F43 as built;
F43 is still at
spec, which does not change the answer.) - Decided, work left in their rows: re-plan F38-i waves 8 and 9 to go ahead while
forge-et-iaac#17 is held; add overlay validation to
forge-et-iaac’sdev.yaml; expire the web buckets’ old versions after 30 days, before production.
2026-11-19 — the Phase 1 acceptance criteria brought up to the built CRM
At the lead’s request, the draft client/phase-1-acceptance-criteria.md was checked against the
Phase 1 features that are done (tracker.yaml) and corrected before it is issued at the hand-over
meeting:
- Corrected to match what is built: C5 (only a completed follow-up is on the account timeline), H3 (a lead has no timeline), H1 (a follow-up can be assigned to a colleague, F3-a), I3 (an imported organisation that matches an existing account keeps that account’s owner, F4-d), and E1 (the person search can be turned off on the Settings page, F11-i).
- Added for built features the draft missed: C8, several email addresses for one contact (F20-l); F10, files attached to an email (F20-h).
- UAT data and sign-ins are Empire’s choice. The lead decided that Kavindu chooses, before drop 1, whether UAT holds no data, made-up records or real Pipedrive data, and whether testers use the test logins or their own mailboxes, after being told the risks of each. This replaces the position of 2026-11-18 that UAT holds made-up data only. The draft’s “Who signs in” and “With what data” lines now leave both to Empire, and the criteria that need Pipedrive’s data are shown on production at the first load if UAT does not hold it.
- Two UAT deliveries: “How the criteria are tested” lists F3, F6 and F7 as arriving in the second delivery.
- E3 kept; E8 kept and to be built: the lead confirmed E3’s wording, and chose to summarise
migrated leads from their linked past email so that E8 holds (new work, an
owed.mdrow).
2026-11-19 — F37-b started early, and when unfinished started-early features move back
The lead took F37-b (bulk email to a saved contact list) into Phase 1 to start early, now that its blockers F37-a, F32-d and F20-g are done, and claimed it (forge-et-harness#1542). Its spec decides OQ-62 under the rule of 2026-11-13 (no questions to Empire before UAT), and Empire is asked to confirm the choices at the hand-over.
The lead also set when an unfinished started-early feature moves back to Phase 2: at the end of Empire’s Phase 1 UAT round, not before Phase 1 seals as decided on 2026-11-06 (PRD Rev 84). F23-d and F37-b can therefore go out in UAT drop 1 or drop 2; each one not done when the round ends moves to Phase 2. F38-i keeps its own rule. The tracker’s Phase 1 and Phase 2 themes were brought up to the scope accepted so far (list views, attachments, email tracking and scheduled send, and the price broadcast in Phase 1). PRD Rev 102 lists every document changed.
2026-11-19 — Phase 1 seals at the end of its UAT round (moved from owed.md)
The review of PRD Rev 102 found that the tracker’s rules could not hold for Phase 1. They seal a phase
only when all its features are done, and open its UAT release only after the seal. But UAT drop 2
carries Phase 1 features (F20-f, F20-j, F44) through Empire’s testing, and the started-early F23-d
and F37-b stay in Phase 1 until the round ends. Of the two options put to the lead, the lead chose to
seal Phase 1 at the end of its UAT round rather than add an exception for the release.
.claude/rules/tracker.md § Delivery Phase Rules now says how: Phase 1 stays in-progress, release
P1 opens early for drop 1 on the entry gate’s ASK-FIRST path, and a UAT defect fixed in drop 2 is
delivery_phase: 1. /forge-release step 4 files defects the same way. Phase 2 stays locked until
the seal; whether its features may start during the round without a per-feature ask is a new
owed.md row for the lead.
2026-11-19 — Phase 2 features may start during Phase 1’s UAT round (moved from owed.md)
Asked in the session, the lead approved the whole of Phase 2 at once: while Phase 1 stays
in-progress through its UAT round, any Phase 2 feature may advance to dev from UAT drop 1 on
without the per-feature ASK FIRST that a locked phase otherwise needs. The approval is recorded in
Phase 2’s notes in tracker.yaml and in .claude/rules/tracker.md § Delivery Phase Rules, and it
lasts until Phase 1 seals, when Phase 2 becomes in-progress as usual.
2026-11-19 — the backend’s analyzers upgraded on a Temurin 21 toolchain (moved from owed.md)
The lead chose to unblock the held Error Prone and NullAway upgrade by having Gradle download Temurin 21
for the build, instead of moving to JDK 25 (forge-et-be#487). Two owed.md rows closed with it:
- “Upgrade Error Prone and NullAway in
forge-et-be”: Error Prone 2.38.0 → 2.53.0 and NullAway 0.12.7 → 0.14.4, the toolchain onJvmVendorSpec.ADOPTIUMwith the foojay resolver, and-XDaddTypeAnnotationsToSymbol=trueoncompileJava. The Guava constraint for CVE-2026-102554 went, because Error Prone 2.53.0 brings the fixed Guava, and Dependabot proposes the pair again, in a group of their own. - “Remove BUG-237’s cause when the backend’s analyzers next move”: its default had been JDK 25
everywhere (Tharinda, 2026-10-21), with a JDK 25 compiler and
--release 21as the fallback. The flag on Temurin 21.0.8 or later removes the same cause: a javac experiment during forge-et-be#487’s review on 2026-11-19 showed that javac then readsList<@Nullable String>from a class file, where Temurin without the flag and Oracle 21.0.10 with it readList<String>. So the §7.2varrule, itsbackend-reviewerrow and backendCLAUDE.mdrow, andscripts/check-incremental-compile.pywere retired, and the backend stays on Java 21 (AD #1). Moving to JDK 25 is no longer needed for BUG-237; it would be its own decision.
2026-11-20 — F20-i’s Graph Explorer checks dropped (moved from owed.md)
F20-i-WI-5.1’s laptop walk could not run its five direct Graph checks (record R-17): signing in to
Graph Explorer as CRM01 needed an Empire administrator’s approval. The lead decided on 2026-11-20 not
to ask Empire IT, because none of the five covers something a rep is likely to meet, so the owed.md
row “Run F20-i’s Graph Explorer checks once Empire IT approves Graph Explorer for the test accounts” is
closed as won’t-do. The five, and what happens to each:
GET /me/mailFolders/deltalists the folders the tree shows (forge-et-be#356 review): only for a later speed-up of the folder-tree read; nothing depends on it today.contentIdselectable on the attachment list (WI-2.1 E-9): efficiency only; inline pictures resolved in the walk (R-13).- Graph’s own error code for a well-formed but invalid id (WI-2.1 E-8): the CRM’s
404was confirmed in the walk (R-13). - A message in a hidden subfolder reaching All mail (forge-et-be#369 review) and the
archivelookup on a mailbox without Archive (WI-2.1 E-5): the two a rep could meet, now §B F20-i row 8 in.forge/cloud-gated-validation.md, watched for on dev and in UAT and filed as a bug if seen.
CRM04, the one test account without Archive (it had no Exchange licence and so no mailbox), is
being given its licence again by Kavindu Anthony, at the lead’s request; it has lost it before.
2026-11-20 — F20-k and F22 taken back into Phase 1, started early
The lead took F20-k (email block lists) and F22 (contact sync) back into Phase 1 to start them early. Both had moved to Phase 2 on 2026-11-11, not started. They follow the started-early terms of 2026-11-19: each stays in Phase 1 through Empire’s Phase 1 UAT round; if it is done, it goes out in a later UAT drop and joins the Phase 1 acceptance criteria; if it is not done by the end of the round, it moves back to Phase 2. F20-k waits on F20-f and F22 waits on F20-i, both Phase 1 work still open, so neither can start before them.
Nothing told to Empire changes: both stay Phase 2 commitments in the client pack until done, as F23-d and F37-b do (PRD Rev 102). The PRD body names no phase for either, so it has no revision.
The same change brought the tracker’s phase themes up to date. Phase 1’s theme now names email
linked to records, the follow-up for an unreplied customer email (F44) and show planning in the
capture app (PRD Rev 96). Phase 2’s theme now names alerts, outreach sequences, bulk actions and
email block lists, and says that its import and export are the spreadsheet import and the export of
the deal, quote, sample and standard lists. Changed: tracker.yaml (F20-k, F22, both phases),
features.md, active-context.md, owed.md, guides/email-in-the-crm-explained.md,
design/environments-and-identity.md, cloud-gated-validation.md, and the F20-k and F22 spec
stubs.
2026-11-20 — the phase themes and phase statements brought up to the moved features
The lead found the dashboard’s Phase 2 theme still listing contact sync, bulk email to a saved
list and email block lists, which are tracked in Phase 1 as started-early work, and asked that the
phase titles and themes, and every other statement of a feature’s phase, match the tracker after
each move. The titles still fit. The themes were rewritten from each phase’s delivery_phase
list: Phase 1’s first sentence is its own scope, which now also names the buying standards on each
account, the audit trail and the dev and UAT environments; its second sentence names the
started-early work (F23-d, F37-b, F20-k, F22, and F38-i’s production environment), which joins
Phase 1 only when done. Phase 2’s theme lists only features with delivery_phase 2, and gains a
started-early feature back in the change that moves it there.
A search of the harness found four other stale statements: the PRD’s Gate 3 re-grouping note, rows
P-13 and P-24, the Marketing consent line and R-15 (PRD Rev 105); a pointer in active-context.md;
F20-k’s phase in the F20-f spec (its Rev 3); and two lines in the email guide and
feature-detail.md. .claude/rules/tracker.md § Delivery Phase Rules now says what a phase move
updates in the same change. Left as written: the client pack, which keeps a started-early feature
in Phase 2 until it is done (PRD Rev 100, Rev 102); the specs and plans of features already done or
dropped (F20-c, F20-d, F36-f, the F37-a plans); and F37-b’s Phase 2 labels in the prototype,
which F37-b’s delivery redraws (design/prototypes/README.md).
2026-11-20 — a finished started-early feature joins Phase 1 at Reflect
The lead asked whether the rules now keep the documents up to date when a feature’s phase or status
changes, without the lead doing it by hand. A check found the rules in place for a phase move
(.claude/rules/tracker.md § Delivery Phase Rules), for a status change (the features.md Phase
column, checked by check-features-index.py in Repo hygiene), and for the current prototypes (the
plan’s ## UI / Design Adherence, plan-reviewer DC-11 and DC-12, frontend-implementer,
/forge-pre-pr-review and frontend-reviewer item 28). One step had no owner: when a
started-early feature reaches done, moving it into Phase 1’s own scope (the theme’s first
sentence, the Phase 1 acceptance criteria, the client pack and a PRD revision) was an owed.md row
the lead had to remember. /forge-reflect, which closes every feature, now does it as step 5e, and
the tracker rule points at it.
2026-11-20 — F20-i’s large-mailbox checks dropped (moved from owed.md)
Two checks from F20-i-WI-5.1’s laptop walk (record R-8 step 9.6, R-11, R-20) need what the team does
not have: a mailbox with more than 1,000 messages matching one word, a new All-mail search folder
filling over a mailbox of a rep’s size, and a Windows machine with classic Outlook. The test mailboxes
(CRM01–CRM05) hold a few dozen messages, so a fill timed there would say nothing about a rep’s. The
lead decided on 2026-11-20 to keep neither as a task: the team cannot get a rep’s mailbox for testing,
Empire’s staff will exercise both if they use their own mailboxes in UAT, which the team cannot require,
and how classic Outlook shows the folder is not critical. The two owed.md rows — “Measure a new
All-mail search folder’s fill time on a real mailbox, and look at it in classic Outlook” and “Check
F20-i’s 1,000-result search cap on a mailbox that holds more than 1,000 matches” — are closed as
won’t-do. What stands meanwhile: the “still being prepared” line keeps its five-minute window
(GraphMailboxProvider.ALL_MAIL_FILL_WINDOW, spec Rev 6), and the 1,000-result line is proved
against the stub (AC-48b, AC-48c). A problem with either seen in UAT is filed as a bug.