docs(m4): reconcile roadmap CSVs with target schema

CHANGELOG.md

@@ -21,3 +21,6 @@
 | 2026-02-24 | 0.1.16 | Added M4 target schema blueprint doc with first-principles modular model, constraints, and migration phases. |
 | 2026-02-24 | 0.1.17 | Added full current-schema mermaid model relationship map to the M4 target schema blueprint. |
 | 2026-02-24 | 0.1.18 | Updated schema blueprint with explicit multi-tenant stakeholder model and phased RBAC rollout with shadow mode before enforcement. |
+| 2026-02-24 | 0.1.19 | Added customer stakeholder-wheel mapping and future stakeholder extension model to the M4 schema blueprint. |
+| 2026-02-25 | 0.1.20 | Added roadmap CSV schema-reconciliation document with stakeholder capability matrix and concrete schema gap analysis. |
+| 2026-02-25 | 0.1.21 | Updated target schema blueprint with roadmap-evidence section plus attendance/offense, stakeholder-network, and settlement-table coverage. |

docs/MILESTONES/M4/planning/m4-roadmap-csv-schema-reconciliation.md

@@ -0,0 +1,160 @@
+# M4 Roadmap CSV Schema Reconciliation
+
+Status: Draft for implementation alignment  
+Date: 2026-02-25  
+Owner: Technical Lead
+
+## 1) Why this exists
+We reviewed the original product-roadmap exports to confirm that the target schema can support all stakeholder lanes as the platform grows.
+
+This avoids two failure modes:
+1. Building command APIs on top of a schema that cannot represent required workflows.
+2. Hard-coding today's customer setup in a way that blocks future staffing companies.
+
+## 2) Inputs reviewed
+All 13 roadmap exports from `/Users/wiel/Downloads`:
+1. `Krow App – Roadmap - Business App_ Google, Nvidia.csv`
+2. `Krow App – Roadmap - Client_ Google, Nvidia.csv`
+3. `Krow App – Roadmap - Compass- The Operator.csv`
+4. `Krow App – Roadmap - Employee App.csv`
+5. `Krow App – Roadmap - Features.csv`
+6. `Krow App – Roadmap - FoodBuy- Procurement.csv`
+7. `Krow App – Roadmap - KROW Dashboard.csv`
+8. `Krow App – Roadmap - Offenses.csv`
+9. `Krow App – Roadmap - Partner.csv`
+10. `Krow App – Roadmap - Roadmap.csv`
+11. `Krow App – Roadmap - Sectors_ BA, Flik ( The executors).csv`
+12. `Krow App – Roadmap - The Workforce_ Employees.csv`
+13. `Krow App – Roadmap - Vendor_ Legendary (Staffing).csv`
+
+Parsed signal:
+1. 983 non-empty task lines.
+2. 1,263 planning rows with task/status/priority/reference signals.
+
+## 3) What the roadmap is clearly asking for
+Cross-file recurring capabilities:
+1. Multi-party org model: client, operator, vendor, procurement, workforce, partner, sector execution.
+2. Orders and shift operations: recurring events, assignment, coverage, schedule management.
+3. Attendance and policy enforcement: clock-in/out, no-show, tardiness, cancellation, offense ladders.
+4. Compliance and document verification: certifications, insurance, legal docs, renewals, risk alerts.
+5. Finance and settlement: invoice lifecycle, disputes, remittance, payment history, aging, payroll/earnings.
+6. Reporting and prediction: dashboards, KPI, forecasting, scenario planning.
+
+Repeated examples across many sheets:
+1. `Vendor Onboarding`, `Service Locations`, `Compliance`, `Certifications`.
+2. `All Invoices (Open/Pending/Overdue/Paid...)`, `Payment Summary`, `Remittance Advice Download`.
+3. Offense progression rules in `Offenses.csv` and `Employee App.csv` (warning -> suspension -> disable/block).
+
+## 4) Stakeholder capability matrix (from roadmap exports)
+
+| Stakeholder lane | Org network | Orders and shifts | Attendance and offense | Compliance docs | Finance | Reporting |
+|---|---|---|---|---|---|---|
+| Client (Google, Nvidia) | Yes | Yes | Partial (visibility) | Yes | Yes | Yes |
+| Vendor (Legendary) | Yes | Yes | Yes | Yes | Yes | Yes |
+| Workforce (Employee app) | Limited | Yes | Yes | Yes | Earnings focus | Limited |
+| Operator (Compass) | Yes | Yes | KPI visibility | Yes | Yes | Yes |
+| Procurement (FoodBuy) | Yes | KPI/SLA focus | KPI/SLA focus | Yes | Yes | Yes |
+| KROW Dashboard | Cross-entity | Cross-entity | Cross-entity risk | Cross-entity | Cross-entity | Heavy |
+| Partner | Basic | Basic | Minimal | Yes | Basic | Basic |
+
+Implication:
+1. This is a multi-tenant, multi-party workflow platform, not a single-role CRUD app.
+2. Schema must separate party identity, party relationships, and role-based permissions from workflow records.
+
+## 5) Reconciliation against current Data Connect schema
+
+What already exists and is useful:
+1. Core scheduling entities: `orders`, `shifts`, `shift_roles`, `applications`, `assignments`.
+2. Workforce entities: `staffs`, `workforce`, `staff_roles`.
+3. Financial entities: `invoices`, `recent_payments`, `vendor_rates`.
+4. Compliance entities: `documents`, `staff_documents`, `certificates`.
+
+Current structural gaps for roadmap scale:
+1. No tenant boundary key on core tables (`tenant_id` missing).
+2. No first-class stakeholder profile/link model for buyer/operator/partner/sector relationships.
+3. Attendance history is not first-class (check in/out only inside `applications`).
+4. No offense policy, offense event, or enforcement action tables.
+5. Finance is coarse (invoice + recent payment), missing line items, payment runs, remittance artifact model.
+6. Sensitive bank fields are currently modeled directly in `accounts` (`accountNumber`, `routeNumber`).
+7. Many core workflow fields are JSON (`orders.assignedStaff`, `orders.shifts`, `shift.managers`, `assignment.managers`).
+8. Money still uses float in critical tables.
+
+Connector boundary gap:
+1. 147 Data Connect mutation operations exist.
+2. 36 of those are high-risk core workflow mutations (`order`, `shift`, `shiftRole`, `application`, `assignment`, `invoice`, `vendor`, `business`, `workForce`, `teamMember`, `account`).
+
+## 6) Target schema additions required before full command rollout
+
+### 6.1 Tenant and stakeholder graph
+1. `tenants`
+2. `tenant_memberships`
+3. `stakeholder_types`
+4. `stakeholder_profiles`
+5. `stakeholder_links`
+6. `role_bindings` (scoped to tenant/team/hub/business/vendor/resource)
+
+### 6.2 Attendance and timesheet reliability
+1. `attendance_events` (append-only clock-in/out/NFC/manual-corrected)
+2. `attendance_sessions` (derived per shift role assignment)
+3. `timesheets` (approval state and pay-eligible snapshot)
+4. `timesheet_adjustments` (manual corrections with audit reason)
+
+### 6.3 Offense and policy enforcement
+1. `offense_policies` (per tenant or per business)
+2. `offense_rules` (threshold and consequence ladder)
+3. `offense_events` (who, what, when, evidence)
+4. `enforcement_actions` (warning, suspension, disable, block-from-client)
+
+### 6.4 Compliance and verification
+1. `verification_jobs`
+2. `verification_reviews`
+3. `verification_events`
+4. `compliance_requirements` (per role, tenant, business, or client contract)
+
+### 6.5 Finance completeness
+1. `invoice_line_items`
+2. `invoice_status_history`
+3. `payment_runs`
+4. `payment_allocations`
+5. `remittance_documents`
+6. `account_token_refs` (tokenized provider refs, no raw account/routing)
+
+## 7) Minimal target relationship view
+
+```mermaid
+erDiagram
+  TENANT ||--o{ TENANT_MEMBERSHIP : has
+  TENANT ||--o{ STAKEHOLDER_PROFILE : has
+  STAKEHOLDER_PROFILE ||--o{ STAKEHOLDER_LINK : links_to
+
+  TENANT ||--o{ BUSINESS : owns
+  TENANT ||--o{ VENDOR : owns
+  BUSINESS ||--o{ ORDER : requests
+  VENDOR ||--o{ ORDER : fulfills
+  ORDER ||--o{ SHIFT : expands_to
+  SHIFT ||--o{ SHIFT_ROLE : requires
+  SHIFT_ROLE ||--o{ APPLICATION : receives
+  APPLICATION ||--o{ ASSIGNMENT : becomes
+
+  ASSIGNMENT ||--o{ ATTENDANCE_EVENT : emits
+  ASSIGNMENT ||--o{ TIMESHEET : settles
+  OFFENSE_POLICY ||--o{ OFFENSE_RULE : defines
+  ASSIGNMENT ||--o{ OFFENSE_EVENT : may_trigger
+  OFFENSE_EVENT ||--o{ ENFORCEMENT_ACTION : causes
+
+  ORDER ||--o{ INVOICE : bills
+  INVOICE ||--o{ INVOICE_LINE_ITEM : contains
+  PAYMENT_RUN ||--o{ PAYMENT_ALLOCATION : allocates
+  INVOICE ||--o{ PAYMENT_ALLOCATION : receives
+  PAYMENT_RUN ||--o{ REMITTANCE_DOCUMENT : publishes
+```
+
+## 8) First-principles rules we should lock now
+1. Every command-critical table includes `tenant_id`.
+2. High-risk writes go through command APIs only.
+3. Money uses exact numeric type (or integer cents), never float.
+4. Core workflow state is relational and constrained, not JSON blobs.
+5. Every irreversible state change has append-only audit event rows.
+
+## 9) Decision
+This roadmap evidence supports continuing with the target architecture direction (command boundary + multi-tenant schema), but we should add attendance/offense/settlement/stakeholder-graph tables before full command rollout on mission-critical flows.

