Empire Teas CRM
Project Overview
A custom-built, single-tenant B2B sales CRM for Empire Teas (Pvt) Ltd, a top-five Sri Lankan tea exporter, replacing Pipedrive. It models the tea-export sales process (bulk tea + private-label) as first-class — multi-round sample development, certification-mismatch checks, export-documentation checklists, quote readiness gating — and embeds a human-in-the-loop AI layer (Claude) for lead triage, inquiry extraction, account briefings, and drafting, with a human approving every AI action and setting all pricing. No business role is built in: one editable IT Admin role and its user are seeded by migration (AD #34), and that admin creates every other role from the permission catalog. A recommended set — which Empire may rename, change or not create — is Sales Reps, Sales Managers, R&D/Sample Owners (Tasters), Administrators, Tea Room (the pricing team who set and publish the weekly bulk prices), and Executive/Management (read-only). Sub-floor-margin quotes additionally require Managing Director approval, granted by configuration. See .forge/project-prd.md for the full contract.
Stack
- Backend: Java 21, Spring Boot 4.2.x (Spring Web, Spring Security, Spring Data JPA), Flyway migrations; build: Gradle, Groovy DSL (AD #18). Tests: Spock 2.5-groovy-5.0 — Boot 4.2’s BOM manages Groovy 5, and Spock’s Groovy suffix is a hard compile gate (AD #25)
- Frontend: TypeScript, React SPA on Vite (pnpm) — no Next.js/SSR (AD #21: internal authenticated app, no SEO; enables static S3 + CloudFront hosting). Server state through TanStack Query (lead decision 2026-09-24): installed by F26-b WI-1.3, one
QueryClientProviderat the app root with the client insrc/app/queryClient.ts; the email hooks read through it too (moved by F5-d). UI components in the CRM come from shadcn/ui (Radix UI + Tailwind v4 on the--et-*tokens, AD #39); screens built before it are moved over as listed in.forge/design/ui/shadcn-backfill.md - Database: PostgreSQL (AWS RDS)
- AI: Claude Haiku 4.5 (high-volume/simple; Haiku 5.5 once on Bedrock) + Claude Sonnet 5.5 (complex synthesis), called from the backend behind an
AIProviderabstraction. Served via Amazon Bedrock, called from the project’s AWS account (AD #19 — one bill and no separate AI provider accounts; where a request is processed depends on the model’s inference profile,ai-provider-strategy.md§4b, and any commercial AWS Region is accepted, OQ-15 settled 2026-11-04; outages degrade to the manual path), with per-feature{model, enabled}runtime config; see.forge/design/ai/ai-provider-strategy.md - Infra: AWS, US East (
us-east-1— AD-O-9, chosen on cost on 2026-08-18 and confirmed on 2026-10-01) — ECS Fargate, Bedrock (the AI layer), SQS (background jobs), EventBridge Scheduler (all timed work — never in-process@Scheduled), S3 (file attachments), SES (system mail — AD-O-3 decided; the capture app sends no email, AD #42), Secrets Manager (backend secrets via task-definition references — AD #22), CloudWatch + AWS Budgets, SNS (CloudWatch alarms → delivery-team email), ALB + ACM (TLS — backend API only), CloudFront (static hosting for both frontends). All of it Terraform-managed (AD #23) — the temporary UAT environment is aterraform apply/destroyof auatinstance, one instance kept from Phase 1’s acceptance round to the end of Phase 2’s. - Auth: Spring Security — Microsoft (Entra ID) OAuth2 login only (AD #28, refining AD #5: Google + local email/password dropped 2026-09-04), mapping to one
Userentity, which an administrator must have created and left active (AD #34 — no auto-provisioning, no invitation; the first admin is seeded by a migration); server-side sessions via Spring Session JDBC.local/testprofiles authenticate via a profile-scoped stub, so laptops/CI need no Entra registration - Mailbox/calendar/contacts: Microsoft 365 via Microsoft Graph — the only provider in V1 scope, behind a
MailboxProviderseam - Trade-show capture app (full scope in V1 — AD #20): a PWA in its own repository (
forge-et-pwa), hosted separately at its own URL (static bundle on S3 + CloudFront) — camera/QR capture, Haiku 4.5 card reading, research/scoring on the sameAIProviderseam, in-app lead notifications only — no email, no WhatsApp (AD #42), feeding the F11 lead intake (PRD F36). A near-complete POC exists (Thilina) — published read-only as the siblingforge-et-pwa-pocrepo: its frontend is API-integrated and portable; its Python/Supabase/Fly backend is a reference only and does not port (AD #19–#23 win). Port from it, never write to it. To run it locally:/et-run-pwa-poc(seeds demo data by default — the mock API is in-memory and starts empty;--no-seedto skip,--stopto shut down); the manual steps are in.forge/team-guide.md § Repos on This Project
See .forge/design/architecture.md for the full system architecture, component responsibilities, and deployment topology.
Architecture Decisions (DO NOT REVERSE)
Each row states the rule in force now; where a later decision refines a row, the row says so and points at it. The one-sentence reason for each decision and its lead sign-off are in .forge/design/architecture-decisions-why.md, one row per AD — read it before proposing to change or refine a decision. The full text of every row as it stood on 2026-09-23 and on 2026-10-02, and the original sign-off wording and trade-offs of AD #29 onwards, are kept verbatim in .forge/engagement-log.md § Architecture Decisions — full rationale archive — read it for the detail and history behind a row. A new or refining decision adds its row here in this form, its reason and sign-off to architecture-decisions-why.md, and its full text to the archive, and the same PR updates every other statement of the fact it changes (.claude/rules/prd.md step 4 — the same git grep, a post-issue note where the proposal states it).
| # | Decision | Date |
|---|---|---|
| 1 | Backend: Java 21 + Spring Boot (version line: AD #25) | 2026-07-13 |
| 2 | Frontend: TypeScript + React, built as a React SPA on Vite (AD #21) | 2026-07-13 |
| 3 | Database: PostgreSQL (AWS RDS), single-tenant relational schema | 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). 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) |
2026-07-13 (uat clause 2026-10-23) |
| 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) |
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) |
2026-07-13 |
| 7 | Background jobs via AWS SQS + Spring Boot async workers in the same codebase — no separate microservice/orchestrator | 2026-07-13 |
| 8 | Admin custom fields (F34) stored as a JSONB column per entity, not dynamic ALTER TABLE/EAV tables |
2026-07-13 |
| 9 | Dependency-vulnerability CI gate: CVSS ≥ 7.0 is the threshold — reported wherever the scan runs, and stopping only a UAT or production release (AD #38); per-repo suppressions need a justification and an expiry; one tool across the Java and Node ecosystems — the tool is Trivy (AD #27) | 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 |
2026-07-13 |
| 11 | Every Stage carries a stable, non-editable stage_type separate from its admin-editable display name |
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 |
2026-08-06 |
| 13 | Every queued job carries an idempotency key; consumers are replay-safe | 2026-08-06 |
| 14 | Bulk prices and costs are effective-dated rows, never updated in place. One exception, for costs: 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. A second exception, for prices: 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. Neither exception changes an as-of read for a day before today |
2026-08-06 (exceptions 2026-10-05, 2026-10-11) |
| 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 | 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 |
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 |
2026-08-06 |
| 18 | Backend build tool: Gradle (Groovy DSL — a single build.gradle), not Maven |
2026-08-18 |
| 19 | AI runs on Claude via Amazon Bedrock exclusively, from the project’s AWS account in us-east-1 through each model’s Bedrock inference profile (neither pinned model runs in-Region on bedrock-runtime — ai-provider-strategy.md §4b): Haiku 4.5 for high volume (Haiku 5.5 once it reaches Bedrock), Sonnet 5.5 for synthesis. No direct-API tier in production and no second-provider fallback (outages degrade to the manual path); per-feature {model, enabled} runtime config. One exception: the proposal’s A.3.1 comparison, on anonymised inquiries with Altrium-held evaluation keys (ai-provider-strategy.md) |
2026-08-18 (models revised 2026-09-30) |
| 20 | The trade-show capture app ships at full scope inside V1 (Option C) as a parallel work-stream, in its own repository (forge-et-pwa) at its own URL; its lead notifications are in-app only, with no email (AD #42 — this row said by email only through SES until 2026-11-12); it 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 |
2026-08-18 (phase 2026-11-11; notifications 2026-11-12) |
| 21 | Both frontends are React SPAs built with Vite — no Next.js, no SSR anywhere | 2026-08-18 |
| 22 | Frontend hosting: static S3 + CloudFront for both apps, each at its own URL with ACM TLS; the backend is the only Fargate service, behind the ALB. Frontend build-time config comes from GitHub Actions variables/secrets (non-sensitive values only — the bundle is public); backend secrets from task-definition secrets references to Secrets Manager (a setting that is not secret is a plain value — AD #40); AWS access through the task IAM role, never static keys |
2026-08-18 |
| 23 | All AWS infrastructure is Terraform-managed, in its own repository, forge-et-iaac (not forge-et-be/terraform/), which holds the Terraform and the rest of the infrastructure code: environment-parameterized modules per account (dev, prod, and a temporary uat instance: one instance applied for Phase 1’s acceptance round and kept, with its data, through Phase 2’s round, then destroyed when the lead decides; between the rounds Shyamin Ayesh (DevOps) decides whether it is paused with its data, kept running, or destroyed and applied afresh; every pause, revive and destroy is done by hand, never on a date), with state in S3 per account, locked by S3’s own lock file (use_lockfile), not a DynamoDB table |
2026-08-19 (location revised 2026-09-29; locking revised 2026-10-02; UAT lifetime revised 2026-11-18) |
| 24 | Trunk-based branching: main is the trunk; a release/vX.Y.Z branch exists only for a release live in production, cut from its tag, protected, never deleted. Releases are annotated tags vX.Y.Z; 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. Branch, commit and PR names carry the ticket id (feat(F2): …, feature/F2-…) |
2026-08-19 (manual dev deploy of a branch 2026-10-18) |
| 25 | 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 |
2026-08-21 (4.2 line 2026-11-20) |
| 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) (key quote.approve_sub_floor), never user.role == ADMIN. Who holds a permission is configuration, and no separation of duties is coded: 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 |
2026-08-21 |
| 27 | The dependency-vulnerability gate is Trivy in all three app repos: one trivy fs Fast-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, permanently — AD #38 replaced the planned flip to enforcing (FS-4 spec Rev 3) and moved the blocking check to UAT and production releases; per-repo .trivyignore.yaml entries carry id, purls, statement and a tool-enforced expired_at; Dependabot stays the alert layer. Refines AD #9’s tool |
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 use 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. Sign-in succeeds only when the verified email matches one active, pre-created user; there is no Entra user sync, so Empire disabling an Entra account is a backstop to in-app deactivation, blocking the next sign-in but not an open session (AD #34). Refines AD #5’s login half |
2026-09-04 |
| 29 | The core/domain separation is no longer extended: FS-12 and FS-13 are cancelled, AD #17’s acceptance test is retired, and 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 |
2026-09-07 |
| 30 | Role management is configurable, on a code-declared permission catalog — refines AD #15; AD #26 stands; the grant is AD #37’s (role, permission_key). The catalog is code, the grants are data: each module declares its keys as constants <resource>.<action> (grouped by resource) with label, description and UI group; the database stores only which role holds which key; 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 is listed in FS-6 Appendix A; its shape is AD #34. Reporting hierarchy: app_user.manager_id, a nullable self-reference, which sets reach over ownership and shares (AD #35, AD #37), the same for view and manage on one entity. Removed since: the per-permission own/team/all scope (AD #37); role templates, the multi-role union and the ai-use level (AD #32); the category axis, the superadmin and the * wildcard (AD #34) |
2026-09-07 |
| 31 | The core/domain split is collapsed; nothing of it remains. Backend: one Gradle module (one build.gradle, no buildSrc, one gradle.lockfile); feature-first packages com.empireteas.<capability> (starting platform, catalog, pricing, then one per feature), no core/tea/app segments, web/service/repository layers inside each; one Postgres schema (public) and one Flyway location. Frontends: forge-et-fe is one package, src/{app, features, ui, lib}; forge-et-pwa mirrors it 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 no dependency cycles between feature packages or folders, 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) |
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; the one seeded role is AD #34’s editable IT Admin. (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 settings.manage, AD #34; since AD #41, on the Users and the Roles page’s keys together). (3) AI is not a grantable level: AI the system runs on its own (lead scoring and triage, inquiry extraction, the morning briefing, 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 account briefing, the quote or brief assistant) is implied by the manage permission it assists — the account briefing by account.manage. The AI layer holds no permission; committing any AI output is an action a person performs. (Its category axis was collapsed into view / manage by AD #34) |
2026-09-11 (account briefing moved 2026-10-21) |
| 33 | The backend keeps its own address; the apps call it cross-site. Each environment’s backend is at api.<env> (api.crm.empire.lk, api.uat.crm.empire.lk, api.dev.crm.empire.lk) behind the ALB, and CloudFront serves only the static bundles. The frontends call VITE_API_BASE_URL = that api.* address; the backend’s CORS list names the environment’s CRM and capture-app origins, credentials allowed; the XSRF-TOKEN cookie carries Domain=<env's CRM host> and a different name 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 and the Entra reply URLs stay on api.*, the cookie host-only. Resolves register A-4 |
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 their sessions at once; nobody can deactivate themselves. No predefined roles: no templates, superadmin, non-deletable system role or * 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 settings.manage (since AD #41, every Settings page key) and one active user with it, whose email is a per-environment Flyway placeholder — the crm01@empire.lk test mailbox outside production, the address Empire confirms in production (a plain task-definition value, AD #40). Never a real person’s email outside production. Minimal catalog: <entity>.view and <entity>.manage per entity (manage implies view and covers every action: create, edit, share, remove a share, reassign the owner, AI drafting), plus special keys (price.publish, quote.approve_sub_floor); 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; split into one key per Settings page by AD #41), and email.manage is the holder’s own mailbox only. No category axis. At least one active user always holds settings.manage (since AD #41, both the Users and the Roles page’s keys): 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, and 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). Keys: FS-6 Appendix A |
2026-09-24 (refined 2026-10-26, 2026-10-28; AD #41 notes 2026-10-30) |
| 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); 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 is AD #37’s reporting-line rule plus the entity’s all 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) |
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. Changes to a user’s own mailbox state in Outlook, other than a send, are not audited (marking a message read or unread, creating or updating the CRM’s All-mail search folder in Outlook — F20-i D-7): they change nothing the CRM stores; a send, and any CRM write that follows such a change (such as recording the folder’s id), is audited. Kept indefinitely in V1, with no viewer screen in V1. Every table carries created_at / modified_at (framework-owned tables such as Spring Session’s excepted), and created_by / modified_by where a person acts. Built by F39, which retrofitted the writes then on main; every later writing feature calls it |
2026-09-24 (Outlook-state clause 2026-10-28) |
| 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, at every level (for a user with nobody below them, just their own and shared records). Each such entity has an <entity>.all key (lead.all, account.all; deal.all, quote.all and sample.all in Phase 2) that widens the holder’s view or manage on it 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 (under settings.users.manage since AD #41, audited — AD #36). Unchanged: mailboxes are outside every reach (email.manage is the holder’s own mailbox only); keys without an owner-bearing entity (the Settings page keys, AD #41; 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 in FS-6 Appendix A; F5-l changed the code |
2026-09-27 |
| 38 | Vulnerability scans report everywhere and block only what Empire receives — refines AD #9 and AD #27. 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), and reports HIGH/CRITICAL findings without failing the PR or the run; the dev deploy runs no Trivy scan, and ECR’s scan on push checks each dev image; TRIVY_GATE_EXIT_CODE stays 0 and the planned flip is cancelled. A UAT or production release (deploy-uat, deploy-prod) stops before deploying on an open HIGH/CRITICAL finding (CVSS ≥ 7.0) in the image or the lockfiles it releases, unless the finding has a .trivyignore.yaml exception with a statement and an unexpired expired_at — the issued proposal’s standing control (§A.4: “a build pipeline that fails on any dependency vulnerability at CVSS 7.0 or above, with exceptions requiring written justification and an expiry date”), applied at the release step instead of on every build. Findings are fixed as ordinary work; when the Spring Boot BOM lags a fix, the version is overridden with ext['<lib>.version'] and the override is removed on the Spring Boot upgrade that catches up (forge-et-be PR #145). F38 Rev 5 moves the check from FR-22 to deploy-uat (FR-35) and deploy-prod (F38-i) |
2026-10-02 (restated 2026-10-12, 2026-10-20, 2026-11-03) |
| 39 | The CRM’s UI is built from shadcn/ui — refines AD #2 and AD #21 (the React SPA on Vite stands). New and changed screens in forge-et-fe use the shadcn components in src/ui/shadcn — Radix UI underneath, Tailwind v4 without its global reset, every Tailwind name mapped onto the --et-* tokens — adapted to the CRM’s rules (aria-disabled, the global focus ring, the icon registry, Field wiring, WCAG 2.1 AA). It replaces “CSS Modules only, no Tailwind” and the two-component cap on react-aria-components, which gains no new use. Screens built before it are moved over one at a time, and each is listed in .forge/design/ui/shadcn-backfill.md until it is. A test enforces it: forge-et-fe’s src/app/shadcnOnly.test.ts fails any 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 holds what existed when the check landed and only shrinks, and adding an entry is frontend-reviewer’s decision for that PR (.forge/design/harness/shadcn-only-check.md). The revamped colour layer (theme-revamp.css) was applied with it route by route; since design-system Rev 74 every route but sign-in is on it. Covers forge-et-fe; forge-et-pwa follows it by AD #43 |
2026-10-09 (test 2026-10-12; capture app 2026-11-20) |
| 40 | A non-secret setting is a plain task-definition value in every environment, never a Secrets Manager secret — refines AD #34 (production’s seeded-admin email) and AD #22 (secrets by secrets reference). 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 are plain values too. 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 |
2026-10-28 |
| 41 | Each Settings page has its own permission key — refines AD #34 (one settings.manage) and AD #37 (setting a manager under it); AD #26 stands. settings.manage is replaced by settings.users.manage (users, managers, offboarding, a user’s effective permissions), settings.roles.manage (every role change), settings.account_tags.manage, settings.contact_tags.manage, settings.lead_tags.manage and settings.email_templates.manage; a later Settings page adds its own key, which ships fail-closed (AD #30). Administration is the Users and Roles keys together: at least one active user always holds both, and a deactivation, role change, role edit or role delete that would leave none is refused; the loggers actuator endpoint and the Pipedrive migration runs need both. The role and catalog reads also answer the Users key, which the user pages read them with. The role editor shows one Settings row with the pages under it, every page chosen when the row is ticked. Holding Users or Roles still lets the holder reach every page (AD #34’s unlimited self-escalation); the editor says so and the audit trail (AD #36) is the control. A migration gave every role that held settings.manage all six keys |
2026-10-30 |
| 42 | The capture app sends no email; its notifications are in-app only — refines AD #20 (lead notifications by email only, through SES). 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 is sent to the rep or to a team address, and there are no push notifications (a later option, not V1). F36-c builds no notification email. SES stays for the backend’s system mail (AD-O-3) | 2026-11-12 |
| 43 | The capture app’s UI is built from shadcn/ui too — applies 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 .forge/design/ui/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 |
2026-11-20 |
Reference Map
| What | Where |
|---|---|
| Project PRD (live contract) | .forge/project-prd.md |
| PRD signals (live OQs) | .forge/project-prd-signals.md — open and partly open questions; spec-reviewer loads rows by their Blocks column |
| PRD history (audit trail) | .forge/project-prd-history.md — resolved questions and PRD revisions; append-only |
| Live feature index | .forge/features.md — regenerated by /forge-decompose |
| System architecture | .forge/design/architecture.md |
| Why each Architecture Decision was made | .forge/design/architecture-decisions-why.md — the reason and lead sign-off for each AD row above, one row per AD |
| System architecture — diagram | .forge/design/architecture-diagram.svg |
| Environments & identity (concrete config) | .forge/design/environments-and-identity.md — DNS, the Entra registration (certificate login only), AWS ownership, the Terraform and what is built on dev (§4), and each item’s owner and status (§5). Non-secret config only |
| Conceptual entity map | .forge/design/data/entity-map.md — accepted; a spec touching a listed edge cites it in ## Input Sources and adopts or revises the row, and its §Contradictions rows are open inputs owned by the named spec (§ Maintenance) |
| Record sharing — decision memo (OQ-58) | .forge/design/data/record-sharing-model.md — decided; revised by AD #35 and AD #37 |
| Design system spec (tokens, components, screen conventions) | .forge/design/ui/design-system.md — its ## Revisions holds the current state; UI plans cite it in ## UI / Design Adherence |
| shadcn/ui backfill list (AD #39) | .forge/design/ui/shadcn-backfill.md — every CRM screen still on the older src/ui components, and how a screen is moved over; a frontend PR that leaves a non-shadcn component adds its row. The file-by-file list the enforcing test reads is forge-et-fe’s src/app/shadcnBackfill.json |
| The capture app on shadcn/ui (AD #43) | .forge/design/ui/pwa-shadcn.md — the decisions for forge-et-pwa (sizes, dependencies, the test) and every capture-app screen in the order it moves, one PR each. The file-by-file list is forge-et-pwa’s src/app/shadcnBackfill.json |
| Browsable prototypes (CRM + capture app) | .forge/design/prototypes/ — read its README.md first; cite the folder, never a file inside it. crm/ and pwa/ are the frozen originals; crm-current/ and pwa-current/ are drawn in the built apps’ look, and a UI change updates them in the same delivery (.claude/rules/plans.md § Required Sections). pwa-current/screenshots/ holds a picture of every capture-app screen and state, indexed in its README.md and cited by file: forge-et-pwa work compares against them as well as the prototype |
| Harness design records (changes to the delivery harness itself) | .forge/design/harness/ — one design per framework change (e.g. person-run-work-items.md), reviewed by fresh-context reviewers before implementation, because /forge-spec-review is feature-only; the rules live in the files each design names |
| Client demo kit (capture-app demo with prepared results, realistic fictional CRM data, local CRM fallback) | demo-kit/README.md — read it before preparing a client demo; every company, person and domain in it is fictional |
| Feature detail — PRD × prototype cross-reference | .forge/design/prototypes/feature-detail.md — read at spec time; the PRD and approved specs win on conflict |
| Team daily playbook | .forge/team-guide.md |
| Tracker (live state) | .forge/tracker.yaml |
| Open follow-ups, with owners | .forge/owed.md — what the team owes Empire, a teammate or the harness; reconciled with .forge/active-context.md |
| The engagement’s current state (moved out of § Active Context) | .forge/active-context.md — where it stands and the critical path, the commercial frame and SOW dates, the team, phase scope, the live decisions to build against, the open risks |
| Tracker dashboard | .forge/dashboard/index.html — data files GENERATED and gitignored (§ Boundaries) |
| Harness reference graph (who points at whom; dangling refs, orphans, Reference-Map coverage) | .forge/dashboard/harness-reference-graph.html — GENERATED; run python3 .claude/lib/harness-graph.py (--convention for coverage) instead of reading it |
| Rendered doc site (HTML mirror of the human-read doc set) | docs-html/index.html — GENERATED; node .claude/lib/render-docs-html.js rebuilds it, .claude/lib/pages-build.sh builds the hosted copy |
| Forge methodology (full) | .forge/forge-harness-framework.md — for why questions only |
| Guides & how-tos (plain-English explainers) | .forge/guides/README.md — guides teach, they don’t govern |
| Spec template + schema | .forge/specs/_TEMPLATE-spec.md |
| Plan template + schema | .forge/plans/_TEMPLATE-plan.md |
Seam-contract template (one per wave, authored by forge-contract-author) |
.forge/plans/_TEMPLATE-contract.md |
| Foundation slices — spec + plan conventions | .forge/specs/foundation/README.md, .forge/plans/foundation/README.md |
| Release / UAT cycle evidence conventions | .forge/release/README.md |
| Quality + gate checklists | .forge/checklists/README.md |
| Engagement gate-run audit | .forge/engagement-gate-runs.md |
| Issued proposal (binding input — L-001) | .forge/client/project-proposal.md — frozen; read before any gate or scope claim; corrections go only in its header’s post-issue notes |
| Running-cost annexe (the figure to quote onward) | .forge/client/sow-cost-annexe.md — cite this, not the proposal’s §A.2.2, for any running-cost number |
| AWS infrastructure SOW (ET-002 — superseded 2026-09-29, never signed) | .forge/client/aws-sow.md — a record only; do not cite it for ownership, pricing or exit (environments-and-identity.md §3 has the arrangement in force) |
| Weekly client updates (plain-English, Fridays) | .forge/client/weekly-updates/README.md — written by /et-weekly-update |
| Outstanding client questions (functional gaps) | .forge/client/open-questions.md — derived from project-prd-signals.md, which stays the source of truth: when Empire answers, fold the answer into it and the PRD (.claude/rules/prd.md), then restate it here |
| Role access map for client sign-off | .forge/client/roles-and-permissions.md — DRAFT until Empire signs off; on sign-off, fold the answers into the PRD capability matrix and the recommended day-one roles, as .forge/design/data/roles-and-permissions-key-map.md § On sign-off sets out (its internal side, kept out of the client copy) |
| Phase 1 acceptance criteria (client-facing) | .forge/client/phase-1-acceptance-criteria.md — DRAFT until Empire agrees it; the list Phase 1 is accepted against. proposal §6 and project-timeline.md §4 require a written set per phase, issued at the phase’s start |
| User guide for Empire (client-facing, handed over) | .forge/client/user-guide-<area>.md — DRAFT; one file per area, written for Empire’s staff in plain words, describing the CRM as built (proposal §9 promises a concise user guide and an administrator guide). First chapter: .forge/client/user-guide-weekly-prices.md |
| Cloud-gated validation & implementation register | .forge/cloud-gated-validation.md — everything deferred or unproved until the cloud exists; its “Start here” checklist is F38’s order of work. Every PR that defers a cloud-only item adds rows (§ Boundaries) |
| AI model/serving/cost strategy | .forge/design/ai/ai-provider-strategy.md |
| Lead research source — provider options (F11 + F36) | .forge/design/ai/lead-research-source-options.md — DECIDED — Exa, chosen by Empire on 2026-11-10, with no fallback (Rev 11; SP-ARCH-004 closed). F11-c searches on company name + website domain; its person search moves behind an admin switch on the Settings page, on by default, which Empire accepted on 2026-11-10 — built by F11-i (.forge/specs/F11-i-person-search-switch-spec.md; PRD Rev 99) |
| Test strategy (tiers + toolchain; system and non-functional verification before each UAT round) | .forge/test-strategy.md — § System Verification to V1 Sign-off is the functional and non-functional plan for each UAT round |
| Nightly full run of the three app repos (the lead’s Mac, 02:00) | .claude/lib/nightly/run-nightly.py (installed by install.sh beside it) — raises nightly-red issues; its log is the harness issue labelled nightly-log; the plain-terms guide is .forge/guides/test-runs-explained.md; the design is .forge/design/harness/test-run-cost.md |
| Weekly flaky-test report (the lead reads it) | python3 .claude/lib/flaky-report.py — every flaky test the gates, records and nightly log published over 14 days, matched to .forge/bugs.md, and which need a bug (.forge/test-strategy.md § Flaky Tests) |
| Lessons learned (upstream-sync queue) | .forge/lessons.md |
| Engagement log (dated narrative + AD rationale archive) | .forge/engagement-log.md — append-only; where a stale Active Context paragraph goes, and the verbatim AD archive |
| Coding standards + environment/profile conventions + quality toolchain (§7) | .forge/design/coding-standards.md — condensed into each app repo’s CLAUDE.md |
| Source trust hierarchy (which doc wins on disagreement) | .claude/rules/source-trust.md — always loaded |
| Spec lifecycle rules | .claude/rules/specs.md (path-scoped) |
| Plan lifecycle rules | .claude/rules/plans.md (path-scoped) |
| Tracker + gate audit rules | .claude/rules/tracker.md (path-scoped) |
| PRD trichotomy + OQ lifecycle rules | .claude/rules/prd.md (path-scoped) |
Client-facing writing (the .forge/client/ pack) |
.claude/rules/client-docs.md (path-scoped) |
| Id numbering — every numbered series, no duplicates, no gaps | .claude/rules/id-numbering.md (path-scoped); checked by .claude/lib/check-unique-ids.py (--gaps lists skipped numbers) |
| Git / PR · branching strategy (AD #24) | .claude/rules/git-conventions.md — always loaded |
Worktree commands, $WS, wave-branch naming (detail) |
.claude/rules/worktrees-and-waves.md (path-scoped; forge-worktree-up and /forge-deliver point at it) |
| Release tags, manifest versions, phase handover · branch-protection rulesets | .claude/rules/release-and-branch-protection.md (path-scoped) |
| The review record on app-repo PRs (detail) | .claude/rules/review-record.md (path-scoped; /forge-review-pr points at it) |
| The local test record, the nightly full run, the load check and one heavy run at a time (detail) | .claude/rules/test-record.md (path-scoped; git-conventions.md § Pull Requests keeps the rules and points at it) |
forge-et-iaac conventions (detail) |
.claude/rules/forge-et-iaac.md (path-scoped) |
| Hook operator guide | .claude/hooks/README.md |
| Every slash command and skill, with what it does | .claude/commands-and-skills.md |
| PR description template (this repo) | .github/PULL_REQUEST_TEMPLATE.md — each app repo has its own |
Harness repo (<harness-repo> = forge-et-harness) |
This repository. Skills and agents write <harness-repo> (or <harness> for its absolute path) |
Backend repo (<backend-repo> = forge-et-be) |
../forge-et-be/CLAUDE.md |
Frontend repo (<frontend-repo> = forge-et-fe) |
../forge-et-fe/CLAUDE.md |
Capture app repo (<capture-repo> = forge-et-pwa) |
../forge-et-pwa/CLAUDE.md — own repo and own URL (AD #20) |
Infrastructure repo (<iaac-repo> = forge-et-iaac) |
../forge-et-iaac/ — all Terraform (AD #23). Its trunk is dev: a developer’s change is a PR to dev; the DevOps team may push to it directly (.claude/rules/forge-et-iaac.md) |
| Capture-app POC (prototype + its docs) | ../forge-et-pwa-poc/ — read-only reference: port from it, never write to it |
| Browser-pane launch config (Claude Code app) | .claude/launch.json — one entry per previewable server; repo-relative paths only |
| Session starter | ./forge-start.sh |
| Personal status-line installer (run once per developer machine) | ./install-personal-statusline.sh — adds the Forge segment to ~/.claude/statusline.sh; idempotent |
Session Start
Open a Claude Code session via ./forge-start.sh. The script inventories .forge/discovery/, reads setup.* from .forge/tracker.yaml, and sends Claude an opening prompt with a turn-1 read-only protocol: read this CLAUDE.md and .forge/active-context.md, the gate state and the in-progress phase and features it prints (with the yq queries it names, never the whole tracker.yaml), and the discovery materials only before Gate 1 has passed; summarize what’s understood, propose the one next action the gate state points to, and stop. Authoring happens in later turns through interactive flows (forge-prd-author, /forge-arch-probe, /forge-decompose, /forge-spec-review, /forge-plan-review).
Workflow Phases
Spec → Plan → Implement → Check → Review → Ship → Reflect
For new projects: Discovery → Project Brief → Decompose runs once before the standard sequence begins.
Front door: to drive a feature through this whole sequence, invoke /forge-deliver <ticket> — the orchestrator that runs Spec → … → Reflect with the gates and human checkpoints. Do not hand-run the per-phase skills (forge-spec-author, forge-wave-decompose, …) individually; /forge-deliver sequences them. (Asking in plain language — “how do I start <ticket>?” — routes you there via the forge-feature-flow skill, .claude/skills/forge-feature-flow/SKILL.md.)
| Phase | Output | Gate |
|---|---|---|
| Spec | .forge/specs/<ticket>-spec.md |
Requirements approved before planning |
| Plan | .forge/plans/<ticket>-plan.md |
Approach approved before coding |
| Implement | Code in worktree | — |
| Check | Lint, tests, build pass | All mandatory checks pass |
| Review | Diff verified against spec + plan | Implementation matches intention |
| Ship | PR with spec/plan context | — |
| Reflect | Updates to CLAUDE.md, rules, or templates; findings → lessons promotion | At least one artifact updated |
No phase is skipped. No implementation begins without an approved spec and plan. Reflect is mandatory after every shipped feature — answer (1) what worked, (2) what didn’t, (3) what should change in the framework, and (4) walk .forge/specs/<feature>-findings.md to promote any generalizable findings to .forge/lessons.md. If no file changes, Reflect wasn’t done.
Quality Gates
Mandatory (no exceptions)
-
Spec reviewed and approved before planning starts
-
Plan reviewed and approved before coding begins
-
Lint, tests, and build (or type checks) pass
-
Diff reviewed against spec and plan
-
A review record on every app-repo PR before merge — every PR into
mainorrelease/*inforge-et-be,forge-et-feandforge-et-pwa,ci:,chore:anddocs:PRs included, carries a review record for its head commit: a PR comment plus aForge reviewcommit status, written by/forge-review-pr <repo>#<N>with the repo’s reviewer agent (backend-reviewerforforge-et-be,frontend-reviewerfor the two frontends);/forge-deliverruns it on every wave PR and single-plan code PR.Forge reviewis a required check: a PR whose head has nosuccessstatus cannot be merged, and every later push leaves the new head without one, so the review runs again — a delta — after the last push and the local record (git-conventions.md § The test suites run locally). A skip is the developer’s explicit decision for that PR, recorded with a reason. Exempt: a Dependabot PR whose head is Dependabot’s own commit (exempt from the record, not from review) and a PR that changes only.mdfiles; the DevOps team’s deploy-file pushes tomainare not PRs and are checked after the fact (git-conventions.md § Branch Protection); the harness repo has no such check. How the record is written, deltas, skips, a base change, the exemptions and what to check before merging a Dependabot PR:.claude/rules/review-record.md— read it before writing, skipping or re-writing a record. Why: with no approval required onmain, this is the one review every app-repo PR gets, and an audit found reviews run after merge and fix commits merged unreviewed (.forge/engagement-gate-runs.md § Post-merge /forge-review-pr backfill — 2026-09-30); one record on the PR’s head makes a missed review visible. -
A review on every
forge-et-iaacPR before it merges — every PR todev, the DevOps team’s included, gets/forge-review-pr forge-et-iaac#<N>with theiaac-revieweragent, and again (a delta) after any later push; its posted verdict is the record, because that repository has no required checks, and Shyamin Ayesh’s approval still allows the merge. A finding left open at the merge gets a home (owed.md,bugs.mdor the register) the same day, and the DevOps team’s direct pushes todevare reviewed after the fact the same way. The detail is in.claude/rules/forge-et-iaac.md. Why: a merge todevrunsterraform apply -auto-approvewith no test suite, and an audit on 2026-11-08 found merged PRs whose only review was an approval with no comment. -
Browser QA — the nightly full run checks every supported size on
main; a PR intomainruns no full browser gate, and a frontend PR runs the browser tests its change selects. The browser suites offorge-et-feandforge-et-pwarun in full every night onmain, in the nightly full run (.claude/lib/nightly/run-nightly.py): a responsiveness and accessibility pass at every supported size (PRD § Accessibility › Supported sizes, design-system §9) — the CRM at tablet (768px floor) and desktop, plus 320px reflow (WCAG 2.1 SC 1.4.10 — zoom support, not a phone design); the capture app at phone, tablet and desktop; Chromium and WebKit; target-size floor 24px in the CRM, 44px in the capture app. What each size checks, and the one counted retry and flaky-test limit, are intest-strategy.md § Browsers & Viewportsand§ Flaky Tests. A failure opens anightly-redissue and is fixed before new work starts, together with anything else that night found (.claude/rules/git-conventions.md § Pull Requests). A PR intomain, a wave PR included, needs no full gate result and noBrowser gate:line (PRD Rev 81), but aforge-et-feorforge-et-pwaPR runs the browser tests its change selects before it is marked ready (PRD Rev 93,.forge/design/harness/fewer-nightly-reds.mdR-1):pnpm e2e:gate --selectedon the final pushed head, after the test record, with the line it prints in the PR’s test evidence asSelected browser run: …(ornone selected, orskipped — <reason>, the developer’s decision); whenmaingains a merge in the same feature area before the PR merges,mainis merged in and the run repeated (R-2); andfrontend-reviewerchecks that every string, test id and token the diff changes is updated in the tests (R-3). While developing, run the specs the change needs (pnpm e2e:gate --selected, or one spec). A PR intorelease/*still needs a passing full-profile gate result that covers its head, because the nightly run tests onlymain: its ready push goes throughpnpm e2e:gate --full --push, which runs the gate on the committed head and writes theBrowser gate:line into the PR description, which the frontend’sFast lanereads; the one exception isBrowser gate: skipped — <reason>, the developer’s decision with a stated reason, treated as a review skip record is (above).frontend-reviewerchecks that every new route or data state has itsPAGE_STATESentry; each FE repo’sCLAUDE.mdcarries the dev-facing detail. Why: the supported sizes are a PRD commitment the nightly run checks every night; the whole browser suite on every PR cost about an hour on a Mac and two to three on Windows, for defects the nightly run finds by the next morning. The selected run costs minutes and catches what most red nights since 2026-11-02 were: a change merged without running the browser tests it affects, or two PRs breaking each other (fewer-nightly-reds.md§ Evidence). -
Apply a review’s recommended fixes by default — don’t wait to be told. When
/forge-review-pr,/forge-pre-pr-review, or a*-reviewersub-agent recommends a fix, apply the safe ones as part of the review pass — Claude’s judgment: contained, correct, test-backed, in-scope — and record for each finding what was fixed / deferred / left-as-is and why (in the PR, and a deferred finding also in its tracked home:bugs.md,owed.mdor the cloud-gated register — § Boundaries). Escalate rather than auto-apply only genuine judgment calls: a behaviour / UX / design change, a spec revision, an ambiguous-attribution or pre-existing-code fix, or a reviewer’s own “leave as-is”. On an app-repo PR, fix and re-review until nothing that must be fixed is open: every Blocker and every Important is fixed, then/forge-review-prreviews the fix commits as a delta, and the fix → delta round repeats while a delta finds a Blocker or an Important. An Important stays unfixed only as the lead’s decision, a problem in code the PR did not change, or the reviewer’s own “leave as is” — each recorded with its reason and home; a Nit is fixed when cheap, otherwise left with a one-line reason. After three delta rounds a finding still open goes to the lead as ablockrecord. The record script refuses anapprovewhile a Blocker or Important is listed as open (/forge-review-prstep 9). A reviewer who is not the PR’s author pushes fixes only with the author’s agreement. Why: the review’s value is the fix landing — a recommended-but-unapplied fix is a silent gap — and the lead should not have to say “go fix it” after every review. -
Security review on every security-sensitive app-repo PR — one that touches endpoints, permissions or reach, sign-in, sessions, cookies or tokens, owned-record queries, uploads, external calls, secrets or config, or renders untrusted text.
/forge-review-prstep 6a runs it as part of the review, so the review record covers it; it is never skipped by the adversarial pass’s skip rules. Why: with no manual code review, a security check that is optional is a check that does not run. -
The phase-boundary check before a phase seals —
.forge/checklists/phase-boundary-checklist.md, recorded in.forge/engagement-gate-runs.mdasPhase <N> boundary check — <date>; the seal step (.claude/rules/tracker.md) and/forge-releaserequire it, and every session opens with a reminder from two weeks before the phase’s due date. Why: it replaces repeated full audits — CI and the review catch drift on every PR, and this covers what they cannot, chiefly a decision never carried into every document (.forge/audits/2026-10-05-project-audit-2.md).
Recommended (skip with justification)
- Dependency-vulnerability CI gate (supply chain) — Trivy in each app repo’s
Fast lane, which reports dependency CVEs at CVSS ≥ 7.0 on every ready PR and stops only a UAT or production release (AD #38); wired once in Foundation (see.forge/security/+ framework §4.10), confirmed green per task rather than re-decided - Adversarial working-diff review —
/forge-pre-pr-reviewon uncommitted work (an inline review — it dispatches no sub-agent, so an implementer can run it; thebackend-reviewer/frontend-reviewersensors are dispatched by/forge-review-pror by the main session); a direct conversation with Claude as an extra opinion. (The framework-aware review of the open PR,/forge-review-pr, is in Mandatory above.)
Review Ownership
In AI-assisted delivery, specs and plans are where review effort matters most — a wrong plan produces wrong code that no amount of code review can efficiently fix.
| Artifact | Reviewer |
|---|---|
| Specs and plans | /forge-spec-review or /forge-plan-review; the developer who runs it approves, the author included |
| Code diff | Verified against spec + plan (lighter — upstream gates did the hard work) |
No spec, plan or Decomposition Plan needs a second person’s approval, and no step waits for one: the author may approve their own artifact at the review skill’s gate and go on to implementation. Asking the lead or a teammate to look is encouraged for foundational work (auth, data model, navigation), never required. Why: a peer-approval rule stopped a developer whenever no teammate was free to approve, with nothing on GitHub requiring it.
Compounding Engineering
Every time the AI makes a mistake that will recur, add a rule to prevent it.
- Decide: one-off or recurring pattern?
- If recurring: first look for a rule that already covers it and change that one. Otherwise put the rule in the narrowest file that is loaded when it is needed — a path-scoped rule in
.claude/rules/(withpaths:), or the skill, command or agent that acts on it — and in this CLAUDE.md only what every session needs. - Rules must be actionable: “use X instead of Y” — not narrative explanations.
- A rule carries its why in one sentence. A longer rationale lives once — in
architecture.md,.forge/lessons.md, the PRD history or.forge/engagement-log.md— and the rule points at it. The same story told in four files drifts four ways and buries the rules it sits beside. - Instruction text states only current facts, each checked against the file, script, workflow or tracker field it names; history goes to the engagement log. A PR that moves, renames or removes a section, a command or a file updates every pointer to it in the same PR (
git grepthe old name). Write plainly, for the current model: a rule and its reason, no emphasis without a reason. Shortening is never the goal on its own; a rule leaves only when nothing needs it. - A change that rewords text people build against or signed off — an AD row, an approved spec’s requirements, the PRD body, a rule being shortened or moved — gets one fresh-context reviewer before merge, given the old and new text, who classes each item as faithful, narrowed, widened, dropped or reversed and checks that dropped detail survives in its linked source. Why: mechanical checks (key terms present, an archive byte-identical) passed a compression of this file that had narrowed or dropped three live rules (harness PR #184).
This is the primary mechanism by which the harness gets smarter over time.
Writing
Write so a teammate who has not read the rest of the session can follow it. Use complete sentences, plain verbs, and standard terminology. No metaphors, no invented terms, and no jargon unless the reader already uses it daily — the established project vocabulary (FS-*, AD #*, the gate names, seam / wave / slice) counts as daily jargon and stays; what this bans is fresh coinage and figurative language in its place. Do not assume the reader has seen earlier output — state the context each artifact needs to stand on its own. Applies to specs, plans, the PRD, tracker notes, client-facing docs, and commit / PR text. The same plain-language rule governs Claude’s replies within a working session — plain verbs, standard terms, no metaphors or invented terms — so the transcript reads clearly to a teammate who opens it later.
Why: specs and plans are read cold by whoever implements them; prose that leans on metaphor or session-local shorthand forces the reader to reconstruct meaning the author already had.
Documents people read from start to finish — the client pack, the guides in .forge/guides/, .forge/team-guide.md and the READMEs — use simple English: short sentences with one idea each (aim for under 20 words), the person or system doing the action named as the subject, common words over formal ones, steps as numbered lists and choices as “If …” lines or a table, each new term explained once and then used the same way, and an example for any rule about dates or numbers. If a paragraph has to be read twice to be understood, rewrite it. The full checklist is in .claude/rules/client-docs.md (Simple English). Why: the lead found the client pack and the user guide too hard to read (2026-11-16).
Three further rules for everything committed to a repository or sent to Empire Teas:
- No record of a decision that was reversed in the same session. When a name or choice flips before it leaves the working session, write the records with the final one only; git history keeps the rest. Why: a short-lived internal value preserved in the docs is noise a reader must work around.
- No other Altrium engagement by name (its project, product or repository names) in files, comments, commits, PR text or client pages. A standard taken from another engagement is written as this project’s own, or as “a previous Altrium engagement”. Why: client-adjacent repositories must not carry other clients’ names.
- No path that exists on one machine. No absolute path and no personal folder (such as a local
Documentsfolder) in committed text; derive locations at run time — the workspace that holds the sibling repos is$WS, derived fromgit rev-parseas.claude/rules/worktrees-and-waves.md § Worktree Commandsshows, so it is right inside a worktree too. Tool-owned locations that are the same on every machine (~/.claude,~/.gradle,~/.m2) are allowed. Why: nobody else can check such a path, and it is wrong on every other machine.
Client-facing writing (.forge/client/) has its own conventions: .claude/rules/client-docs.md.
Boundaries
ALWAYS DO
- Run lint and tests after every code change
- No self-approval on gates. Show the receipts. When claiming any gate or verification has passed (lint, tests, typecheck, build, spec/plan ready, diff-matches-spec, ready-to-ship), list the specific commands run and their output — not just “tests pass” or “looks good.” For audited gates (
/forge-prd-check,/forge-arch-probe,/forge-decompose), the verdict always comes from the developer, never from Claude. Why: hand-waving claims let bugs through that the evidence would have caught; commands + output give the developer something to verify rather than trust. A command whose exit status is the evidence gets its own line and its own$?—./gradlew check > run.log 2>&1; echo "EXIT=$?", then read the log — never a pipe (| tail,| grep) in the same statement, whose status is the filter’s, and never atimeoutshorter than the thing it measures (a killed Gradle prints noBUILD FAILED). Where the gate leaves structured results (JUnit XML, a coverage report), a collapsed count is the sign of a truncated run. See.forge/lessons.mdL-043. - At session start, reconcile the engagement-evolving sections of this CLAUDE.md and
.forge/active-context.mdagainst the injected gate-state. Theinject-gate-state.shSessionStart hook prints the authoritative engagement status at the top of every session. Compare it against.forge/active-context.md(which## Active Contextpoints at) and.forge/owed.md,## Stack, and## Reference Map’s app-repo rows. If any of those describe an engagement state earlier than what the tracker now reports, flag the drift as the first item of turn 1, propose the specific edits, and offer to apply them before continuing. Actual edits land on turn 2 once the user agrees. Why: the injected gate-state block is authoritative; the listed files and CLAUDE.md sections are derivatives that go stale at every gate passage. - At a hand-off to a fresh session, put the context in the harness docs, then give a short opening prompt. Whenever you recommend, imply, or otherwise hand off to a fresh Claude Code session — drafting → review, review → next-phase authoring, gate-N → gate-N+1, plan approved → implementation, a manual wave handed to a person, ship → next-feature spec — first file everything the next session needs and cannot read from disk: a decision in the document that owns it (a spec revision, a plan’s
## Notes, the AD table,owed.md), the state and the next step in the feature’s trackernotes(one line,.claude/rules/tracker.md) — and commit and push it to the branch the next session reads (the ticket’s plan or wave branch,/forge-deliverStage 0 Step 0a). Then, in the same turn and unasked, give the opening prompt: the command (/forge-deliver <ticket>, or the skill the next phase uses), or one line naming the task and the file to work from (for a manual run sheet:Run the run sheet <path> with me, in <worktree>), in a fenced```markdown ```block, with any usage notes outside the fence. Never restate in the prompt what the docs already hold, and never keep hand-off context only in a prompt or in one machine’s Claude memory. Don’t trigger on mid-phase pivots or trivial subtasks. Why: the docs are what every teammate and every machine reads; Stage 0 and the tracker make/forge-deliverself-orienting, and context kept only in a prompt, a transcript or one laptop’s memory is lost to the team and drifts from the docs. - Follow patterns referenced in the plan — if the plan says “follow UserService”, follow it
- Update the plan’s
## Progresssection before ending any implementation session - Treat plan subtasks as session boundaries: end a session when its working context is dominated by output the next subtask does not need, after
## Progressis written. The handoff on disk is the point, not any token threshold - Edit harness files only through the Edit and Write tools — specs, plans, the PRD files,
tracker.yamland everything under.claude/. Neversed -i,perl -i,teeor a shell redirect into them, even when a client prefers Bash for file changes. Why: every governance guard (spec/plan approval, spec leapfrog, PRD shape, protected paths) is a hook on the Edit/Write tools; a Bash write never fires them.block-dangerous-bash.shrefuses the write shapes it can recognise, an inlinepython3/node/ruby/perlscript that writes files and names a guarded path included; the rule covers the ones it cannot (a script file run from disk, for instance). The tracker is no exception: skills write it with the Edit tool between.claude/lib/tracker-write.sh beginandfinish, neveryq -i, which rewrites the whole file (.forge/lessons.mdL-003) and whichblock-dangerous-bash.shrefuses ontracker.yaml. The one Bash write left is that script restoring its own snapshot when an edit changed more than it declared. - Ask
git statusbefore committing to avoid staging unintended files - Keep the AWS bill and CI minutes down, in design and in daily work. Empire Teas pays the AWS bill; billing settings (budgets, alerts, cost allocation tags) are Shyamin Ayesh’s, Kavindu Anthony’s, Malinda Wellalage’s and Thilina Abeyrathna’s — so a missing budget or billing alert is not a finding, a task or a Trello card for the delivery team to raise (the lead, 2026-10-26) — but what the system costs to run is the delivery team’s design responsibility (the lead, 2026-10-18). In specs and plans, choose the cheaper option when it meets the requirement — no always-on resource for occasional work, no NAT gateway, single-AZ, pay-per-use services, the right model tier and token budget for each AI feature — and name a new running cost in the spec, against
.forge/client/sow-cost-annexe.md. In daily work, leave nothing running that you started (test resources, containers, extra tasks), make no AWS call or Bedrock request a check does not need, and keep GitHub Actions runs to what the PR needs (.claude/rules/git-conventions.md § Pull Requests). Why: the running cost is promised to Empire Teas in the cost annexe, and every resource or call the design adds is paid for every month after go-live. - Before changing code to satisfy a CI tool’s finding, reproduce the finding locally with the same tool and version. Why: a redacted CI log does not identify the finding, and a guessed fix once changed correct code and left the real cause in place (
.forge/lessons.mdL-081). - Never commit the generated mirrors, and never hand-edit them.
docs-html/, the dashboard data files (.forge/dashboard/{tracker,signals,metrics}.js) and the reference graph (harness-reference-graph.{html,md}) are gitignored and rebuilt per machine from the tree: theStophooks regenerate all three at the end of every turn, exceptmetrics.js, which refreshes only when its sources are edited (the dashboard data also refreshes on every edit, via a PostToolUse hook);.githooks/pre-commitregenerates the doc site and the reference graph for a commit made outside a session;./forge-start.shrebuilds all three once in a fresh clone; the hosted copies come from.claude/lib/pages-build.sh. If a local view looks stale, run the generator —node .claude/lib/render-docs-html.js,bash .claude/hooks/regen-tracker-dashboard.sh </dev/null,python3 .claude/lib/harness-graph.py --write. Why: a whole-file regeneration conflicts byte-for-byte between any two branches that both ran it while never disagreeing about anything real (.forge/lessons.mdL-049).Repo hygieneCI proves the generators run clean on the PR’s tree; the hosted dashboard and doc site are built by thePublish dashboardworkflow, which runs.claude/lib/pages-build.shon every push tomainand force-pushes the result to the generatedlivebranch that Cloudflare Pages deploys (.forge/dashboard/README.md). - Every scripted find-and-replace must assert its anchor matched (and verify the result after) — an unmatched replacement exits 0 and is indistinguishable from success. Prefer the Edit tool, which fails loudly on a non-match; reserve scripts for genuinely repetitive edits.
- Update
.forge/tracker.yamlwhen feature state changes - Register every cloud-gated item in
.forge/cloud-gated-validation.mdin the PR that defers it. Anything a feature or slice cannot finish or prove locally because the AWS account, the Entra registration, Bedrock, SES, KMS, CloudWatch or a deployed environment does not exist yet — a faked adapter, an AC asserted only against the stub, a config key with no local value, a pipeline step not wired — gets a row in that file’s per-owner section (§B, one block per feature or slice — §C is the capability view and only holds engagement-level rows with no single owner), with the source FR/AC/Decision and how to validate it once cloud is up, plus a dated line in its## Log. A spec whose work touches such a capability carries an FR naming its cloud-gated items (F20-a FR-16 is the model) or states “none”;spec-reviewer§7,plan-reviewer§6,/forge-pre-pr-reviewand/forge-reflecteach check the register was updated. Why: the local path substitutes for every one of these and passes green, so an unregistered gap is invisible until UAT; one file is the only place the team can check what the cloud environments still owe. - Give everything left undone a row in a list the team walks later, in the change that leaves it. A deferred review finding, a decision waiting on the lead or a teammate, a defect noticed in code the change does not own, a follow-up a reviewer or a design pass raised: a defect goes to
.forge/bugs.mdandtracker.yaml, a cloud-only item to.forge/cloud-gated-validation.md, and anything else — a decision, a task, a question — to.forge/owed.mdwith an owner. A plan’s## Notes, a findings file, a design-system revision, a PR body or a review record may point at the row, but is never its only home, and the report to the developer says where each item went. Why: those records are not read once the feature closes, so an item kept only there is lost — F5-g’s gate list-height question and the lead view’s scrolling detail column were each found that way and logged afterwards (BUG-146,owed.md). - Record a decision or a finding in the harness in the session it happens. When the lead decides something or answers a question, or the work finds a fact (the state of an AWS resource, a cost, a defect, an exception to a spec or the proposal), write it in the document that owns it — a spec revision,
environments-and-identity.md§4, the register,owed.md,bugs.md, the engagement log, a guide — and ship it in the session’s PR (one PR for a session’s follow-ups, not one per item); do not ask whether to record a decision already made, and say where it went. Project knowledge goes in these docs, never only in a session transcript or one machine’s Claude memory. Why: an answer kept in a chat or on one laptop is lost to the rest of the team and to later sessions (the lead, 2026-10-14 and 2026-10-26). - The person in the session is the GitHub sign-in, never the Claude account. Attribute every decision, approval, claim and record to the person
gh api user --jq .loginnames (mapped to a first name throughtracker.yamldelivery.team), and do not ask who it is when that answers it. Why: the team shares Claude accounts when a member’s tokens run out, so the Claude account’s email can name someone other than the person typing (the lead, 2026-11-06). - Ask for explicit approval status when finishing work on a spec or plan
- When applying upstream forge-harness changes, invoke the
harness-sync-reviewersub-agent (in.claude/agents/) via the Agent tool at the end of the sync, passing the upstream forge-harness path and the from/to version range. Read findings, fix blockers, decide on majors, then bumptracker.yaml.harness_version. Why: changelog application drifts silently — a step skipped, a customization clobbered, a path-rewrite missed — and divergence compounds across syncs if not caught at the application moment. - When adding a new skill to
.claude/skills/, declare its phase scope inSKILL.mdfront-matterphases:(e.g.[discovery],[foundation, engineering]). Omit only for skills meant to be always-on. Thephase-scope-skills.shhook hides out-of-phase skills from session context — a missing field defaults to always-on.
ASK FIRST
- Install a new dependency (any package manager)
- Change database schema or migrations
- Deviate from the approved plan’s approach
- Add a new environment variable or configuration key
- Choose the authentication strategy or provider
- Make any change that affects another developer’s in-progress worktree
- Any AWS call that is not a read, in any account and with any profile: anything that creates, changes, deletes, starts, stops, rotates or invokes, including a single test call to a Bedrock model or the AgentCore Gateway. Ask the lead each time, unless the lead has said in that session that a named call needs no asking.
describe,listandgetcalls (neverget-secret-value) and Cost Explorer reads need no asking. Why: the lead wants nothing done in AWS by Claude without the team knowing, and the dev identities Claude uses can change anything in the account.
NEVER DO
- Commit secrets, keys, credentials, or
.envfiles - Print a gitignored local config file that can hold secrets (
application-local.yml,.env*, certificates, private keys) — nocat,diff,sed -nor Read of the whole file; compare it with its.exampleby key names only, or read the one key needed. Why: adiffofforge-et-be’sapplication-local.ymlonce printed the local Entra certificate and private key into a session transcript. - Commit directly to
main - Modify CI/CD pipeline configuration without lead approval
- Delete or overwrite another developer’s in-progress work
- Silently change a spec after it has been approved — always add a revision entry (see
.claude/rules/specs.md) - Skip mandatory quality gates
- Sign comments or config with author names/dates — git history carries provenance; state the rule and the why, not who decided it or when. Exception: governance artifacts whose schema requires attribution (AD table dates and the sign-offs in
architecture-decisions-why.md, spec/plan approvals,## Revisionsentries, trackeraccepted_by/dates, lessonsDate:fields, client-facing decision records). - Copy a count or tally derived from another file into passing prose (OQ counts, AD counts, page counts) — say it qualitatively or point at the source of truth; a copied number goes stale silently. Keep a count only when the number is itself the rule (an invariant like “exactly one phase in-progress”) or a spec-locked design parameter. Exception: point-in-time records (audit registers, revision logs, gate runs) keep their numbers verbatim — rewriting them falsifies history. See
.forge/lessons.mdL-002. - Load generated or vendored artifacts into context. The complete list:
docs-html/**(rendered mirror),.forge/dashboard/*.js(the tracker/signals/metrics/usage mirrors and the vendoredd3.v7.min.js),.forge/dashboard/harness-reference-graph.{html,md}(generated, hundreds of lines — runpython3 .claude/lib/harness-graph.pyfor a fresh report rather than reading the artifact), and.claude/lib/vendor/**(minified libs). Read the.md/.yamlsources instead. Only exception: verifying a generator’s own output — and prefer agrep/sedthrough Bash over reading the whole file into context. Why: they are bulky duplicates of the sources — reading them burns context on noise and risks acting on a mid-regeneration copy. - Start implementation without an approved spec and plan
- Write to any file on turn 1 of a fresh session opened by
./forge-start.shor with an open-ended first message (“where are we?”, “what next?”). Such a session opens with the read-only protocol — orient, summarize, propose one next action, stop. A first message that names one concrete task (“fix the typo in X”, a slash command) authorizes that task on turn 1; every gate the task passes through (spec and plan approval, the hooks) still applies. Authoring happens in later turns via interactive flows that interview or surface tradeoffs before writing. Multi-step requests like “run discovery → write PRD → build it” are NOT authorization to chain — do the first step and stop. Why: a first turn that reads and drafts in one motion leapfrogs the gates — the interview, the review, the human approval — before anyone has seen the framing. The read-only turn exists to protect the gates, not to save tokens.
Hooks
Hooks in .claude/hooks/ are deterministic — they run on every relevant tool call and cannot be forgotten mid-session. The tracker-reading hooks require yq to parse .forge/tracker.yaml; most hooks parse their stdin with jq. All fail open if their dependency is missing (per-hook detail: .claude/hooks/README.md § Dependencies).
If a hook blocks, treat its stderr as authoritative. Don’t work around it.
Full operator guide and per-hook detail: .claude/hooks/README.md.
Role Delegation
Multi-pass reviewers are wired and enforced by hooks:
/forge-spec-review <path>—spec-reviewersub-agent across up to 2 passes (Pass 1 audits including input-side gaps as dimension §12; Pass 2 verifies fixes); applies Blocker/Important fixes between passes; asks human for final approval before flippingStatus: approved. Feature specs only — foundation specs exempt./forge-plan-review <path>—plan-reviewerruns one audit pass, plus a verification pass when the audit returned any Blocker; Blocker and Important fixes are applied between them, then a human approval gate (foundation and feature plans both supported)./forge-review-pr <repo>#<N>(e.g.forge-et-be#124; a bare number only when no other configured repo has a PR with that number) — framework-aware GitHub PR review across configured workspace repos. Pulls diff, classifies the PR, runs framework-specific quality checks + an adversarial pass, produces a Blocker/Important/Nit verdict, applies the safe fixes, and for an app-repo PR intomainorrelease/*writes the review record (a delta review when the PR already carries anapproverecord). Optional--commentposts the full verdict to the PR. On aforge-et-iaacPR it dispatches theiaac-revieweragent and always posts the verdict, which is that repository’s record.
Adversarial code review and security review on uncommitted working diffs run via /forge-pre-pr-review (inline — it dispatches no sub-agent; the backend-reviewer / frontend-reviewer sensors are dispatched by /forge-review-pr on the open PR, or by the main session for a second opinion); the mandatory security review of the open PR is /forge-review-pr step 6a.
Every sub-agent runs on the driver’s model and effort. The definitions in .claude/agents/ declare model: inherit and no effort:; do not pass a model parameter when dispatching any sub-agent, built-in ones included. Why: one model for all work is the team’s decision (.forge/team-guide.md § Choosing a Claude model and effort), and a per-dispatch model is the only setting that overrides it.
Command and skill inventory
Every slash command and skill, with one line on what it does, is in .claude/commands-and-skills.md; a new command or skill adds its row there in the same change. They load by name, so the list is what makes them discoverable, and the reference graph’s --convention check flags one that nothing reaches from this file. The front door for feature delivery is /forge-deliver (§ Workflow Phases).
Common Commands
Each app repo’s CLAUDE.md § Common commands is the one list of its commands — build, test, lint, run, the dependency scan and, in the frontends, the browser gate. Read it there; the harness keeps no copy, so a command change is made in the app repo only.
| Repo | Where its commands are | What a PR needs once, after its last push |
|---|---|---|
forge-et-be |
../forge-et-be/CLAUDE.md § Common commands |
python3 scripts/local-build-evidence.py (the Test record check: the build with the tests the change needs) |
forge-et-fe |
../forge-et-fe/CLAUDE.md § Common commands |
pnpm test:record (the tests the change needs; backend running). Into release/*: pnpm e2e:gate --full --push for the last push first |
forge-et-pwa |
../forge-et-pwa/CLAUDE.md § Common commands |
pnpm test:record (the tests the change needs; no backend needed). Into release/*: pnpm e2e:gate --full --push for the last push first |
Where each app repo’s test suite runs, and the local record (the Test record check) a PR carries instead: .claude/rules/git-conventions.md § Pull Requests. The browser suites run in full in the nightly full run on main, and on the developer’s machine only for a PR into release/*, where CI reads the Browser gate: line rather than running a browser (§ Quality Gates › Mandatory, Browser QA); no CI job runs a browser after a deploy either. The smoke run after each dev deploy is pnpm e2e:smoke, run by hand (.forge/team-guide.md § Environments, F38-g); UAT and production get the same smoke run by hand after their deploys, and no browser tier runs inside deploy-uat or deploy-prod (F38-i decision 3; .forge/design/architecture.md § CI/CD Pipelines, .forge/test-strategy.md § When Tests Run).
Active Context
The engagement’s current state — where it stands and the critical path, the commercial frame and the Statement of Work dates, the team, phase scope, the live decisions to build against, and the open risks — is in .forge/active-context.md. Read it before authoring or reviewing a spec, plan or Decomposition Plan, before any work that touches the schedule, the phases, the cloud bring-up, the AI layer or the commercial terms, and before telling anyone where the engagement stands; reconcile it against the injected gate state at session start (§ Boundaries, ALWAYS DO). It is kept out of this file so that it is not loaded into every request.
Six of its rules bind every session:
- 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 (L-001,
.claude/rules/source-trust.md). Running costs are quoted from.forge/client/sow-cost-annexe.md, never the proposal’s §A.2.2/§A.8. - The lead’s rule: finish building one week before each milestone. A phase’s
due_dateintracker.yamlis that build target, one week before itsmilestone_date(the Statement of Work date Empire was given); report a phase against its milestone, with the build target beside it. Each UAT round runs in a temporary environment; development never doubles as UAT. - Work-item sizing (team — the Gate-3 standing instruction). 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_byis explicit and parallel versus sequential is classified — the dependency graph is the work-division plan across the four developers. The borderline splits marked◐infeatures.mdare the first to merge back if the per-feature overhead bites. - No fixed lanes: waves are sliced vertically, with no backend/frontend split, and each developer takes the next unblocked feature from the tracker (
.forge/team-guide.md § Working in Parallel — Four Developers). - Until AWS lifts the account’s Bedrock limits, Haiku 4.5 runs every AI feature in every environment, and the backend paces its Bedrock calls — the lead’s decision of 2026-10-26, which overrides the Sonnet 5.5 and Haiku 5.5 tiers in § Stack and AD #19 for now (
.forge/design/ai/ai-provider-strategy.md§5 row 10; the pacing is F42). - No questions to Empire before UAT — the lead’s decision of 2026-11-13. An answer a spec, plan or design needs from Empire is decided by the delivery team: the simplest option for Empire’s staff to understand, minimal, and flexible enough for the ways they might work, recorded with its reason where the question was kept. A change Empire asks for at UAT is then made as ordinary work. Do not raise new questions for Empire, and decide one already waiting on them when work reaches it.
Owed, with owners. The open follow-ups and who owes each one are in .forge/owed.md. Read it before telling anyone what is outstanding, and update it in the same change that settles an item.