Parent: Content Scope Split — Cross-Repository Implementation & Migration Plan · Work packages: Appendix B — Agent Work Packages & Acceptance Tests
<aside> 🛡️
Operational specification, not an executed migration. The commands/modes, ledger and controls described here must be implemented and rehearsed first. Live changes require environment-specific authorization. Preserve existing credentials and permissions; stop on unexplained drift or potential privilege expansion.
</aside>
Follow the parent plan's verified section 6A branch matrix and Appendix B's branching rules. Application implementation starts in the testing stage and progresses testing → staging → pre-live → production, without skipping a stage. SDK/docs remain based on main; their candidate versions and contract hash participate in lower-environment integration tests before production activation.
The exact application lanes are testing → staging → pre-live → main for Users Backend/Gateway/Admin; testing → staging → prelive → main for Platform/Developer Console; and testing-warsh → do-staging → pre-live → do for Content API. These are repository branches, not interchangeable Hydra environment names. The parent matrix links the branch/workflow evidence checked on 9 September 2026. Revalidate the current receiving branch and deployment configuration before every promotion.
| Boundary | Required gate before advancing |
|---|---|
| Feature PR → testing-stage branch | Correct initial base; approved scope contract; passing target-required CI and feature tests; unrelated changes excluded; deployment authorization accounts for automatic deploy-on-merge behavior. Confirm the deployed testing SHA and all affected service targets before claiming testing readiness. |
| Testing → staging | Testing integration and legacy/granular negative tests pass. Migration dry-run and fault-recovery evidence is available for the approved isolated target. Create a promotion branch from current staging, carry only reviewed changes/dependencies, run staging CI, then verify the staging deployment and integrated contract/version set. |
| Staging → pre-live | Staging authorization, quotas, consent, writer coordination and rollback-floor tests pass. Prepare the promotion from the exact pre-live/prelive target, preserve its settings and migration history, and re-run its tests. Verify pre-live deployment, representative migration/resume/reconcile behavior and SDK/docs candidate compatibility. |
| Pre-live → production | Pre-live acceptance and reconciliation are signed off; all production prerequisites and migration numbers are reconciled. Prepare target-based production PRs to main or Content API do. Obtain approval for merge-triggered deployment, retain compatible readers before writers, and perform only the authorized production canary/cutover in C7. |
Every promotion receipt records repository, feature/work-package ID, source and target branches, preceding-stage source SHA, receiving/promoted SHA, contract hash, required CI results, deployment ID and actual running SHA, environment/issuer/database mapping, migration version/checksum, integration evidence, rollback-floor build and approval. Cherry-pick SHAs can differ; retain provenance and re-test the result. Fixes discovered at a later stage must be reflected in earlier feature/integration branches and revalidated as appropriate, not left as unexplained environment drift. Any emergency bypass requires a separately approved exception rather than silently changing this sequence.
Preserve the change, not the entire source branch. Use narrowly scoped promotion branches based on the latest receiving target and traced cherry-picks/backports where appropriate. Do not bulk-merge unrelated testing work into staging/pre-live/production, reset target branches or rewrite already-applied migration files. Each environment receives the appropriate compatible additive migration history. Migration apply operations remain explicitly authorized and are not implied by merging migration code.
Form Handler is retired and excluded, not a pipeline exception. The owner confirmed on 9 September 2026 that it was retired when Developer Console was introduced. There is no Form Handler feature branch, PR, isolated deployment, main merge, new environment lane or release gate in this plan. Do not reactivate it or interpret retained repository/workflow files as current operational use. Existing clients originally issued through it still require migration coverage according to their current rights and lifecycle. Starter/template follow-through uses its existing main-based release process as specified in section 6A.
Do not assume four Git branches mean four independent Hydra or Platform databases. Record the actual issuer and data-store identities. If testing/staging/pre-live share a store, use isolated approved test clients and a ledger keyed to that real target; do not run the same migration four times as if these were separate populations. No lower-environment rehearsal may point at production merely because an environment alias is missing. Stop the affected operation until the mapping is established.
SDK/docs PRs target main, but source merge, package publication, public documentation status and server activation are separate milestones. Use candidate packages/pinned contracts for earlier stages; retain backward-compatible defaults or explicit granular opt-in until compatible servers are ready. Publish the stable compatible SDKs before delivering new granular-only credentials. Label unreleased/pre-live documentation accurately and avoid letting automatic documentation generation overwrite the reviewed scope contract.
New developer provisioning follows Developer Console → Platform API. Relevant current Admin Dashboard operations follow the same approved grant policy. These entry points authenticate the developer/operator and resolve the app, environment, client type, lifecycle state and policy version; the retired Form Handler is not an entry point. All active writers must resolve the same approved v1 policy; a fallback path must not quietly use old defaults. Validate requested permissions server-side against the approved environment/client-type catalog and approval records.
For a genuinely new OAuth identity, compute the D5 baseline with granular content permissions and no legacy content/content.read; preserve independent baseline rights. Optional subset selection must follow the approved product policy. A new confidential client can receive a secret; a public browser client keeps its existing public/PKCE model and must not gain a secret or client-credentials grant merely through this change.
Persist the creation intent with its idempotency key, policy version and desired grants; create the Hydra client through the existing safe provisioning path. Verify the actual client ID, allowed scopes, auth method and protected metadata. Reconcile managed grant state before reporting a successful effective grant. Deliver credentials using the existing secure one-time mechanism, together with the granted scope list, scope policy version and compatible SDK/onboarding instructions. Never log the secret, and never create a duplicate client to recover an ambiguous timeout.
At runtime the confidential application requests the minimal explicit scope set required by the operation. Hydra's client-allowed set constrains the token's granted set. The gateway validates the actual token and route's explicit alternatives, applies stable quotas and forwards through the existing trusted origin channel. Client allowed scopes, token scopes and route requirements are distinct; a successful grant-state migration does not rewrite every old token.
Acceptance: credentials created through Developer Console/Platform and current Admin paths behave consistently; unapproved scope requests fail; token issuance is verified using approved test identities before broad customer cutover. Existing credentials originally issued by Form Handler remain covered by backward-compatibility tests without running that retired service. Scope defaults when the token request omits scope must be measured on the deployed Hydra configuration and documented; do not rely on an assumed server default.