docs/MILESTONES/M4/planning/m4-target-schema-blueprint.md

@@ -1,7 +1,7 @@
 # M4 Target Schema Blueprint (Command-Ready)
 
 Status: Draft for team alignment  
-Date: 2026-02-24  
+Date: 2026-02-25  
 Owner: Technical Lead
 
 ## 1) Goal
@@ -36,6 +36,49 @@ flowchart LR
   V --> O
 ```
 
+## 1.2 Stakeholder wheel mapping (current baseline)
+The stakeholder labels from the customer workshop map to schema as follows:
+
+1. Buyer (Procurements):
+- Buyer users inside a business/client account.
+- Schema anchor: `users` + `tenant_memberships` + `team_members` (procurement team scope).
+2. Enterprises (Operator):
+- Tenant operator/admin users running staffing operations.
+- Schema anchor: `tenants`, `team_members`, command-side permissions.
+3. Sectors (Execution):
+- Operational segments or business units executing events.
+- Schema anchor: `teams`, `team_hubs`, `team_hud_departments`, `roles`.
+4. Approved Vendor:
+- Supplier companies approved to fulfill staffing demand.
+- Schema anchor: `vendors`, `workforce`, `vendor_rates`, `vendor_benefit_plans`.
+5. Workforce:
+- Individual workers/staff and their assignments.
+- Schema anchor: `staffs`, `staff_roles`, `applications`, `assignments`, `certificates`, `staff_documents`.
+6. Partner:
+- External integration or service partner (future).
+- Schema anchor: `stakeholder_profiles` extension path + scoped role bindings.
+
+Rule:
+1. Start with baseline stakeholders above.
+2. Add new stakeholders via extension tables and role bindings, not by changing core scheduling and finance tables.
+
+## 1.3 Future stakeholder expansion model
+To add stakeholders later without breaking core schema:
+1. Add `stakeholder_types` (registry).
+2. Add `stakeholder_profiles` (`tenant_id`, `type`, `status`, `metadata`).
+3. Add `stakeholder_links` (relationship graph across stakeholders).
+4. Bind permissions through `role_bindings` with scope (`tenant`, `team`, `hub`, `business`, or specific resource).
+
+## 1.4 Roadmap CSV evidence snapshot
+Evidence source:
+1. `docs/MILESTONES/M4/planning/m4-roadmap-csv-schema-reconciliation.md`
+
+What the exports confirmed:
+1. The product is multi-party and multi-tenant by design (client, operator, vendor, workforce, procurement, partner, dashboard).
+2. Attendance and offense enforcement are core business workflows, not side features.
+3. Finance requires more than invoices (payment runs, remittance, status history, dispute/audit trace).
+4. Compliance requires asynchronous verification and requirement templates by tenant/business/role.
+
 ## 2) First-principles rules
 1. Every critical write must be server-mediated and transactional.
 2. Tenant boundaries must be explicit in data and queries.
@@ -171,6 +214,33 @@ Rules:
 1. Every command write emits a domain event.
 2. Idempotency scope: `(actor_uid, route, idempotency_key)`.
 
+## 4.9 Attendance, Timesheets, and Offense Governance
+Tables:
+1. `attendance_events` (append-only: clock-in/out, source, correction metadata)
+2. `attendance_sessions` (derived work session per assignment)
+3. `timesheets` (approval-ready payroll snapshot)
+4. `timesheet_adjustments` (manual edits with reason and actor)
+5. `offense_policies` (tenant/business scoped policy set)
+6. `offense_rules` (threshold ladder and consequence)
+7. `offense_events` (actual violation events)
+8. `enforcement_actions` (warning, suspension, disable, block)
+
+Rules:
+1. Attendance corrections are additive events, not destructive overwrites.
+2. Offense consequences are computed from policy + history and persisted as explicit actions.
+3. Manual overrides require actor, reason, and timestamp in audit trail.
+
+## 4.10 Stakeholder Network Extensibility
+Tables:
+1. `stakeholder_types` (buyer, operator, vendor, workforce, partner, future types)
+2. `stakeholder_profiles` (tenant-scoped typed profile)
+3. `stakeholder_links` (explicit relationship graph between profiles)
+
+Rules:
+1. New stakeholder categories are added by data, not by schema rewrites to core workflow tables.
+2. Permission scope resolves through role bindings plus stakeholder links where needed.
+3. Scheduling and finance records remain stable while stakeholder topology evolves.
+
 ## 5) Target core model (conceptual)
 
 ```mermaid
