# Build Engine — full implementation plan

**Plan baseline:** 24 October 2026 · Odoo20 + React · 164 stories · repository baseline `5b3f3f7` plus current uncommitted work.

This is the delivery plan to reach a production pilot with accepted CRM, Sales, Purchase, Saudi accounting and construction workflows. It is not a claim that the current system is complete. Current status under the React end-user requirement in [ADR0014](../adr/0014-react-as-end-user-application.md), refreshed from Checkpoint 290 on 2026-10-27: **18 DONE, 125 PARTIAL, 11 MISSING, 10 BLOCKED**. React supports guarded RFI workflows, crew-overlap warnings, quality/safety checklists, technical-proposal drafting/review (BE-031/035), a financial proposal draft from confirmed Odoo pricing (BE-032), and a saved private approval PDF preview (BE-034). These stories remain PARTIAL pending their listed acceptance criteria. **76.2% PARTIAL is a classification share, not an overall completion percentage; 11.0% is fully verified DONE.** See the [traceability matrix](../REQUIREMENTS_TRACEABILITY.md), [capability comparison](BUILD_ENGINE_CAPABILITY_COMPARISON.html), [open decisions](../OPEN_DECISIONS.md) and [current QA evidence](../TEST_RESULTS.md).

The visual status and indicative calendar are available in the standalone [Build Engine project roadmap](../../frontend/public/build-engine-project-roadmap.html), also served at `http://127.0.0.1:3200/build-engine-project-roadmap.html`.

## Delivery rules

1. Preserve Odoo as system of record and business-rule engine; React is the end-user application for every launch-scope workflow. Build React screens over native Odoo models and permission-checked BFF APIs. Do not copy standard ERP data or business rules into a parallel frontend backend.
2. Deliver vertical workflows: lead → qualified opportunity → tender/quote → award → project/approved BOQ → procurement/receipt → site usage → analytic cost → customer invoice/payment → closeout. A set of disconnected menus does not count as a complete workflow.
3. Keep the original story contract and priority. Under ADR0014, every DONE story also needs its required React user journey, with authorized create/edit/read, invalid-input atomicity, reopened state and audit context, denial for unauthorized/company/project boundaries, bilingual errors and the story-specific browser path. Native Odoo-only UI does not meet the current end-user requirement.
4. Keep staging evidence separate from customer acceptance. The Saudi demonstration company is synthetic; its posted entries, reports and six local-model smoke calls are not an audited company close, legal opinion, load test or production rollout.
5. Turn unresolved provider access into a real dependency, not a mocked claim. Develop stubs and fixtures while awaiting approval, but leave the portal story BLOCKED until the provider sandbox and owner acceptance pass.
6. Do not promote a story by counting tests. Maintain the status and evidence row in the matrix after every accepted vertical slice. Retain failed/skipped test names and explain conditional skips.

## Program phases and exit gates

