Foundation delivery and rollout

Inputs and scope

This plan covers WorkOS authentication and the two tools, hello_read and hello_write, within the Product scope. Draft Platform PR #1129 already implements the foundation and contains ADR-024's adoption candidate. Its setup guide records implementation approval, but mainline ADR adoption and implementation merge are not established. Review the implementation against this reconciled specification; do not repeat the original investigation as if no implementation existed. See implementation evidence for the inspected commit and evidence limits.

Delivery sequence

1. Review the specification, ADR and existing implementation

Review PR #1129 at the inspected head against Product's scope and AC-1 through AC-6. Chimp 0.6.0, JSON Streamable HTTP and revisions 2025-06-18 / 2025-11-25 are selected. Every protected request resolves fresh WorkOS authority; its deadline is external-token expiry or eight seconds from first lookup. The complete buffered reply is withheld if that deadline expires. Initial size, rate, concurrency and provider limits are recorded in Program design.

Hosted tests support the code claims. The author reports successful Codex CLI 0.163.0 browser OAuth and desktop calls to both probes after the HTTPS CIMD fix. This is partial development compatibility evidence, not proof of all renewal, withdrawal or tenant-isolation behavior. Record the exact desktop version, active protocol mode and negotiated revision for the release under evaluation.

Specification approved as Ready: the scope and approach are approved. The implementation PR determines the final design; update the specification later if needed. ADR adoption and implementation review remain in Platform's PR process. Specification readiness does not establish merge, deployment, activation or release acceptance.

2. Complete implementation review and prepare activation

Review the complete foundation already in PR #1129, including permission definitions, internal credential separation, provider lookups, deadline enforcement, privacy filters and local routing. Resolve blocking implementation findings and rerun affected tests on the candidate release. Implementation review findings belong to that PR's review process; they do not reopen this specification's approval.

Before making MCP available: pass the server and provider tests for AC-1 through AC-6, including authentication and tenant regressions. Configure the target environment and ingress protection, provision definitions and approved grants, and name the operational owner. The release must remain safe with MCP off for every tenant. The author's enabled development organization is a deliberate local exception, not approval for another environment.

3. Verify the deployed release

With deployment and activation approved, run the manual test plan and operational checks against the chosen release. Check setup, permissions, renewal, recovery and switching MCP off and on. Inspect logs and Sentry while testing.

Before acceptance: resolve blocking findings and record the release, environment, client/version, results and the acceptance decision. Record any remaining work before wider use. Passing automated tests or merging the code does not establish acceptance or availability.

Planned PR set

The logical split remains specification/ADR, implementation, and operation/results. PR #1129 combines the ADR adoption candidate with implementation; Planning content remains a separate review. Do not create duplicate work merely to restore the original proposed PR split:

1. Specification and ADR: the specification scope and approach are approved as Ready. Complete ADR adoption through the implementation PR.
2. Implementation: deliver the complete foundation from step 2, with tests and setup guidance. One PR can cover both tools; individual stories do not need separate PRs. Merging it does not deploy or accept the feature.
3. Operation and results: add verified operating instructions and the results from step 3, including the acceptance decision. Review any code fixes separately and rerun affected checks before resuming activation.

Start each PR from current main with its prerequisites merged. If approved work needs to start on an unmerged dependency, coordinate the branches and rerun checks after rebasing. Explain any change to this proposed split.

If the compatibility check needs a test harness, keep it separate from production routes and business data. Keep useful results and agree what happens to the harness afterward; it must not become a production authentication bypass. Split out a prerequisite refactor only when shared-code risk justifies a separate review.

Dependencies and safe intermediate states

Prepare the environment

Keep MCP off for every tenant after deployment. Configure the MCP address, issuer and organization, both permission definitions, approved user grants and the WorkOS flag entitlement-remote-mcp-org. Use the selected finite operating limits and verify they suit the target environment. This delivery does not cache access between requests. Measure provider propagation separately from the eight-second authority deadline and record the accepted total withdrawal exposure. Missing required configuration must deny access. Permission setup checks must not grant access or delete unrelated definitions.

Verify the selected buffered-response expiry guard in the candidate release. Its hosted controlled-clock test passes; the environment check remains a gate. Verify the documented trusted-client-address ingress controls. A WorkOS propagation delay must not allow an admitted request to outlive its authorization.

Enable a controlled test

An authorized operator enables the flag only for the chosen tenant and environment. The flag alone grants no user permissions. Record the MCP address, operational owner and maximum delay before changed access takes effect alongside the release details. Immediately check allowed and denied requests, plus existing browser authentication.

Stop access or roll back

Turn off the organization's WorkOS flag and check that protected requests stop within the agreed time limit. An unavailable WorkOS lookup must not extend expired access. OAuth metadata, bearer authentication and browser access remain usable.

For an emergency, withdraw the MCP route or roll back the release. Account separately for tokens already issued and requests already running; switching off the flag does not revoke tokens immediately. The two tools change no business data, so there is no business-data rollback.

Expand availability

Define who should receive access and verify the intended release before expanding use. Internal availability and final acceptance remain separate decisions. No fixed observation period is required; add one only for a stated reason, with a workload, duration, measurable criteria and a decision owner.