System Requirements Document

1. Introduction

Synergy Pro Painting requires a production-ready Custom Python Services platform that acts as the authoritative security, authority, calculation, persistence, integration, and infrastructure layer for its business operations. The platform sits between human operators (via a Command Center) and the CrewAI AI workforce, and serves as the single controlled gateway to external systems such as Jobber, QuickBooks, email, calendar, weather, mapping, marketing, and storage.

This document defines the system as a set of enforceable, testable requirements. The core intent is a strict separation of concerns:

• AI reasoning (CrewAI) provides intelligence and recommendation only.
• The Python platform provides enforcement, authorization, policy, deterministic calculation, persistence, and audit.
• External systems provide authoritative operational and accounting data where applicable.
• Humans retain final authority over high-risk actions.

Security, authorization, policy, and deterministic calculations must never depend on LLM prompts, agent instructions, UI restrictions, frontend validation, or natural-language policy. No AI agent may bypass the platform, and no external system may be treated as trusted without validation.

2. System Overview

The platform is a modular Python backend/runtime that mediates every consequential action across the following hierarchy:

HUMAN AUTHORITY
        ↓
COMMAND CENTER
        ↓
SECURITY + AUTHORIZATION
        ↓
BUSINESS POLICY
        ↓
CUSTOM PYTHON SERVICES
        ↓
CREWAI WORKFORCE
        ↓
AUTHORIZED TOOLS
        ↓
EXTERNAL SYSTEMS

Internally, requests flow through the following control chain:

COMMAND CENTER
        ↓
API GATEWAY
        ↓
AUTHENTICATION
        ↓
AUTHORIZATION
        ↓
POLICY / AUTHORITY ENGINE
        ├── APPROVAL ENGINE
        ├── AUDIT ENGINE
        ├── EVENT BUS
       \x20\xe2\x94\x94── EXECUTION ENGINE
        ↓
CREWAI RUNTIME ADAPTER
        ↓
TOOL GATEWAY
        ├── JOBBER
        ├── QUICKBOOKS
        ├── EMAIL
        ├── CALENDAR
        ├── WEATHER
        ├── MAPPING
        ├── MARKETING
        ├── STORAGE
       \x20\xe2\x94\x94── FUTURE INTEGRATIONS

The platform must remain modular enough that future AI agents, crews, integrations, companies, services, and business modules can be added without redesigning the security architecture. The system builds the actual working backend — it is not a demo, prototype, tutorial, mockup, conceptual architecture, or partial implementation.

3. Functional Requirements

3.1 Core Platform Components

• FR-1. As a platform operator, I want an authentication component so that every request is bound to a verified identity before any processing occurs.
• FR-2. As a platform operator, I want an authorization component so that every consequential operation passes backend authorization in code.
• FR-3. As a platform operator, I want an RBAC component so that permissions are enforced through roles rather than agent or UI instructions.
• FR-4. As a platform operator, I want company isolation so that data, events, tasks, and credentials of one company are never accessible to another.
• FR-5. As a platform operator, I want an authority/policy engine so that the authority class of every action is determined by backend policy.
• FR-6. As a platform operator, I want an approval engine so that high-risk actions require explicit, bound human authorization before execution.
• FR-7. As a platform operator, I want a Tool Gateway so that no AI agent directly accesses external systems.
• FR-8. As a platform operator, I want integration adapters so that external systems are accessed through normalized, versioned interfaces.
• FR-9. As a platform operator, I want a deterministic estimating engine so that estimate mathematics is authoritative and reproducible, never LLM-derived.
• FR-10. As a platform operator, I want a business calculation engine so that labour, material, pricing, tax, and profitability calculations are reusable and independently testable.
• FR-11. As a platform operator, I want a persistence/data layer so that all authoritative state is durably stored with constraints and integrity guarantees.
• FR-12. As a platform operator, I want an event bus so that business and AI lifecycle events are published and consumed with a defined schema.
• FR-13. As a platform operator, I want task/execution persistence so that AI executions and their state survive restarts and remain resumable.
• FR-14. As a platform operator, I want an API layer so that authenticated, authorized clients and services can invoke workforce and administrative operations.
• FR-15. As a platform operator, I want webhook security so that inbound external events are authenticated, validated, and deduplicated before processing.
• FR-16. As a platform operator, I want idempotency so that repeated requests never create duplicate consequential operations.
• FR-17. As a platform operator, I want audit logging so that every consequential action produces an append-only record.
• FR-18. As a platform operator, I want observability so that requests, executions, latency, cost, failures, and blocks are traceable by correlation IDs.
• FR-19. As a platform operator, I want standardized error handling so that failures return safe, structured, machine-readable errors.
• FR-20. As a platform operator, I want a retry system so that safely retryable operations recover without duplicating side effects.
• FR-21. As a platform operator, I want a dead-letter queue so that unrecoverable failures are persisted and surfaced rather than silently lost.
• FR-22. As a platform operator, I want AI model/cost telemetry so that model usage, tokens, latency, and spend are tracked per agent, crew, flow, and company.
• FR-23. As a platform operator, I want an evaluation framework so that AI behavior, authority boundaries, and calculations are automatically tested.
• FR-24. As a platform operator, I want security testing so that defined attack and abuse scenarios are verified by automated tests.
• FR-25. As a platform operator, I want integration testing so that adapters and external boundaries are verified against real interfaces.
• FR-26. As a platform operator, I want configuration management so that environment and business configuration is externalized and never hard-coded.
• FR-27. As a platform operator, I want secrets management interfaces so that credentials are referenced securely and never exposed to agents or APIs.
• FR-28. As a platform operator, I want health/readiness monitoring so that the live, ready, degraded, and failed states of the system and its dependencies are exposed.
• FR-29. As a platform operator, I want emergency controls so that agents, crews, flows, and classes of external actions can be paused or disabled immediately.
• FR-30. As a platform operator, I want versioning so that estimates, pricing, policies, calculations, agents, prompts, tools, workflows, knowledge, and configuration are versioned.
• FR-31. As a platform operator, I want migration infrastructure so that schema changes are applied through controlled, reversible migrations.
• FR-32. As a platform operator, I want background workers so that long-running and asynchronous work executes outside the request cycle.
• FR-33. As a platform operator, I want scheduling infrastructure so that recurring and delayed work is executed reliably.
• FR-34. As a platform operator, I want documentation so that the architecture, contracts, and operations are understandable and maintainable.
• FR-35. As a platform operator, I want production deployment configuration so that the platform ships as production-ready containers.