| Phase | Outcome and story scope | Dependencies / exit gate |
|---|---|---|
| **0 · Confirm demo and launch decisions** | Preserve the working 164-story backlog; reconcile with the signed BRD/contract and name product, finance, construction, integration and acceptance owners. Separate decisions needed for safe synthetic-data work from launch decisions on tenant model, identity, approvals, offline actions, Saudi services, retention and service targets. | Track DEC-01–11 with an owner/date. Do not block deterministic work on synthetic data. The original BRD is not independently confirmed in this checkout, so the matrix remains a working baseline. |
| **1 · Finance and connected business workflows** | BE-077–086 plus connected CRM/sales/tender/project/procurement flows BE-009–018, BE-029–038, BE-039–068. Extend native Odoo accounting, CRM, sales, purchase, stock and analytics. Connect awarded lead → project/BOQ → quote/order → PO/receipt/vendor bill → project analytic cost → customer invoice/payment. Complete KSA chart/tax policy, bank matching and reports. | Finance owner and qualified Saudi accountant; DEC-02/04/06. Rehearse migration from overlapping accounting addons. Gate: synthetic commercial case reconciles quote, commitment, receipt, bill, project cost, invoice, payment and reports; accountant signs statutory cases before launch. No ZATCA production submission without owner authorization. |
| **2 · Remaining project planning and cost controls** | BE-039–058 and remaining BE-059–068. Finish task dependencies/resource assignment/Gantt/baselines/milestones, versioned BOQ import/approval, variation controls, approved suppliers, material request, RFQ comparison, approval separation, receipt and landed cost. | Phase1, DEC-06/09. Gate: awarded opportunity advances through approved baseline and supplier award; quantities, commitments and analytic actual reconcile; invalid versions and unauthorized approvals roll back. |
| **3 · Remaining construction and field collaboration** | BE-069–076; BE-087–123; BE-124–129; BE-133–139. Complete site inventory, time/attendance controls, assets, quality/safety/NCR, submittals, RFI/site reports, contracts/helpdesk, project documents and workflow lifecycle. | Phases1–2 and DEC-03/06/08/09. Gate: site and approver roles complete a synthetic build scenario with evidence, valid transitions, actor/timestamps and company/project boundaries; required quality gates prevent unsafe progression. |
| **4 · Offline, mobile, imports and archives** | BE-113/114, BE-125–132 and BE-140–147. Finish offline queue, conflict resolution, idempotent retries, Excel import/export, attachment sync and archive packs. | DEC-07/08/11. Gate: assigned user syncs drafts after soak, resolves concurrent edits, retries without duplicates, sees rejection reasons and retrieves versioned files. Final approvals stay online unless a safe offline signature model is accepted. |
| **5 · AI agents with evaluated, human-approved actions** | BE-019–028, BE-029–038 and BE-148–157. Finish discovery/qualification/proposal and project planning/sequence/risk/BOQ/RFQ/variation/RFI/site-report/closeout suggestions. | DEC-02/05, role-scoped context and approved sources. Gate: Arabic/English evaluation set, citations/freshness/confidence, approve/edit/reject feedback, audit/replay and denied-tool tests. Local model availability alone does not complete stories; AI cannot silently send bids or post financial entries. |
| **6 · Saudi portals and regulated integrations** | Service-specific slices of BE-020/022 and BE-082/083/085, plus integrations required by accepted contracts. Build separate adapters for selected Etimad, Balady, Ejar/Wafi, ZATCA and bank services. DGA standards assessment is separate from API connectivity. | Each service needs an owner, named product, permission/contract, official docs, scoped credentials and sandbox acceptance. No generic “all DGA portals” claim. |
| **7 · Dashboards, notifications and workflow closeout** | BE-158–164; closeout BE-048/108/115/123/132/157 after upstream work lands. Complete portfolio/margin, budget-v-actual, cash/AR/AP, risk/gates, drilldowns, notifications, exports and rollout preparation. | Source data and DEC-10 NFRs. Gate: dashboard totals reconcile to source records, roles/exports are tested and pilot scripts are accepted. |
| **8 · Final security hardening and production rollout** | Final threat model, cross-tenant/project boundary review, identity/secrets/object-store checks, dependency/license scan, backup/restore, load/soak, incident procedures and tenant-by-tenant migration/rollback. Includes production gates for BE-001–008 and BE-130–132. | Final release gate. Feature-level authorization and validation remain required in every implementation phase. No production customer data until identity, isolation, restore, audit and access checks pass; DEC-01/11 and approved NFRs required. |

## Complete story coverage by workstream

Story IDs are shown verbatim so no epic gets lost between phases. Status counts are from the existing matrix; they are not forecasts. `D/P/M/B` means DONE/PARTIAL/MISSING/BLOCKED.

| Epic | Story IDs | Current D/P/M/B | Plan phase |
|---|---|---:|---|
| Platform, tenancy and onboarding | BE-001–008 | 0/6/2/0 | 8 |
| CRM, tenders and opportunities | BE-009–018 | 4/6/0/0 | 1 |
| Business development AI | BE-019–028 | 1/2/5/2 | 5,6 |
| Sales AI and proposals | BE-029–038 | 0/8/1/1 | 1,5 |
| Projects and scheduling | BE-039–048 | 0/10/0/0 | 1,2,7 |
| BOQ, BOM and cost control | BE-049–058 | 1/9/0/0 | 1,2 |
| Procurement and suppliers | BE-059–068 | 1/9/0/0 | 1,2 |
| Inventory and warehouses | BE-069–076 | 4/3/0/1 | 2,5 |
| Accounting and ZATCA | BE-077–086 | 0/7/0/3 | 1,6 |
| HR and timesheets | BE-087–092 | 0/5/0/1 | 5 |
| Assets and maintenance | BE-093–099 | 2/5/0/0 | 2,5 |
| Quality, inspections and safety | BE-100–108 | 1/7/0/1 | 5,9 |
| RFI, submittals and site reporting | BE-109–115 | 3/4/0/0 | 5,6 |
| Contracts and client helpdesk | BE-116–123 | 0/8/0/0 | 5 |
| Documents, drawings and knowledge | BE-124–132 | 1/5/2/1 | 1,5,6 |
| No-code workflow engine | BE-133–139 | 0/7/0/0 | 5 |
| Offline and Excel | BE-140–147 | 0/8/0/0 | 6 |
| Project management AI | BE-148–157 | 1/7/2/0 | 7 |
| Owner dashboards and notifications | BE-158–164 | 0/6/1/0 | 7 |
| **Total** | **BE-001–164** | **18/125/11/10** | **All phases** |

