Harden Workday DA setup lifecycle, resume, and readiness

[Surendra Goutham (is-goutham)]

Description

Hardens the Workday Declarative Agent setup lifecycle for reliable first-run, resume, connection setup, user-context wiring, connection sharing, and readiness behavior.

• Consolidates Workday DA state under .local/connect/workday-da/ with backward-compatible migration.
• Adds a versioned, schema-validated Workday setup definition and deterministic state engine.
• Adds atomic persistence, concurrency locking, prerequisite enforcement, dependent-row regression, and live resume revalidation.
• Detects agent, tenant, application, endpoint, and environment drift and invalidates stale evidence.
• Enforces the V1 Microsoft Entra ID Integrated and ESS DA HR boundaries.
• Detects Power Platform environments without a Dataverse database, gives direct provisioning/admin guidance, and refuses package installation until a Dataverse organization URL is verified.
• Reduces first-run authentication prompts by keeping the DA package check Dataverse-only and requesting a Power Automate Flow token only for checks that actually use Flow APIs.
• Pins every Workday Entra FlightCheck to the Azure CLI-verified administrator account so the shared Graph cache is reused instead of reopening account selection in multi-account workspaces.
• Adds deterministic preview/apply/post-verification for managed Workday and Dataverse connection-reference binding.
• Adds deterministic preview/apply/readback for [Admin] - User Context - Setup to redirect to Workday [System] - 1: Set User Context V2, while refusing ambiguous or customized topics and preserving an exact manual fallback.
• Adds DA-specific FlightCheck gates that verify Workday connection parameters are shared on the selected agent and verify the Workday V2 user-context redirect is enabled.
• Adds deterministic preview/apply/post-verification for the reviewed Workday runtime cloud flows.
• Selects PAC profiles by cloud, environment, and maker account.
• Clarifies that agent parameter sharing occurs before the authorization script's -WhatIf and apply runs.
• Guides the maker to publish and share the agent with a non-maker employee, start a fresh conversation, run a read-only Workday query, and confirm that no Connect, consent, or extra sign-in prompt appears.
• Requires structured, privacy-safe non-maker validation evidence before marking Workday ready.
• Makes the Workday administration boundary explicit: the skill never signs in to the Workday admin interface or changes tenant security, and delegates those steps to an authorized Workday administrator without collecting admin credentials.
• Replaces the permanent SAML-mismatch halt with a controlled customer choice: preserve the current federation or continue only after explicit Workday/identity-admin approval and rollback capture.
• Simplifies the Workday SAML safety pre-check to three provider states and requests only the Service Provider ID when confirming the intended Entra federation; certificate details are deferred to certificate validation.
• Streamlines customer follow-ups into seven resumable milestones, consolidates Workday administrator actions into one handoff, uses one scoped approval per Entra/runtime phase, and makes network review conditional without weakening internal verification.
• Improves manual FlightCheck formatting, row-specific acknowledgements, and copyable device-code instructions.
• Adds the reviewed runtime system-topic catalog and package-managed topic protection guidance.
• Enforces the same lifecycle and completion gates across Development, Sandbox, and Production.
• Recognizes completed DA Workday state in the top-level /connect summary.

Product-owned package version ranges, automatic topic activation, and machine-observed semantic validation of the final Workday response remain explicit follow-ups because the required product/platform contracts are not currently available.

Related issue

Refs #290

Type of change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update
• Refactor / cleanup

Testing

• 117 passed in the finalized UserContext helper, DA FlightCheck, registry, state, and orchestration suites.
• Expanded DA/registry selection: 174 passed before the final active-agent precedence refinement; the finalized targeted suite covering that refinement passed.
• Broader Workday regression selection: 527 passed, 2 skipped, with one unchanged CEA routing fixture mismatch that is also present on the remote branch baseline and outside this diff.
• Ruff passed for all changed Python implementation and test files.
• Changed Python helpers compile successfully.
• git diff --check passed.
• Sensitive-value scan of the diff passed.

Checklist

• My code follows the existing style
• I have added/updated tests where applicable
• I have updated documentation as needed

Static validation (samples/ only)

No files under samples/ were changed.

Validation
- YAML parse: N-A
- AdaptiveDialog kind: N-A
- XML parse: N-A
- Filename convention (new): N-A
- Folder convention (new, incl. README.md): N-A
- Diff scope (samples/ only): N-A
- Secrets / internal URLs: N-A

[nkemms]

Local review findings

I found eight issues in the Workday DA lifecycle changes:

1. High — persisted state can falsely claim ready. scripts/workday_da_state.py validates the stored shape but does not rederive and compare status with setupStatus, revalidation state, and DA5.1 scenario evidence. A state file with pending rows and status: "ready" passes validate(), allowing unsupported readiness to reach the orchestrator.

2. High — documented manual fallbacks cannot complete programmatic rows. The definition declares fallbackGate: "manual" for steps including DA2.5 and DA4.4, but the state engine only consumes the static gate. A successfully acknowledged manual fallback remains in-progress; recording it as passed instead misattributes it as programmatic evidence.

3. High — the completion contract can silently omit a setup step. Definition validation checks for unknown IDs and inclusion of the final step, but does not require completion.requiredStepIds to cover every defined blocking step. Removing a non-final requirement such as DA4.8 still yields a valid definition and permits false readiness.

4. Medium — flow activation is not scoped to the installed package. scripts/activate_workday_da_flows.py resolves workflows globally by display name. If a package flow is absent but an unrelated flow has the same name, the helper can activate and verify the unrelated record. Resolve through the selected solution/component inventory or immutable IDs.

5. Medium — the canonical maker identity is not enforced for Dataverse writes. PAC verifies the preferred account, but scripts/auth.py uses preferred_username only for cached-account selection or as an interactive login hint. Interactive sign-in can return another account, allowing PAC discovery and Dataverse mutations to run under different identities.

6. Medium — binding approval output exposes IDs instead of the promised safe names. scripts/bind_workday_da_connections.py emits raw connection IDs in candidate errors and its preview, while the playbook requires a display-name-oriented confirmation. The plan should include the selected target display names and keep raw identifiers out of session-facing output.

7. Low — a PAC timeout bypasses the structured failure contract. The binding runner lets subprocess.TimeoutExpired escape, while main() does not catch that exception. A timeout produces a traceback instead of WORKDAY_DA_BINDING_FAILED_JSON.

8. Low — the incomplete-readiness branch has no required user-facing copy. verify-connection.md says to tell the user which step remains but provides no Message block, despite requiring all user-visible text to come from exact message blocks.

The targeted suite produced 119 passes and 3 failures. All three failures reproduce on the current main target and are not introduced by this PR. The PR head is fresh against its target and the current-target merge is clean.