3.2 Architecture Separation

• FR-36. As a platform architect, I want AI reasoning, business authority, external system access, and deterministic calculations to be separated into distinct layers so that no layer can assume the responsibilities of another.
• FR-37. As a platform architect, I want the Command Center, API Gateway, authentication, authorization, policy engine, execution engine, CrewAI adapter, and Tool Gateway to form a single enforced request chain so that every request passes through the same controls.

3.3 Security Model

• FR-38. As a security engineer, I want security enforced in code so that prompts, agent instructions, UI restrictions, frontend validation, and natural-language policies are never the sole enforcement mechanism.
• FR-39. As a security engineer, I want authentication enforced on every request so that no unauthenticated call reaches business logic.
• FR-40. As a security engineer, I want authorization enforced on every consequential operation so that no unauthorized action executes.
• FR-41. As a security engineer, I want RBAC enforcement so that permissions are resolved from identity roles and scopes.
• FR-42. As a security engineer, I want permission scopes so that operations are restricted to the specific scope they require.
• FR-43. As a security engineer, I want service identities so that non-human service callers are authenticated and constrained.
• FR-44. As a security engineer, I want agent identities so that each AI agent carries a verifiable identity distinct from humans and services.
• FR-45. As a security engineer, I want API authentication so that all API clients are verified.
• FR-46. As a security engineer, I want API authorization so that each endpoint enforces required permissions.
• FR-47. As a security engineer, I want company isolation enforced on every request so that company context is derived from authenticated identity, not client-supplied values.
• FR-48. As a security engineer, I want resource-level authorization so that access decisions are made per resource instance.
• FR-49. As a security engineer, I want action-level authorization so that access decisions are made per action.
• FR-50. As a security engineer, I want rate limiting so that abuse and runaway loops are throttled.
• FR-51. As a security engineer, I want request validation so that malformed or hostile input is rejected.
• FR-52. As a security engineer, I want input sanitization so that untrusted input cannot compromise downstream systems.
• FR-53. As a security engineer, I want output validation so that responses conform to expected schemas.
• FR-54. As a security engineer, I want secret protection so that secrets are never exposed to agents, APIs, logs, or prompts.
• FR-55. As a security engineer, I want encryption so that sensitive data is protected in transit and at rest where applicable.
• FR-56. As a security engineer, I want secure headers so that API responses follow hardened HTTP conventions.
• FR-57. As a security engineer, I want webhook verification so that inbound webhooks are authenticated before processing.
• FR-58. As a security engineer, I want replay protection so that replayed requests and events cannot cause duplicate consequences.
• FR-59. As a security engineer, I want idempotency enforced on consequential operations so that retries and duplicates are safe.
• FR-60. As a security engineer, I want audit logging on all security-relevant events so that activity is traceable.
• FR-61. As a security engineer, I want security event logging so that authentication, authorization, and policy decisions are captured distinctly.

3.4 Identity

• FR-62. As a platform operator, I want identity support for owner, administrator, and manager so that human authority levels are represented.
• FR-63. As a platform operator, I want identity support for estimator and salesperson so that estimating and sales workflows are attributable.
• FR-64. As a platform operator, I want identity support for operations, production, and employee so that field and delivery workflows are attributable.
• FR-65. As a platform operator, I want identity support for finance, bookkeeping, and marketing so that financial and marketing workflows are attributable.
• FR-66. As a platform operator, I want identity support for AI agent, AI crew, service account, and integration so that non-human actors are explicitly typed.
• FR-67. As a platform operator, I want every request to establish user_id, company_id, identity_type (HUMAN|AGENT|SERVICE|INTEGRATION), roles, permissions, scopes, session_id, and request_id so that the full request context is available to enforcement.
• FR-68. As a security engineer, I want client-supplied company_id to be validated against authenticated identity so that an untrusted client cannot spoof tenant context.

3.5 Multi-Company Isolation

• FR-69. As a platform operator, I want every tenant-sensitive object to carry company_id so that isolation is enforceable at every layer.
• FR-70. As a platform operator, I want isolation enforced at the API layer so that cross-company requests are rejected at the boundary.
• FR-71. As a platform operator, I want isolation enforced at the service layer so that business logic cannot cross tenants.
• FR-72. As a platform operator, I want isolation enforced at the repository layer so that data access is tenant-scoped.
• FR-73. As a platform operator, I want isolation enforced at the database query layer so that queries cannot retrieve another company's rows.
• FR-74. As a platform operator, I want isolation enforced at the cache layer so that cached values never leak across companies.
• FR-75. As a platform operator, I want isolation enforced on events so that events are attributed and scoped to one company.
• FR-76. As a platform operator, I want isolation enforced on tasks so that work items are company-scoped.
• FR-77. As a platform operator, I want isolation enforced on memory so that agent or system memory is company-scoped.
• FR-78. As a platform operator, I want isolation enforced on integrations so that external calls use company-scoped credentials and context.
• FR-79. As a platform operator, I want isolation enforced on audit so that audit records are attributable to a company.
• FR-80. As a platform operator, I want isolation enforced on files/documents so that documents are company-scoped.
• FR-81. As a platform operator, I want isolation enforced on knowledge so that knowledge retrieval respects company boundaries.
• FR-82. As a platform operator, I want isolation enforced on credentials so that one company's credentials are never usable by another.
• FR-83. As a security engineer, I want cross-company access to be impossible regardless of AI agent behavior so that isolation never depends on agent memory.

3.6 Authority Model

• FR-84. As a policy administrator, I want a READ authority class so that information retrieval is permitted and classified.
• FR-85. As a policy administrator, I want a RECOMMEND authority class so that analysis and recommendation are permitted without execution.
• FR-86. As a policy administrator, I want a DRAFT authority class so that actions can be prepared without being executed.
• FR-87. As a policy administrator, I want a CONTROLLED_WRITE authority class so that execution occurs only when configured policy allows it.
• FR-88. As a policy administrator, I want a HIGH_RISK_WRITE authority class so that explicit authorization or approval is mandatory.
• FR-89. As a policy administrator, I want a PROHIBITED authority class so that certain actions are rejected regardless of agent request.
• FR-90. As a security engineer, I want authority to be determined by backend policy so that agents cannot self-assign authority.

