Phase 4: verify and roll out

This phase turns technical checks into evidence that product and engineering can review before employer access changes in production.

Outcome

TL;DR

Approve the intended changes before writing, prove repeat safety after writing, then schedule the same job daily.

Production scheduling is the final step, not the first test. The rollout proceeds through:

1. automated journey tests;
2. a complete sanitized-data dry run;
3. QA dry run and manual apply;
4. an immediate second QA run;
5. production dry-run review;
6. controlled production apply;
7. named employer login and authorization checks; and
8. daily scheduling after company and outlet synchronization.

Automated journey matrix

Business journey	Required proof
Active HQ employer	Migrates, logs in and reaches an endpoint for the correct company
Active outlet manager	Receives one correct outlet and cannot use another
Active area manager	Receives all and only the intended outlets
External super-HQ	Receives every valid company membership and can switch among them
Internal super-HQ	Receives no customer membership
Existing JodApp identity	Links safely without creating a duplicate
Identity conflict	Writes nothing and appears in review report
New disabled employer	Is skipped and receives no identity
Previously migrated employer becomes disabled	JodGig memberships are revoked and employer access stops
Company or external grant removed	Corresponding legacy membership is revoked
Outlet removed from an area	Corresponding assignment disappears
Native JodApp membership	Survives every JodGig reconciliation unchanged
Legacy-password employer	Logs in once, upgrades to BCrypt and stays upgraded after reconciliation
Later source email or BCrypt password change	Propagates one way to JodApp
Identical second run	Produces no material changes

These tests call the public planner and writer. Private mapping-method tests may supplement them but cannot replace them.

Review the dry-run report

TL;DR

Counts find large mistakes; named examples find incorrect reasoning hidden inside plausible counts.

Review both:

• aggregate counts for each decision and access shape; and
• a small named set of non-production or authorized QA examples representing every journey above.

The report must reconcile:

Question	Evidence
How many source users were examined?	Count equals the complete employer-type population for that snapshot
Why was each person included or excluded?	One decision and reason code per source ID
Which identities will be linked?	Remote-ID matches, approved email links and conflicts shown separately
Which company access will exist?	Exact desired membership company IDs and roles
What will be removed?	Separate revoke lists for memberships and assignments
What needs human action?	Missing prerequisites and identity conflicts listed explicitly

No personal fields or password material belong in the report.

Sanitized-data gate

Check	Pass condition
Complete planner run	Every employer-type source row receives one decision
Super-HQ counts	All valid pivots produce memberships; invalid and disabled company links do not
Missing prerequisites	Every missing company or outlet is visible
Duplicate and orphan handling	No crash and no duplicate destination access
Repeat planning	Same snapshot produces the same plan

The local sanitized database describes data shape, not current production totals. Re-run the same non-PII audit queries against production immediately before rollout.

QA gate

Step	Required result
Run company and outlet syncs	Employer prerequisites exist
Run employer dry run	Product and engineering approve decisions and counts
Run employer apply manually	No unexplained failures
Exercise named logins and endpoints	Correct company and outlet authorization
Disable or alter controlled source examples	Next plan shows the intended revocation or update
Run employer apply again	Expected changes occur
Run immediately a third time	No material changes

Include at least one identity with both a JodGig-provisioned membership and a native JodApp membership.

Production preflight

TL;DR

Freeze the implementation, not JodGig. Read the current source, review the exact plan, and ensure the job can be disabled quickly.

Before the first production write:

• deploy application-readiness changes;
• confirm every employer endpoint enforces active membership;
• ensure the old employer writer and any employer JIT path are disabled;
• run company and outlet syncs;
• run the production dry report;
• resolve or explicitly defer every needs_review case;
• record the expected decision and change counts;
• confirm database backup and operational rollback procedures; and
• identify who may start, stop and inspect the reconciliation.

Do not log or export password hashes as part of backup or review material.

Controlled production apply

Step	Observation
Start the same job in manual write mode	Exactly one writer obtains the run lock
Watch progress and failure counts	One bad person does not stop later people
Compare final counts with approved plan	Differences are explained before declaring success
Test named employer accounts	Login, selected company, switching and outlet scope work
Test a revoked example	Employer endpoint rejects it
Run the planner again	No unexpected remaining changes

If the result is unsafe:

1. disable further employer writes;
2. keep the run report and affected IDs;
3. restore destination data using the approved database procedure or a targeted corrective plan;
4. fix the planner or writer;
5. repeat dry-run approval before another apply.

Do not attempt to repair production by editing JodGig-owned membership rows manually without recording the source inconsistency; the next full reconciliation will calculate from JodGig again.

Daily operation

TL;DR

Schedule one full reconciliation after the company and outlet jobs. Use the same service for manual exceptions.

Exact clock time is an operations choice. The required order is:

Immediate provisioning is not required. If an employer needs same-day access, operations starts the same full job manually after confirming company and outlet prerequisites.

Alert on:

• job failure;
• a non-zero unexpected-failure count;
• new identity conflicts;
• missing company or outlet prerequisites;
• a large change from recent decision counts; and
• overlapping-run attempts.

Review cases may remain non-zero when they are known and intentionally deferred, but the run must not describe itself as fully clean.

First-week verification

Day	Check
First production run	Named accounts, counts, revocations and second-plan convergence
Each daily run	Failure, review and change counts
After source access changes	Expected membership or outlet removal appears the next day
End of first week	No unexplained repeated updates; no native membership changes

Keep the manual trigger and dry-run mode after scheduling. They are operational tools, not temporary test code.

Retire the old implementation

TL;DR

Only one employer writer may remain after rollout.

After the replacement has completed the production verification period:

• remove the abandoned employer-sync service and unfinished mapper code;
• close or supersede the old implementation issues;
• remove unused employer login-time migration states;
• keep the historical specification as decision history; and
• link operational documentation to this new plan.

Do not change JodGig::Users::SyncService or JodGig::Users::JitMigrationService only to make them share an identity-writing service with the employer reconciliation.

Release approval

Role	Approval question
Product/domain owner	Does every decision match who should have access?
Implementing engineer	Do planner and writer tests cover each specified journey?
Reviewer	Can the report explain every write and revocation?
Operations	Can the job be started, stopped, inspected and rerun safely?

Scheduling is approved only when all four questions have a clear yes.