> ## Documentation Index
> Fetch the complete documentation index at: https://specs.flux.employinc.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 2026 04 17 paychex pilot release design

# Paychex Pilot Release — Roadmap Synthesis Design

**Status**: Approved in brainstorming (2026-04-17)
**Author**: Patrick Jean (CTO) with Claude Code synthesis
**Created**: 2026-04-17
**Target Milestone**: M1 — Paychex Pilot Launch (2026-04-30)
**Supersedes**: `docs/roadmap/paychex-go-live-dod.md` (PR #307 open) — content absorbed into Cycle 364 and this spec.

***

## Purpose

Flux has \~30 in-flight plans across multiple waves, themes, and PRs. The Paychex partnership has a hard launch target of 2026-04-30. This spec does three things:

1. Defines the pilot steel thread — what the first Paychex customer can actually do end-to-end on April 30.
2. Restructures the roadmap so **waves = functional domains** and **milestones = dated releases**. Removes "launch" concepts from waves.
3. Identifies the Floor / Stretch / Out scope for the April 30 pilot with pre-declared cut-lines and fallbacks, so we do not negotiate scope under pressure in the final week.

The brainstorming approach (Approach A — "Target with Cut-Lines") keeps the aspirational scope (including real `PaychexApiGateway`, real calendar-driven interview workflow, multi-channel job distribution) in the plan while guaranteeing a credible pilot ships even if any single deep-integration piece slips.

***

## Steel Thread — the 6 Steps

The pilot is one Paychex customer completing this flow end-to-end. Steel thread = guaranteed floor. Stretch items are aspirational targets governed by cut-lines (§4).

| # | Step                                 | Floor (guaranteed)                                                                                                                                                              | Stretch (cuttable)                                                                         |
| - | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| 1 | Employer signs up (Paychex customer) | Clerk signup + Paychex-branded login                                                                                                                                            | Paychex SSO (HC-10) — out                                                                  |
| 2 | Create job conversationally          | AI intake → JD generated + approved → persisted                                                                                                                                 | —                                                                                          |
| 3 | Post to job boards                   | Cycle 208 Phase 1: 3-tier architecture + 8 adapters scaffolded + Indeed live + AI tier-selection over live channels                                                             | LinkedIn + ZipRecruiter live; Phase 2 optimization loop                                    |
| 4 | Candidates apply + get updates       | Portal (Cycle 323.5) + magic-link auth + real notification gateway (Resend email) + transactional SMS via Bird toll-free (new Cycle 323.7, lean gateway in notification domain) | Full Candidate Agent across SMS/WhatsApp/iMessage (Cycle 323.1–323.4); two-way SMS replies |
| 5 | Schedule interviews                  | Chat-driven scheduling via Resend email + .ics attachment + SMS confirmation                                                                                                    | `InterviewSchedulingWorkflow` + Google Calendar gateway (full Temporal orchestration)      |
| 6 | Select + hand off to Paychex         | Cycle 363 `HirePackage` export — printable sheet + JSON download for manual Paychex entry                                                                                       | Real `PaychexApiGateway` (PR #307 DoD §1 scope)                                            |

**What is explicitly out of pilot** (listed so the floor is unambiguous):

* Candidate Match Agent (Wave 4 — Cycle 218 + 10 sub-cycles)
* Campaign Domain + Candidate Agent persona (Wave 3 — Cycle 323, 323.1)
* Full multi-channel engagement via campaign domain (Wave 3 — Cycles 323.2 SMS agent, 323.3 WhatsApp/email agent, 323.4 iMessage)
* Canonical Schema Platform Part 2 projections (Wave 2 extension)
* Autonomous incident response + progressive delivery (Wave 6 — Cycles 301.4, 301.5)
* SOC2 Type I attestation
* EU AI Act formal conformity assessment (Cycle 221 formal scope; transparency + oversight primitives ship because 218 embeds them)
* A2P 10DLC SMS (toll-free ships in pilot; A2P is post-pilot milestone M2)

***

## Wave Structure — Domain-Organized

Waves describe functional capability bundles. They are not time-ordered release trains.

| Wave       | Title                   | Domain                                                                                                                                                                           |
| ---------- | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Wave 0** | AI Blueprint Foundation | sage-blueprint: ReAct agent, SSE chat, skill system, Temporal patterns, frontend scaffolding, CI/CD, k3d — **complete**                                                          |
| **Wave 1** | Employer Domain         | Employer signup, auth, chat/agent, dashboard, conversation history, contextual sidebar, generative UI                                                                            |
| **Wave 2** | Job Posting             | Job creation conversationally, JD generation, screening questionnaire, multi-channel distribution, agentic tier selection + budget optimization                                  |
| **Wave 3** | Candidate               | Candidate identity, magic-link portal, agent-native chat, campaign domain, multi-channel engagement, notification backbone integration                                           |
| **Wave 4** | Candidate Selection     | Screening + ranking, persistent Match Agent, Intelligence UI, Fairness Engine, EU AI Act compliance, Select for Hire, canonical payroll projection, Paychex Flex API integration |
| **Wave 5** | Platform & Trust        | Pricing/billing, feature flags, evals, observability stack, security audit, SOC2 prep, deploy hardening, staging, production infra                                               |
| **Wave 6** | Dark Factory SDLC       | Spec-driven dev (Mintlify + PRDs + RFCs), Chief Engineer review system, autonomous incident response, progressive delivery, AI debt tools, skill-driven automation               |

### Cycle → wave mapping

**Wave 0 (complete)**: 133.1, 202, 203, 204, 204.1, 205, 205.1, 209, 211, 212

**Wave 1 (Employer Domain)**: 205.2, 215, 216, 216.1, 216.2, 216.3, 216.4

**Wave 2 (Job Posting)**: 208 (all phases)

**Wave 3 (Candidate)**: 217 (identity — merged), 217.5 (autonomous agent architecture, shared with Wave 4), 323, 323.1, 323.2, 323.3, 323.4, 323.5, 323.6, **323.7** (new — pilot SMS gateway)

**Wave 4 (Candidate Selection)**: 218 (candidate match agent) + 218.1–218.10, 219, 220, 221 (formal EU AI Act conformity — see flag), 222 (workflow outbox), 363 (Select for Hire), Real `PaychexApiGateway`

**Wave 5 (Platform & Trust)**: 207, 209.1, 211.1, 213 (deploy hardening), 213 (feature flags), 301.1, 301.2, 301.3, 382, 382.1, 382.2, 218 (AI response feedback PR #300), **364** (new — Paychex Pilot Finishing), **365** (new — Pilot Evals Harness)

**Wave 6 (Dark Factory SDLC)**: 214 (spec-driven dev), 221 (Chief Engineer review system — operating), 301.4, 301.5, 380, 381, 400, 401, AI debt cycles, 209.2 (preview envs), 209.5 (worktree envs)

### Numbering collisions to resolve (follow-up)

* **Two Cycle 221s**: CE Review System (Wave 6, operating) and EU AI Act Formal Compliance (Wave 4, match agent). Same cycle doc path would collide. Recommend renumbering the Match Agent compliance cycle. Flagged in Wave 4 wave doc.
* **Two Cycle 217s**: Candidate Identity (Wave 3, merged) and nginx ingress migration (infra). Recommend aliasing the infra one.
* **Two Cycle 213s**: Deploy Hardening (Wave 5) and Feature Flags (Wave 5). These share the cycle number from legacy drafts. Recommend aliasing or renumbering one.
* **Two Cycle 218s** (multiple): AI Response Feedback (PR #300, Wave 5), Unified SSE Auth (Wave 3 prerequisite), Candidate Match Agent (Wave 4). Same pattern — predates 381 issue-number IDs. Recommend aliasing.
* **Cycle 382 collision**: Production Environment Bootstrap (Wave 5, open PR #420) vs. AI Debt Scan (Wave 6, open PRs #400 #417 #421). Recommend renumbering AI debt cycles before they merge.

These are all addressable as a cleanup follow-up after pilot ships. The roadmap documents flag them explicitly.

***

## Release Milestones

Milestones cherry-pick cycles across waves toward a dated target. Milestones do not own cycles; waves do.

| Milestone                            | Target     | Draws from             | What's delivered                        |
| ------------------------------------ | ---------- | ---------------------- | --------------------------------------- |
| **M1: Paychex Pilot Launch**         | 2026-04-30 | W1, W2, W3, W4, W5, W6 | Steel thread (§2) with cut-lines (§4)   |
| M2: A2P 10DLC SMS Cutover            | post-pilot | W3                     | Transactional SMS toll-free → A2P 10DLC |
| M3: Full Job Distribution            | post-pilot | W2                     | Cycle 208 Phase 2 + 3 complete          |
| M4: Candidate Match Agent GA         | post-pilot | W4                     | 218.x series shipped                    |
| M5: Candidate Agent Multi-Channel GA | post-pilot | W3                     | 323.1 through 323.4 shipped             |
| M6: Dark Factory Autonomous Ops GA   | post-pilot | W6                     | 301.4 + 301.5 shipped                   |
| M7: SOC2 Type I                      | post-pilot | W5                     | Full audit + attestations               |

***

## Cut-Lines and Fallbacks

Each cut-line is a go/no-go checkpoint at a stream milestone. Fallbacks are pre-declared. No re-negotiation mid-flight.

| Cut-line           | Triggering milestone                                                      | Green path                        | Red path (automatic fallback)                                                                        |
| ------------------ | ------------------------------------------------------------------------- | --------------------------------- | ---------------------------------------------------------------------------------------------------- |
| **CL-1**           | S3: `PaychexApiGateway` sandbox E2E round-trip (create → verify → delete) | Real Paychex API in pilot         | Cut `PaychexApiGateway`; ship Cycle 363 `HirePackage` export for manual Paychex entry                |
| **CL-2** (stretch) | S2: LinkedIn sandbox approved AND adapter green                           | LinkedIn live alongside Indeed    | LinkedIn stays stub; AI picks from live channels only                                                |
| **CL-3**           | S1: `InterviewSchedulingWorkflow` + Calendar gateway E2E green            | Temporal-orchestrated interviews  | Chat-driven scheduling via Resend + .ics attachment + SMS confirmation                               |
| **CL-4**           | S6: 10-concurrent-session load test passes                                | Pilot serves concurrent employers | Pin pilot to ≤3 concurrent employer sessions; document cap in runbook; size up post-pilot            |
| **CL-5**           | S6: Security audit CRITICAL/HIGH findings = 0                             | Launch proceeds                   | Remediate findings; non-critical features may defer; launch does not proceed with CRITICAL/HIGH open |

***

## Execution Phases

### Phase 1 — Kickoff

Submit all long-lead external items immediately:

* Paychex sandbox + prod OAuth credentials (fallback: auto-triggers CL-1 if not received)
* Indeed Sponsored Jobs API sandbox (fallback: Indeed XML feed)
* A2P 10DLC SMS registration (fallback: Bird toll-free ships in pilot; A2P is M2)
* LinkedIn Jobs API (stretch only)
* Resend domain authentication SPF/DKIM/DMARC (fallback: shared Flux domain)

### Phase 2 — Parallel build

Six streams, one owner each. No cross-stream blocks.

| Stream                                    | Cycles                                               | Exit milestone                                                                                             |
| ----------------------------------------- | ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| **S1. Hiring agent + JD + portal + SMS**  | 323.5, 323.7, 323.6 email subset, 205.2 finish       | Candidate applies via portal, receives email + SMS confirmations                                           |
| **S2. Job distribution**                  | 208 Phase 1                                          | Indeed live; 3-tier architecture + 8 adapters scaffolded; AI tier-selection operational                    |
| **S3. Select for Hire + Paychex API**     | 363 implementation, `PaychexApiGateway` (PR #307 §1) | Employer hires → real Paychex employee (stretch) OR `HirePackage` export ready (floor)                     |
| **S4. Prod bootstrap + deploy hardening** | 382.1, 382.2, 209.1, 213                             | GKE prod cluster live, release-branch gating, rollback tested                                              |
| **S5. Observability + alerts**            | 301.1, 301.2, 301.3                                  | Dashboards green in staging; alerts routed to on-call                                                      |
| **S6. Evals + Paychex pilot finishing**   | 365, 364                                             | Eval harness gating CI; security audit clean; employee data UI shipped; runbooks written; Go/No-Go at 100% |

### Phase 3 — Cut-line gates

CL-1 through CL-5 evaluated in order as stream milestones land. Fallback actions taken automatically.

### Phase 4 — Integration burn

* All Floor streams merged to `release/paychex-pilot` branch
* 72-hour burn-in against GKE staging with synthetic traffic (10 concurrent sessions)
* Paychex partner dry-run against sandbox end-to-end
* All cut-lines verified (green or fallback active)

### Phase 5 — Go-live gate

* Run Cycle 364 Go/No-Go checklist (absorbs + refines PR #307 §10)
* CTO + Paychex stakeholder sign-off
* `promote-to-prod.yml` executes
* First real Paychex tenant onboarded; observability on-call active

***

## New Cycles Created with This Spec

Three cycles were identified as unclaimed work. Each gets a full cycle doc rather than being tacked on outside the spec-driven process.

* **Cycle 323.7** — Pilot Transactional SMS Gateway (`docs/roadmap/cycles/cycle323.7-pilot-transactional-sms.md`)
* **Cycle 364** — Paychex Pilot Finishing (`docs/roadmap/cycles/cycle364-paychex-pilot-finishing.md`)
* **Cycle 365** — Pilot Evals Harness (`docs/roadmap/cycles/cycle365-pilot-evals-harness.md`)

***

## Documents Produced by This Spec

1. This design spec.
2. Milestone doc: `docs/roadmap/milestones/paychex-pilot-launch.md`.
3. Updated `docs/roadmap/roadmap-overview.md` with the Wave × Milestone model.
4. Seven wave docs rewritten / renamed / created:
   * `waves/wave-0-ai-blueprint-foundation.md` (renamed from wave-0-bootstrap.md)
   * `waves/wave-1-employer-domain.md` (rewritten from wave-1-mvp-foundation.md)
   * `waves/wave-2-job-posting.md` (rewritten from wave-2-revenue-platform.md)
   * `waves/wave-3-candidate.md` (rewritten from wave-4-candidate-agent-platform.md)
   * `waves/wave-4-candidate-selection.md` (rewritten from wave-5-candidate-match-intelligence.md)
   * `waves/wave-5-platform-and-trust.md` (rewritten from wave-3-production-hardening.md)
   * `waves/wave-6-dark-factory-sdlc.md` (new)
5. Three new cycle docs: 323.7, 364, 365.
6. PR #307 `paychex-go-live-dod.md` content absorbed into Cycle 364 and milestone doc. The loose file is superseded and should not merge.

***

## Decisions Made During Brainstorming

1. **Paychex API in scope for now, cuttable via CL-1**. User confirmed: "if we must cut something then this would be OK to cut; but include in scope for now." Approach A.
2. **Interview scheduling via Temporal is stretch, not floor**. Fallback is email + .ics + SMS.
3. **SMS transactional is floor**; full agent SMS is stretch (Wave 3 post-pilot).
4. **SMS uses toll-free for pilot**; A2P 10DLC registered in parallel for M2 cutover.
5. **Job distribution ships the 3-tier architecture in pilot** (per Cycle 208 Phase 1 scope), with Indeed live and others scaffolded as stubs. AI tier-selection reasons only over live channels.
6. **Candidate Match Agent is out of pilot** (Wave 4 / Milestone M4). Pilot uses existing Cycle 203 `screen_resume` + `rank_candidates` tools.
7. **Candidate Agent multi-channel is out of pilot** (Wave 3 / Milestone M5). Pilot uses the agent-native Portal (323.5) plus transactional SMS (323.7) only.
8. **Waves are domain-organized**, not release-organized. "Launch" concepts live in milestones, not waves.
9. **Target date stays 2026-04-30**. 13 calendar days from brainstorming.
10. **Numbering collisions flagged but not resolved in this spec** — addressed as a post-pilot cleanup pass.

***

## Post-Spec Tasks (for the implementing Claude Code session)

After this spec lands and the user approves it:

1. Create GitHub issues for Cycles 323.7, 364, 365 so they take on issue-number IDs per Cycle 381.
2. Open plan PR for this work with roadmap-overview, wave docs, and milestone doc.
3. Address numbering collisions (218, 221, 217, 213, 382) as a cleanup pass after pilot ships.
4. Coordinate kickoff of Phase 1 long-lead items (credentials, A2P, Indeed, LinkedIn, Resend) as parallel unblocking work — these do not wait on spec approval.