3.7 Prohibited Actions

• FR-91. As a security engineer, I want AI agents prohibited from transferring money, so that funds cannot be moved without human authority.
• FR-92. As a security engineer, I want AI agents prohibited from changing bank credentials.
• FR-93. As a security engineer, I want AI agents prohibited from modifying authentication.
• FR-94. As a security engineer, I want AI agents prohibited from modifying security permissions.
• FR-95. As a security engineer, I want AI agents prohibited from creating administrators without authorization.
• FR-96. As a security engineer, I want AI agents prohibited from deleting accounting history.
• FR-97. As a security engineer, I want AI agents prohibited from deleting customers.
• FR-98. As a security engineer, I want AI agents prohibited from deleting jobs.
• FR-99. As a security engineer, I want AI agents prohibited from altering historical financial records.
• FR-100. As a security engineer, I want AI agents prohibited from filing taxes.
• FR-101. As a security engineer, I want AI agents prohibited from approving their own high-risk actions.
• FR-102. As a security engineer, I want AI agents prohibited from bypassing approval.
• FR-103. As a security engineer, I want AI agents prohibited from disabling audit logging.
• FR-104. As a security engineer, I want AI agents prohibited from disabling security controls.
• FR-105. As a security engineer, I want AI agents prohibited from exposing credentials.
• FR-106. As a security engineer, I want AI agents prohibited from retrieving secrets unnecessarily.
• FR-107. As a security engineer, I want AI agents prohibited from impersonating humans.
• FR-108. As a security engineer, I want AI agents prohibited from fabricating customer consent.
• FR-109. As a security engineer, I want AI agents prohibited from fabricating measurements.
• FR-110. As a security engineer, I want AI agents prohibited from fabricating financial data.
• FR-111. As a security engineer, I want AI agents prohibited from fabricating completed work.
• FR-112. As a security engineer, I want AI agents prohibited from fabricating payment.
• FR-113. As a security engineer, I want AI agents prohibited from fabricating estimates.
• FR-114. As a security engineer, I want AI agents prohibited from modifying their own permissions.
• FR-115. As a security engineer, I want AI agents prohibited from modifying their own guardrails.
• FR-116. As a security engineer, I want AI agents prohibited from modifying their own system policies.
• FR-117. As a security engineer, I want prohibited actions to return a structured policy denial so that denial is machine-readable and auditable.

3.8 Policy Engine

• FR-118. As a policy administrator, I want a centralized policy engine so that business policies are not duplicated inside individual agents.
• FR-119. As a policy administrator, I want policy control over minimum gross margin.
• FR-120. As a policy administrator, I want policy control over discount limits.
• FR-121. As a policy administrator, I want policy control over estimate approval thresholds.
• FR-122. As a policy administrator, I want policy control over purchasing limits.
• FR-123. As a policy administrator, I want policy control over financial action limits.
• FR-124. As a policy administrator, I want policy control over communication permissions.
• FR-125. As a policy administrator, I want policy control over scheduling authority.
• FR-126. As a policy administrator, I want policy control over service-area rules.
• FR-127. As a policy administrator, I want policy control over tax configuration.
• FR-128. As a policy administrator, I want policy control over labour rules.
• FR-129. As a policy administrator, I want policy control over overtime rules.
• FR-130. As a policy administrator, I want policy control over material purchasing.
• FR-131. As a policy administrator, I want policy control over customer data access.
• FR-132. As a policy administrator, I want policy control over marketing publication.
• FR-133. As a policy administrator, I want policy control over destructive operations.
• FR-134. As a policy administrator, I want policy control over AI autonomy.
• FR-135. As a policy administrator, I want policy control over model spending limits.
• FR-136. As a policy administrator, I want policies to be defined with a policy_id, company_id, action, threshold, unit, approval_required_above, effective_from, and version.
• FR-137. As a policy administrator, I want policies to be versioned so that historical executions retain the policy version used.

3.9 Approval Engine

• FR-138. As an approver, I want a centralized approval workflow so that high-risk actions are reviewed consistently.
• FR-139. As an approver, I want an approval object containing approval_id, company_id, request_id, requested_by, action, risk_level (LOW|MEDIUM|HIGH|CRITICAL), evidence, proposed_action, policy_basis, expires_at, status (PENDING|APPROVED|REJECTED|EXPIRED|CANCELLED), approved_by, and approved_at.
• FR-140. As a security engineer, I want self-approval prevented.
• FR-141. As a security engineer, I want expired approvals rejected.
• FR-142. As a security engineer, I want approval reuse prevented.
• FR-143. As a security engineer, I want altered approved actions rejected.
• FR-144. As a security engineer, I want approval without authorization prevented.
• FR-145. As a security engineer, I want approvals to bind to the exact proposed action so that a materially changed action requires a new approval.

3.10 Tool Gateway

• FR-146. As a platform operator, I want a centralized Tool Gateway so that no AI agent directly accesses external systems.
• FR-147. As a platform operator, I want the Tool Gateway flow to proceed: AGENT → TOOL REQUEST → AUTHENTICATION → AUTHORIZATION → COMPANY VALIDATION → POLICY CHECK → INPUT VALIDATION → RATE LIMIT → IDEMPOTENCY → EXTERNAL API → RESPONSE VALIDATION → AUDIT → STRUCTURED RESULT.
• FR-148. As a tool author, I want every tool to declare tool_id, version, description, read_write (READ|WRITE), authority_class, required_permissions, required_scopes, company_scoped, and idempotent.

3.11 Jobber Integration

