​

Stage 2 Certification

​

Purpose

​

When to run this

• At Stage 2 seal decision
• After Stage 2 hotfixes touching onboarding/policy/PEPM paths

​

Prerequisites

• Stage 1 gate remains green
• Access to Stage 2 test suites and certification tag history

​

Inputs

• Candidate commit SHA/tag
• Stage 2 test outputs
• Stage 1 regression gate outputs

​

Procedure

​

1) Scope statement

• Business onboarding readiness: Discovery, classification, and preflight validation
• Policy + RBAC enforcement: Platform-scope vs org-scope policy management, super-admin enforcement
• PEPM assignment writes: Idempotent SCD2 writes with safe-group handling
• Wizard continuation readiness: Preflight → discovery → mapping → processing flow readiness

​

2) Explicit exclusions

• Commission math / calculation logic
• Allocation / reconciliation logic
• Stage 3 snapshot generation
• Rollups / aggregation / totals
• Dashboard / analytics endpoints
• AI decision-making in business logic

​

3) Evidence

​

Stage 2 Test Results

python -m pytest api/tests/test_business_agent_pepm_assignments.py -q

python -m pytest api/tests/test_business_onboarding_policy_rbac.py -q

​

Stage 1 Gate Verification

pytest api/tests/test_stage1_bridge.py api/tests/test_intake_processor.py api/tests/test_storage_presigned_url.py -q

​

4) Notable fixes included in Stage 2 closure

​

Production Bugfix

• assignment_ids → pepm_assignment_ids in api/bigquery/business_onboarding_queries.py:1612
  • Prevents NameError in non-idempotent PEPM write path
  • Regression test added in test_pepm_write_non_idempotent_when_active_set_differs

​

Test Stabilization

• Function-boundary patching for find_business_ids_in_safe_group in idempotent test
  • Avoids brittle SQL string matching
  • Patches at api.bigquery.business_onboarding_queries.find_business_ids_in_safe_group
• Correct patch targets for preflight discovered businesses
  • Changed from api.bigquery.discovery_queries.get_discovered_businesses to api.routes.intake_preflight.get_discovered_businesses
  • Matches actual import: from api.bigquery.discovery_queries import get_discovered_businesses
• Removed brittle call_count assertions
  • Replaced with script_called flag guard for idempotent case
  • Focuses on contract checks (idempotent result structure) rather than exact query counts
• Idempotency normalization fix
  • Updated idempotency_rows to use non-normalized pepm_rate values ("2.50", "1.00") to match production’s str(Decimal(...)) behavior
  • Ensures idempotency check matches correctly and script is NOT executed for idempotent cases
• Import safety for optional dependencies
  • Made api/routes/ai_query.py import-safe by wrapping vertexai imports in try/except ImportError
  • Prevents pytest crashes when optional AI dependencies are not installed

​

5) Known non-blocking warnings

• PydanticDeprecatedSince20 warnings about Field(..., example=...) usage
  • Not test failures
  • Deferred to future Pydantic migration work
  • Does not affect functionality

​

Verification

1. Explicit hotfix justification
2. Re-run of Stage 2 test suite
3. Re-run of Stage 1 gate (must remain green)
4. Updated certification if scope changes

​

Failure modes & fixes

1. Stage 2 suite failures
   • Fix failing onboarding/policy/PEPM code paths and rerun targeted tests.
2. Stage 1 gate regression
   • Block seal; restore Stage 1 green before proceeding.
3. Optional dependency import crashes in tests
   • Keep optional integrations import-safe using guarded imports.
4. Idempotency path mismatch
   • Validate PEPM idempotency normalization assumptions and test fixtures.

​

Artifacts produced

• Certification metadata (date/commit/tag)
• Stage 2 and Stage 1 test results
• Notable fix list captured in certification evidence
• Seal decision and re-certification criteria

​

Related docs

• docs/runbooks/STAGE1_CERTIFICATION.md
• docs/runbooks/STAGE3_KICKOFF.md
• docs/reference/RBAC_AUDIT_SUMMARY.md