@@ -196,6 +266,11 @@ erDiagram
   STAFF ||--o{ APPLICATION : applies
   SHIFT_ROLE ||--o{ ASSIGNMENT : allocates
   WORKFORCE ||--o{ ASSIGNMENT : executes
+  ASSIGNMENT ||--o{ ATTENDANCE_EVENT : emits
+  ASSIGNMENT ||--o{ TIMESHEET : settles
+  OFFENSE_POLICY ||--o{ OFFENSE_RULE : defines
+  ASSIGNMENT ||--o{ OFFENSE_EVENT : may_trigger
+  OFFENSE_EVENT ||--o{ ENFORCEMENT_ACTION : causes
 
   STAFF ||--o{ CERTIFICATE : has
   STAFF ||--o{ STAFF_DOCUMENT : uploads
@@ -207,10 +282,16 @@ erDiagram
   ORDER ||--o{ INVOICE : billed_by
   INVOICE ||--o{ RECENT_PAYMENT : settles
   TENANT ||--o{ ACCOUNT_TOKEN_REF : payout_method
+  INVOICE ||--o{ INVOICE_LINE_ITEM : details
+  PAYMENT_RUN ||--o{ PAYMENT_ALLOCATION : allocates
+  INVOICE ||--o{ PAYMENT_ALLOCATION : receives
+  PAYMENT_RUN ||--o{ REMITTANCE_DOCUMENT : publishes
 
   ORDER ||--o{ DOMAIN_EVENT : emits
   SHIFT ||--o{ DOMAIN_EVENT : emits
   ASSIGNMENT ||--o{ DOMAIN_EVENT : emits
+  STAKEHOLDER_TYPE ||--o{ STAKEHOLDER_PROFILE : classifies
+  STAKEHOLDER_PROFILE ||--o{ STAKEHOLDER_LINK : relates
 ```
 
 ## 6) Command write boundary on this schema
@@ -234,6 +315,8 @@ flowchart LR
 4. `workforce`: unique active `(vendor_id, staff_id)`.
 5. `team_members`: unique `(team_id, user_id)`.
 6. `accounts` (or token ref table): unique primary per owner.
+7. `attendance_events`: unique idempotency tuple (for example `(assignment_id, source_event_id)`).
+8. `offense_rules`: unique `(policy_id, trigger_type, threshold_count)`.
 
 ## 7.2 Indexes
 1. `orders (tenant_id, status, date)`.
@@ -243,6 +326,9 @@ flowchart LR
 5. `assignments (workforce_id, shift_id, role_id, status)`.
 6. `verification_jobs (subject_id, type, status, created_at)`.
 7. `invoices (business_id, vendor_id, status, due_date)`.
+8. `attendance_events (assignment_id, event_time, event_type)`.
+9. `offense_events (staff_id, occurred_at, offense_type, status)`.
+10. `invoice_line_items (invoice_id, line_type, created_at)`.
 
 ## 8) Data type normalization
 1. Monetary: `Float -> DECIMAL(12,2)` (or integer cents).
@@ -271,11 +357,13 @@ flowchart TD
   - run RBAC in shadow mode"]
   P2 --> P3["Phase 3: Scheduling normalization
   - remove order JSON workflow fields
-  - add order_schedule_rules and shift_managers"]
+  - add order_schedule_rules and shift_managers
+  - add attendance and offense base tables"]
   P3 --> P4["Phase 4: Command rollout
   - command writes on hardened schema
   - emit domain events + idempotency
-  - enforce RBAC for command routes"]
+  - enforce RBAC for command routes
+  - add finance settlement tables for payment runs and remittance"]
   P4 --> P5["Phase 5: Read migration + cleanup
   - migrate frontend reads as needed
   - enforce RBAC for sensitive reads
@@ -289,6 +377,8 @@ flowchart TD
 4. Core transaction invariants enforced by schema constraints.
 5. Command API contracts mapped to new normalized tables.
 6. RBAC is in shadow mode with decision logs in place (not hard-blocking yet).
+7. Attendance and offense tables are ready for policy-driven command routes.
+8. Finance settlement tables (`invoice_line_items`, `payment_runs`, `payment_allocations`) are available.
 
 ## 12) Full current model relationship map (all models)