• FR-149. As an operations user, I want a normalized Jobber adapter so that Jobber operations are accessed through a stable interface without exposing raw implementation details to agents.
• FR-150. As an operations user, I want a get_customer interface.
• FR-151. As an operations user, I want a search_customers interface.
• FR-152. As an operations user, I want a create_customer interface.
• FR-153. As an operations user, I want an update_customer interface.
• FR-154. As an operations user, I want a get_job interface.
• FR-155. As an operations user, I want a search_jobs interface.
• FR-156. As an operations user, I want a create_job interface.
• FR-157. As an operations user, I want a get_quote interface.
• FR-158. As an operations user, I want a create_quote_draft interface.
• FR-159. As an operations user, I want a get_schedule interface.
• FR-160. As an operations user, I want a create_schedule_proposal interface.
• FR-161. As an operations user, I want a get_job_notes interface.
• FR-162. As an operations user, I want a create_job_note interface.
• FR-163. As an operations user, I want a get_job_status interface.
• FR-164. As an operations user, I want an update_job_status interface.
• FR-165. As a platform operator, I want Jobber operations separated into READ, PROPOSE, and COMMIT so that read access cannot be confused with committed writes.
• FR-166. As a platform operator, I want the Jobber adapter to handle authentication, token lifecycle, rate limits, retries, timeouts, schema changes, API failures, idempotency, and audit logging.
• FR-167. As an integration engineer, I want external API fields verified against the current API implementation before integration so that no fields are assumed.

3.12 QuickBooks Integration

• FR-168. As a finance user, I want a normalized QuickBooks adapter so that accounting operations are accessed through a stable interface.
• FR-169. As a finance user, I want a get_accounts interface.
• FR-170. As a finance user, I want a get_transactions interface.
• FR-171. As a finance user, I want a get_profit_loss interface.
• FR-172. As a finance user, I want a get_balance_sheet interface.
• FR-173. As a finance user, I want a get_accounts_receivable interface.
• FR-174. As a finance user, I want a get_accounts_payable interface.
• FR-175. As a finance user, I want a get_customer_balance interface.
• FR-176. As a finance user, I want a get_vendor_balance interface.
• FR-177. As a finance user, I want a get_accounting_period interface.
• FR-178. As a finance user, I want a create_transaction_proposal interface.
• FR-179. As a finance user, I want a create_invoice_proposal interface.
• FR-180. As a finance user, I want a create_expense_proposal interface.
• FR-181. As a finance user, I want accounting to remain authoritative in QuickBooks and authorized human workflows so that AI may analyze and recommend but never silently alter accounting records.
• FR-182. As a finance user, I want financial writes to be policy-controlled so that no financial mutation occurs outside policy.

3.13 Communication Integrations

• FR-183. As an operations user, I want controlled email interfaces so that customer and business email is governed by approval.
• FR-184. As an operations user, I want controlled SMS interfaces so that text communication is governed by approval.
• FR-185. As an operations user, I want controlled customer messaging interfaces so that all customer outreach is governed.
• FR-186. As an operations user, I want DRAFT, APPROVE, and SEND stages for outbound communication so that nothing is sent without authorization.
• FR-187. As an operations user, I want every outgoing communication to carry company identity, customer/job association where applicable, sender identity, approval state, content hash, timestamp, and audit record.
• FR-188. As a security engineer, I want unauthorized commitments prevented so that no agent can bind the company to an unapproved commitment.

3.14 Calendar / Scheduling

• FR-189. As a scheduling user, I want a normalized calendar interface so that scheduling operations are consistent across providers.
• FR-190. As a scheduling user, I want a get_availability interface.
• FR-191. As a scheduling user, I want a get_events interface.
• FR-192. As a scheduling user, I want a create_schedule_proposal interface.
• FR-193. As a scheduling user, I want a validate_schedule interface.
• FR-194. As a scheduling user, I want a commit_schedule interface.
• FR-195. As a scheduling user, I want a cancel_schedule interface.
• FR-196. As a security engineer, I want schedule commitments to pass availability and policy validation so that an agent can never promise a date merely because it appears probable.

3.15 Webhook Engine

• FR-197. As an integration engineer, I want secure webhook processing that supports authentication.
• FR-198. As an integration engineer, I want webhook signature verification.
• FR-199. As an integration engineer, I want webhook timestamp validation.
• FR-200. As an integration engineer, I want webhook replay protection.
• FR-201. As an integration engineer, I want webhook event ID handling.
• FR-202. As an integration engineer, I want webhook idempotency.
• FR-203. As an integration engineer, I want webhook schema validation.
• FR-204. As an integration engineer, I want webhook company identification.
• FR-205. As an integration engineer, I want webhooks persisted before processing.
• FR-206. As an integration engineer, I want webhook processing state tracked.
• FR-207. As an integration engineer, I want webhook retry handling.
• FR-208. As an integration engineer, I want webhook dead-letter handling.
• FR-209. As an integration engineer, I want webhook audit logging.
• FR-210. As an integration engineer, I want the webhook processing sequence: RECEIVE → AUTHENTICATE → VALIDATE → DEDUPE → PERSIST → PROCESS → ACKNOWLEDGE → AUDIT.
• FR-211. As a security engineer, I want consequential actions blocked until the event is validated.

3.16 Idempotency

• FR-212. As a platform operator, I want every consequential external operation to support idempotency using a key derived from company_id + action_type + source_event_id.
• FR-213. As a platform operator, I want idempotency records to store the idempotency key, request, action, status, response, and timestamp.
• FR-214. As a platform operator, I want repeated requests to not create duplicate invoices, purchases, messages, customers, jobs, schedules, payments, or accounting transactions.

3.17 Deterministic Estimating Engine

• FR-215. As an estimator, I want a completely separate deterministic calculation engine so that the LLM interprets information but the engine performs authoritative mathematics.
• FR-216. As an estimator, I want the engine to accept inputs including measurements, surfaces, rooms, walls, ceilings, trim, baseboards, doors, windows, casings, coats, primer, paint, coverage, material costs, labour rate, crew size, productivity, prep, waste, equipment, travel, overhead, markup, tax, complexity, and service type.
• FR-217. As an estimator, I want the engine to produce outputs including surface area, material quantities, primer gallons, paint gallons, labour hours, production days, material cost, labour cost, equipment cost, travel cost, prep cost, overhead, markup, subtotal, tax, total, gross profit, gross margin, and production assumptions.
• FR-218. As an estimator, I want every calculation to be reproducible.
• FR-219. As an estimator, I want each calculation to store calculation inputs, calculation outputs, engine version, pricing version, policy version, timestamp, and calculation ID.
• FR-220. As a security engineer, I want the LLM prohibited from overwriting calculated totals.