The plan may order stories within an epic by dependency, but it does not change the approved matrix status or original priority. P0 requirements lead the scope in each phase; P1/P2 follow once the shared workflow foundation is accepted. A blocked story can have useful engineering progress, but only move to DONE after its external dependency and full criteria pass.

## Cross-cutting acceptance for every story

Use the existing story acceptance contract plus these release checks. Record evidence links in the same traceability row:

- **Access and persistence:** correct authenticated Odoo user, company/project and role; create/edit/read/reopen the record through the intended UI/API; server-side validation and audit actors/timestamps/version.
- **Failure safety:** missing, malformed, stale and forbidden inputs produce field-level/actionable errors; multi-record failures leave no partial business transactions; retries are idempotent.
- **Isolation:** another company, private project, restricted role, portal user and anonymous caller receive denial without protected record contents; prove this through native API and browser routes.
- **Business linkage:** expected native records/relationships/reconciliation exist (e.g. quote→project, BOQ→RFQ→receipt→bill→analytic, milestone→invoice→payment→bank match).
- **Arabic/accessibility:** full user-facing EN/AR labels and errors, correct RTL on actual forms/PDF where required, phone layout, keyboard focus, screen-reader labels, and searchable/exportable documents where the story requires them.
- **Verification:** module-level test, service/API integration, real-browser role journey, data-integrity/security cases and a deterministic synthetic fixture; no story is certified by mocks alone.

## External decisions and start-now work

| Decision | Owner input needed | Engineering that can start now |
|---|---|---|
| DEC-01 hosting/tenant rollout | Customer tenancy model, KSA hosting/domain, deployment artifact and onboarding | Keep stacks isolated; production readiness checklist and reproducible staging install |
| DEC-02 agent write/approval policy | Choose approval artifact and business actor/audit boundary | Evaluate current suggestion/human-approval path; keep local QA adviser read-only |
| DEC-03 payroll | Inputs-only vs full payroll; approved GOSI/WPS formats/rates | Protect employee data; test configurable exports with synthetic data |
| DEC-04 ZATCA | Invoice types/Phase2, authorized operator/OTP, Simulation credentials and owner approval | Build configuration checks/fixtures; no live call or certification claim |
| DEC-05 Etimad/discovery | Approved API products/data rights/scopes, business account and subscription owner | Source-allowlist boundary, import schema, dedupe and mock fixture tests |
| DEC-06 approval matrix | Named approvers/delegates and separation-of-duties per transaction | Implement least privilege and rejected-write tests around agreed existing roles |
| DEC-07 offline | Draft vs final actions, conflict authority and agreed soak period | Fix cursor/idempotency and draft queue under migration-safe API version |
| DEC-08 files | Formats, preview quality and converter/license policy | Harden private attachments and version linking; defer unsupported converters |
| DEC-09 engineering references | Qualified owner and update source for Saudi code/checkpoints | Store source/date/version in configurable test fixtures |
| DEC-10 operations | Read/load targets, SLO, retention, backup/restore RPO/RTO and pilot scope | Build reproducible measures; do not publish unmeasured targets |
| DEC-11 identity/storage | OIDC issuer/audience/claims, KSA object-store choice, key/retention policy | Trusted tenant derivation, project ACLs, abstraction and failure tests |

## Definition of pilot readiness

The pilot is ready when all agreed launch-scope P0 and their mandatory dependencies are DONE, every launch-scope P1 is either DONE or explicitly accepted with a named owner/control, finance and project data reconcile, production identity and archive scopes are proven, required provider connections have sandbox acceptance, and migration/restore/security/accessibility/field scenario checks pass. The complete backlog can continue beyond the first pilot; any deferred stories and controls must be named. No percentage should hide these scope decisions.

The next execution step is to audit React screen/API coverage across all 164 stories, then complete the finance and connected CRM→project/BOQ→purchase→invoice journey in React over native Odoo. Continue remaining construction, offline, AI and individually approved portal integrations in the same React-first vertical-slice pattern. Keep feature-level authorization in each change; perform the final cross-tenant security and rollout gate last. Resolve business decisions in parallel where they do not block synthetic-data work.

## Staffing and schedule

Indicative calendar: **12–18 months** with 3–5 cross-functional full-time equivalents and timely product, Saudi accountant, construction/site and QA participation; **18–30 months** with a 1–2 person team. The estimate assumes overlapping phases only after dependencies and data/security gates stabilize. It excludes provider-access delays, signed-scope changes, migration surprises and extended field/offline soak. It is a planning range, not a committed delivery date; re-estimate after capacity, DEC-01/02/04–11 and the pilot scope are confirmed. Phase bands and assumptions are in the [HTML roadmap](../../frontend/public/build-engine-project-roadmap.html).