3.18 Estimating Formula Engine

• FR-221. As an estimator, I want configurable formulas so that company pricing is not hard-coded where configuration is appropriate.
• FR-222. As an estimator, I want surface_area derived from calculated geometry.
• FR-223. As an estimator, I want material_quantity = surface_area / coverage.
• FR-224. As an estimator, I want material_cost = quantity × unit_cost.
• FR-225. As an estimator, I want labour_hours = production_quantity / productivity_rate.
• FR-226. As an estimator, I want labour_cost = labour_hours × labour_rate.
• FR-227. As an estimator, I want direct_cost = materials + labour + equipment + travel + prep.
• FR-228. As an estimator, I want overhead = configured_percentage or allocation.
• FR-229. As an estimator, I want markup applied from a configured rule.
• FR-230. As an estimator, I want subtotal = direct_cost + overhead + markup.
• FR-231. As an estimator, I want tax = configured tax calculation.
• FR-232. As an estimator, I want total = subtotal + tax.
• FR-233. As an estimator, I want gross_profit = revenue − total_cost.
• FR-234. As an estimator, I want gross_margin = gross_profit / revenue.
• FR-235. As a test engineer, I want all formulas covered by automated tests.

3.19 Measurement Engine

• FR-236. As an estimator, I want deterministic measurement calculations for walls and wall sections.
• FR-237. As an estimator, I want deterministic measurement calculations for ceilings.
• FR-238. As an estimator, I want deterministic measurement calculations for floors where applicable.
• FR-239. As an estimator, I want deterministic measurement calculations for windows.
• FR-240. As an estimator, I want deterministic measurement calculations for doors.
• FR-241. As an estimator, I want deterministic measurement calculations for trim.
• FR-242. As an estimator, I want deterministic measurement calculations for baseboards.
• FR-243. As an estimator, I want deterministic measurement calculations for casings.
• FR-244. As an estimator, I want deterministic measurement calculations for rooms.
• FR-245. As an estimator, I want deterministic measurement calculations for hallways.
• FR-246. As an estimator, I want deterministic measurement calculations for closets.
• FR-247. As an estimator, I want deterministic measurement calculations for exclusions.
• FR-248. As an estimator, I want deterministic measurement calculations for openings.
• FR-249. As an estimator, I want support for square feet, linear feet, count, dimensions, deductions, and multiple coats.
• FR-250. As an estimator, I want missing dimensions never inferred so that a structured MISSING_DATA state is returned instead.

3.20 Business Calculation Engine

• FR-251. As a business user, I want reusable calculation services for labour.
• FR-252. As a business user, I want reusable calculation services for production.
• FR-253. As a business user, I want reusable calculation services for material quantity.
• FR-254. As a business user, I want reusable calculation services for waste.
• FR-255. As a business user, I want reusable calculation services for markup.
• FR-256. As a business user, I want reusable calculation services for margin.
• FR-257. As a business user, I want reusable calculation services for overhead.
• FR-258. As a business user, I want reusable calculation services for taxes.
• FR-259. As a business user, I want reusable calculation services for travel.
• FR-260. As a business user, I want reusable calculation services for project profitability.
• FR-261. As a business user, I want reusable calculation services for estimate profitability.
• FR-262. As a business user, I want reusable calculation services for revenue.
• FR-263. As a business user, I want reusable calculation services for conversion metrics.
• FR-264. As a business user, I want reusable calculation services for job costing.
• FR-265. As a business user, I want reusable calculation services for utilization.
• FR-266. As a business user, I want reusable calculation services for productivity.
• FR-267. As a test engineer, I want every deterministic calculation to be independently testable.

3.21 Database

• FR-268. As a platform operator, I want PostgreSQL as the primary persistent datastore.
• FR-269. As a platform operator, I want normalized schemas for companies, users, roles, permissions, service_accounts, agents, crews, tasks, flows, executions, customers, leads, opportunities, projects, estimates, estimate_versions, measurements, calculation_runs, jobs, schedules, materials, inventory, purchases, invoices, payments, messages, documents, events, approvals, policies, policy_versions, audit_events, exceptions, dead_letter_items, integrations, integration_credentials_metadata, webhooks, idempotency_records, ai_model_usage, ai_cost_records, evaluation_runs, evaluation_cases, agent_versions, knowledge_versions, and system_settings.
• FR-270. As a platform operator, I want foreign keys and constraints so that referential integrity is enforced.
• FR-271. As a platform operator, I want UUID identifiers for entities.
• FR-272. As a platform operator, I want appropriate indexes so that query performance is maintained.
• FR-273. As a security engineer, I want secrets excluded from ordinary application tables.

3.22 Data Versioning

• FR-274. As a platform operator, I want estimates, pricing, policies, calculations, agents, prompts, tools, workflows, knowledge, and business configuration versioned.
• FR-275. As a platform operator, I want authoritative historical state never silently overwritten.

3.23 Event Bus

• FR-276. As a platform operator, I want an internal event architecture that emits business and AI lifecycle events including lead.created, lead.updated, estimate.requested, estimate.calculated, estimate.qa_failed, estimate.approval_requested, estimate.approved, job.created, job.started, job.completed, qc.failed, qc.passed, purchase.required, purchase.approved, invoice.created, invoice.sent, payment.received, payment.overdue, customer.message, review.requested, financial.period_closed, ai.execution.started, ai.execution.completed, ai.execution.failed, ai.policy_blocked, ai.approval_requested, and integration.failed.
• FR-277. As a platform operator, I want every event to contain event_id, event_type, company_id, source, request_id, payload, created_at, and schema_version.

3.24 Execution Engine

• FR-278. As a platform operator, I want persistent AI execution tracking with states QUEUED, RUNNING, WAITING, REVIEW, APPROVED, COMPLETED, FAILED, BLOCKED, and CANCELLED.
• FR-279. As a platform operator, I want each execution to store execution ID, request ID, company, identity, agent, crew, flow, task, status, inputs reference, output reference, errors, approvals, retries, cost, duration, timestamps, and versions.
• FR-280. As a platform operator, I want executions to be resumable.

3.25 CrewAI Adapter

• FR-281. As a platform operator, I want a clean adapter between the Python platform and the CrewAI workforce.
• FR-282. As a platform operator, I want the Python platform to control who may invoke CrewAI.
• FR-283. As a platform operator, I want the Python platform to control what context is provided to CrewAI.
• FR-284. As a platform operator, I want the Python platform to control which tools are available to CrewAI.
• FR-285. As a platform operator, I want the Python platform to control authority, company, task, policy, budget, approval, and output validation for CrewAI invocations.
• FR-286. As a platform operator, I want CrewAI to return structured results.
• FR-287. As a security engineer, I want raw agent output prohibited from directly executing external writes.

3.26 Standard AI Request / Response Contracts

• FR-288. As a platform operator, I want a standard AI request contract containing request_id, company_id, user_id, command, requested_agent, requested_crew, priority (LOW|NORMAL|HIGH|CRITICAL), context, and authorization_context.
• FR-289. As a platform operator, I want all AI request fields validated.
• FR-290. As a platform operator, I want a standard AI response contract containing request_id, execution_id, status (QUEUED|RUNNING|COMPLETED|REVIEW|BLOCKED|FAILED), result, confidence_score, confidence_level (HIGH|MEDIUM|LOW|BLOCKED), evidence, assumptions, missing_information, requested_approval, tool_actions, warnings, and errors.

3.27 API

• FR-291. As an API consumer, I want a REST API built with FastAPI.
• FR-292. As an API consumer, I want a POST /api/v1/workforce/execute endpoint.
• FR-293. As an API consumer, I want a GET /api/v1/workforce/executions/{id} endpoint.
• FR-294. As an API consumer, I want a POST /api/v1/workforce/events endpoint.
• FR-295. As an API consumer, I want a POST /api/v1/workforce/approval endpoint.
• FR-296. As an API consumer, I want a POST /api/v1/workforce/cancel endpoint.
• FR-297. As an API consumer, I want a GET /api/v1/workforce/health endpoint.
• FR-298. As an administrator, I want secured administrative/service endpoints for agents, crews, tools, policies, integrations, calculations, estimates, audit, evaluations, and system controls.
• FR-299. As a security engineer, I want every endpoint to require appropriate authentication and authorization.
• FR-300. As a security engineer, I want internal administrative endpoints never exposed publicly without protection.

3.28 Error Model

• FR-301. As a platform operator, I want standardized error codes including VALIDATION_ERROR, AUTHENTICATION_ERROR, AUTHORIZATION_ERROR, COMPANY_ACCESS_ERROR, POLICY_BLOCKED, APPROVAL_REQUIRED, MISSING_DATA, CONFLICT, NOT_FOUND, RATE_LIMITED, INTEGRATION_ERROR, TIMEOUT, MODEL_ERROR, CALCULATION_ERROR, DUPLICATE_REQUEST, SECURITY_ERROR, and INTERNAL_ERROR.
• FR-302. As a platform operator, I want a standard error response containing error_code, message, request_id, details, and retryable.
• FR-303. As a security engineer, I want errors to never expose secrets, stack traces, credentials, tokens, or sensitive internal information.

3.29 Retry Engine

• FR-304. As a platform operator, I want exponential backoff in the retry system.
• FR-305. As a platform operator, I want jitter in retries.
• FR-306. As a platform operator, I want retry limits.
• FR-307. As a platform operator, I want retry classification so that only safe operations are retried.
• FR-308. As a platform operator, I want idempotency integrated with retries.
• FR-309. As a platform operator, I want circuit breakers on failing dependencies.
• FR-310. As a platform operator, I want alternate routes where appropriate.
• FR-311. As a platform operator, I want dead-letter routing for exhausted retries.
• FR-312. As a platform operator, I want unsafe operations never retried blindly.

3.30 Dead-Letter Queue

• FR-313. As an operator, I want a persistent DLQ storing id, company_id, request_id, execution_id, source, payload_reference, error_type, error_message, retry_count, status (OPEN|RETRYING|RESOLVED|DISMISSED), and created_at.
• FR-314. As an operator, I want unresolved failures exposed to the Command Center.

3.31 Audit Engine

• FR-315. As an auditor, I want append-only audit logging.
• FR-316. As an auditor, I want authentication, authorization, policy decisions, agent execution, task creation, delegation, tool calls, external API calls, approvals, rejections, financial actions, estimates, calculations, customer communications, purchases, schedule commits, job changes, security events, policy blocks, errors, and emergency controls audited.
• FR-317. As an auditor, I want audit events containing audit_id, company_id, request_id, actor_type (HUMAN|AGENT|SERVICE|SYSTEM), actor_id, action, resource_type, resource_id, result (SUCCESS|DENIED|FAILED), reason, metadata, and timestamp.
• FR-318. As a security engineer, I want ordinary agents prohibited from deleting or altering audit records.

3.32 Observability

• FR-319. As an operator, I want structured observability tracking request duration, execution duration, API latency, tool latency, external API errors, task failures, agent failures, crew failures, retries, queue depth, model latency, tokens, AI cost, policy blocks, approvals, external writes, calculation failures, and database performance.
• FR-320. As an operator, I want correlation through request_id, execution_id, task_id, event_id, and company_id.
• FR-321. As a security engineer, I want secrets never logged.

3.33 AI Cost Management

• FR-322. As a budget owner, I want AI usage tracked by provider, model, agent, crew, task, flow, company, request, input tokens, output tokens, estimated cost, actual cost where available, and duration.
• FR-323. As a budget owner, I want per-agent budgets.
• FR-324. As a budget owner, I want per-crew budgets.
• FR-325. As a budget owner, I want per-flow budgets.
• FR-326. As a budget owner, I want a company budget.
• FR-327. As a budget owner, I want daily limits.
• FR-328. As a budget owner, I want monthly limits.
• FR-329. As a budget owner, I want an emergency shutdown for cost overruns.
• FR-330. As a budget owner, I want approval required for expensive operations.

3.34 Model Router

• FR-331. As a platform operator, I want provider-neutral model routing based on task complexity, risk, latency requirement, structured-output requirement, budget, and model availability.
• FR-332. As a platform operator, I want model routing output containing provider, model, reason, and estimated_cost.
• FR-333. As a platform operator, I want the system not hard-coded to a single model provider.

3.35 Evaluation Framework

• FR-334. As a test engineer, I want an automated evaluation system testing schema compliance.
• FR-335. As a test engineer, I want evaluation of hallucination behavior.
• FR-336. As a test engineer, I want evaluation of authority boundaries.
• FR-337. As a test engineer, I want evaluation of tool permissions.
• FR-338. As a test engineer, I want evaluation of prompt injection resistance.
• FR-339. As a test engineer, I want evaluation of company isolation.
• FR-340. As a test engineer, I want evaluation of policy enforcement.
• FR-341. As a test engineer, I want evaluation of confidence behavior.
• FR-342. As a test engineer, I want evaluation of missing-data behavior.
• FR-343. As a test engineer, I want evaluation of calculation correctness.
• FR-344. As a test engineer, I want evaluation of agent delegation.
• FR-345. As a test engineer, I want evaluation of duplicate prevention.
• FR-346. As a test engineer, I want evaluation of error recovery.
• FR-347. As a test engineer, I want evaluation of approval behavior.
• FR-348. As a test engineer, I want regression evaluation.
• FR-349. As a test engineer, I want every agent to have evaluation cases.

3.36 Required Security Tests

• FR-350. As a test engineer, I want an automated test where an unauthorized user attempts to access another company's data.
• FR-351. As a test engineer, I want an automated test where an agent attempts a restricted tool.
• FR-352. As a test engineer, I want an automated test where an agent attempts a financial transfer.
• FR-353. As a test engineer, I want an automated test where an agent attempts self-approval.
• FR-354. As a test engineer, I want an automated test where an agent attempts credential retrieval.
• FR-355. As a test engineer, I want an automated test where an agent receives a prompt injection.
• FR-356. As a test engineer, I want an automated test where a duplicate webhook is received.
• FR-357. As a test engineer, I want an automated test where a duplicate invoice operation is attempted.
• FR-358. As a test engineer, I want an automated test where an expired approval is used.
• FR-359. As a test engineer, I want an automated test where a modified approved action is executed.
• FR-360. As a test engineer, I want an automated test where an invalid company_id is supplied.
• FR-361. As a test engineer, I want an automated test where an unauthorized API endpoint is accessed.
• FR-362. As a test engineer, I want an automated test where audit tampering is attempted.
• FR-363. As a test engineer, I want an automated test where the rate limit is exceeded.
• FR-364. As a test engineer, I want an automated test where a malformed external response is returned.
• FR-365. As a test engineer, I want an automated test where an external integration is unavailable.
• FR-366. As a test engineer, I want an automated test where calculation input is missing.
• FR-367. As a test engineer, I want an automated test where the LLM attempts to override a deterministic calculation.
• FR-368. As a test engineer, I want an automated test where an agent attempts to disable guardrails.
• FR-369. As a test engineer, I want an automated test where an agent attempts recursive delegation.

3.37 Deterministic Calculation Tests

• FR-370. As a test engineer, I want extensive unit tests covering area, perimeter, linear feet, deductions, coats, coverage, gallons, waste, prep, labour, productivity, crew size, overhead, markup, tax, total, margin, profitability, rounding, edge cases, zero values, invalid values, negative values, and extreme values.
• FR-371. As a test engineer, I want calculation outputs to be deterministic.

3.38 Data Validation

• FR-372. As a platform operator, I want Pydantic schemas used at all important boundaries.
• FR-373. As a platform operator, I want validation of API requests, API responses, tool requests, tool responses, external API responses, events, webhooks, calculations, estimates, approvals, policies, and AI outputs.
• FR-374. As a security engineer, I want malformed data rejected.
• FR-375. As a security engineer, I want dangerous values never silently coerced.

3.39 Context Security

• FR-376. As a security engineer, I want a Context Builder that provides AI agents only the minimum necessary information.
• FR-377. As a security engineer, I want context to draw from company, user, authorization, task, customer, job, estimate, measurements, relevant knowledge, business rules, relevant history, and tool permissions.
• FR-378. As a security engineer, I want entire databases never automatically dumped into model context.

3.40 Prompt Injection Defense

• FR-379. As a security engineer, I want all external content treated as untrusted, including emails, customer messages, website content, uploaded documents, notes, Jobber data, QuickBooks descriptions, web content, and external API fields.
• FR-380. As a security engineer, I want external text to never grant permissions.
• FR-381. As a security engineer, I want external text to never redefine system instructions.
• FR-382. As a security engineer, I want external text to never request credentials.
• FR-383. As a security engineer, I want external text to never modify policy.
• FR-384. As a security engineer, I want external text to never authorize actions.
• FR-385. As a security engineer, I want external text to never override security.
• FR-386. As a security engineer, I want external text to never alter company identity.

3.41 Emergency Controls

• FR-387. As an operator, I want a PAUSE_ALL_AGENTS control.
• FR-388. As an operator, I want a PAUSE_AGENT control.
• FR-389. As an operator, I want a PAUSE_CREW control.
• FR-390. As an operator, I want a PAUSE_FLOW control.
• FR-391. As an operator, I want a DISABLE_EXTERNAL_WRITES control.
• FR-392. As an operator, I want a DISABLE_FINANCIAL_ACTIONS control.
• FR-393. As an operator, I want a DISABLE_CUSTOMER_MESSAGES control.
• FR-394. As an operator, I want a DISABLE_MARKETING control.
• FR-395. As an operator, I want a FORCE_HUMAN_APPROVAL control.
• FR-396. As an operator, I want a RESUME_SYSTEM control.
• FR-397. As a security engineer, I want emergency state enforced by backend services so that CrewAI cannot override it.

3.42 Health System

• FR-398. As an operator, I want a GET /health endpoint.
• FR-399. As an operator, I want a GET /ready endpoint.
• FR-400. As an operator, I want a GET /live endpoint.
• FR-401. As an operator, I want a GET /metrics endpoint.
• FR-402. As an operator, I want health checks covering the database, Redis, workers, event bus, Jobber, QuickBooks, email, model providers, tool gateway, and calculation engine.
• FR-403. As an operator, I want states separated into LIVE, READY, DEGRADED, and FAILED.

3.43 Configuration

• FR-404. As a platform operator, I want configuration externalized via environment/configuration for database, Redis, API ports, external integrations, model providers, feature flags, budgets, retry policies, timeouts, rate limits, and security settings.
• FR-405. As a security engineer, I want secrets never hard-coded.
• FR-406. As a platform operator, I want a .env.example providing variable names only.

3.44 Secrets

• FR-407. As a security engineer, I want secure secret references supported.
• FR-408. As a security engineer, I want secrets never committed, printed, logged, exposed to agents, returned through APIs, or placed in prompts.
• FR-409. As a security engineer, I want plaintext credentials never stored unnecessarily.
• FR-410. As a platform operator, I want the design to support future integration with Vault, cloud secret managers, and encrypted environment configuration.

3.45 Infrastructure

• FR-411. As a platform operator, I want a production-ready Dockerfile.
• FR-412. As a platform operator, I want docker-compose.yml.
• FR-413. As a platform operator, I want docker-compose.dev.yml.
• FR-414. As a platform operator, I want docker-compose.test.yml.
• FR-415. As a platform operator, I want services for api, worker, scheduler, database, and redis.
• FR-416. As a platform operator, I want no unnecessary infrastructure required.

3.46 Migrations

• FR-417. As a platform operator, I want Alembic used for migrations.
• FR-418. As a platform operator, I want an initial schema migration.
• FR-419. As a platform operator, I want index migrations.
• FR-420. As a platform operator, I want constraint migrations.
• FR-421. As a platform operator, I want versioning in migrations.
• FR-422. As a platform operator, I want a rollback strategy.
• FR-423. As a platform operator, I want production schema never modified manually through application startup.

3.47 Project Structure

• FR-424. As a developer, I want the project structured as synergy_python_services/ with app/ subpackages: api, auth, authorization, policies, approvals, agents, crews, orchestration, tools, integrations, calculations, estimating, persistence, models, schemas, events, workers, audit, observability, evaluation, security, configuration, exceptions, and main.py.
• FR-425. As a developer, I want tests/ containing unit, integration, security, evaluation, calculations, and regression suites.
• FR-426. As a developer, I want migrations/, scripts/, config/, docs/, Dockerfile, docker-compose.yml, requirements.txt, pyproject.toml, .env.example, and README.md present at the project root.
• FR-427. As a developer, I want clear separation of responsibilities preserved even if structure is technically adjusted.

3.48 Code Quality

• FR-428. As a developer, I want type hints throughout.
• FR-429. As a developer, I want clear naming conventions.
• FR-430. As a developer, I want modular services.
• FR-431. As a developer, I want dependency injection.
• FR-432. As a developer, I want reusable interfaces.
• FR-433. As a developer, I want consistent error handling.
• FR-434. As a developer, I want structured logging.
• FR-435. As a developer, I want tests for all required functionality.
• FR-436. As a developer, I want documentation.
• FR-437. As a developer, I want no dead code.
• FR-438. As a developer, I want no fake implementations.
• FR-439. As a developer, I want no TODO placeholders for required functionality.
• FR-440. As a developer, I want no hard-coded secrets.
• FR-441. As a developer, I want no hidden side effects.

3.49 API Versioning

• FR-442. As a developer, I want the /api/v1/ version prefix so that future versions can coexist.
• FR-443. As a developer, I want breaking changes to require explicit versioning.

3.50 Performance

• FR-444. As an operator, I want optimization for low latency reads.
• FR-445. As an operator, I want long-running work handled asynchronously.
• FR-446. As an operator, I want parallel independent operations.
• FR-447. As an operator, I want caching where safe.
• FR-448. As an operator, I want database indexes.
• FR-449. As an operator, I want connection pooling.
• FR-450. As an operator, I want deduplication.
• FR-451. As an operator, I want batching.
• FR-452. As an operator, I want minimal model calls.
• FR-453. As an operator, I want deterministic calculations for math.
• FR-454. As an operator, I want queue-based execution.
• FR-455. As an operator, I want authorization and auditability never sacrificed for performance.

3.51 Reliability

• FR-456. As an operator, I want the platform to survive temporary database failures.
• FR-457. As an operator, I want the platform to survive Redis failures.
• FR-458. As an operator, I want the platform to survive external API failures.
• FR-459. As an operator, I want the platform to survive model failures.
• FR-460. As an operator, I want the platform to survive network failures.
• FR-461. As an operator, I want the platform to survive worker crashes.
• FR-462. As an operator, I want the platform to survive duplicate events.
• FR-463. As an operator, I want the platform to survive partial execution.
• FR-464. As an operator, I want the platform to survive timeouts.
• FR-465. As an operator, I want the platform to survive malformed external data.
• FR-466. As an operator, I want no consequential action silently lost.
• FR-467. As an operator, I want state persisted before relying on asynchronous processing.

3.52 Backup / Recovery Design

• FR-468. As an operator, I want infrastructure design for database backup.
• FR-469. As an operator, I want point-in-time recovery where supported.
• FR-470. As an operator, I want migration recovery.
• FR-471. As an operator, I want configuration backup.
• FR-472. As an operator, I want audit preservation.
• FR-473. As an operator, I want DLQ recovery.
• FR-474. As an operator, I want event replay.
• FR-475. As an operator, I want disaster recovery design.
• FR-476. As an operator, I want destructive recovery never performed automatically.

3.53 Event Replay

• FR-477. As an operator, I want controlled event replay that authenticates the operator.
• FR-478. As an operator, I want replay to validate authorization.
• FR-479. As an operator, I want replay to preserve the original event.
• FR-480. As an operator, I want replay to generate a replay event ID.
• FR-481. As an operator, I want replay to enforce idempotency.
• FR-482. As an operator, I want replay to record an audit event.
• FR-483. As an operator, I want replay to prevent duplicate consequential actions.

3.54 Future Extensibility

• FR-484. As a platform architect, I want the architecture to support future modules for HR, safety, fleet, equipment, inventory, contracts, legal, customer success, revenue management, purchasing, business development, expansion, additional companies, additional AI agents, additional crews, and additional integrations without redesign.
• FR-485. As a platform architect, I want all future modules to use the same security and authority framework.

3.55 Company Operating Model

• FR-486. As an administrator, I want business configuration treated as data so that it is not hard-coded inside agents.
• FR-487. As an administrator, I want configurable company profile.
• FR-488. As an administrator, I want configurable services.
• FR-489. As an administrator, I