Parent: Content Scope Split — Cross-Repository Implementation & Migration Plan · Contract: Appendix A — Scope Contract & Endpoint Reconciliation
<aside> 🛠️
All work packages are planned, not executed. File paths below are inspected entry points or explicitly proposed deliverables. Follow the current branch's instructions and tests. Do not create unrelated changes merely to ensure every repository has a PR.
</aside>
Read the parent and every appendix before implementation. Re-read approved D1–D6 decisions at activation gates. Follow section 6A of the parent plan for every feature branch, PR base and promotion. Users Backend, Gateway, Admin Dashboard, Platform API and Developer Console start from testing; Content API starts from testing-warsh. SDK/docs work starts from main. Optional starter/template repositories use their documented main-based release lanes. qf-form-handler is retired and excluded from implementation and release work, per owner confirmation on 9 September 2026; do not create branches, PRs, tests/deployments or pipeline infrastructure for it. Its previously issued clients remain in the current migration inventory.
Application changes must progress through testing → staging → pre-live → production using the exact repository-specific branch names in that matrix. Create the first feature branch from the current remote initial base and target that base in its PR. Create each later promotion branch from the current next-stage target and carry only the previously verified feature changes and required dependencies. Record source-to-promotion commit correspondence; do not bulk-merge unrelated environment-branch changes, force-push, reset branches or skip stages. Preserve ongoing App State work, migration history, client lifecycle and target-specific CI/configuration. A default-branch source citation is evidence, not an instruction to start implementation there; a merged PR is not deployment evidence.
Each work package must produce: changed-file list, contract hash, dependency links, tests actually run with results, skipped checks and why, rollout prerequisites, and rollback floor. Track status as planned / in progress / blocked / ready for review / verified. “Verified” requires evidence on the exact commit, not test claims copied from an older PR. Record blocking questions without guessing answers; continue independent safe tasks.
This planning request does not authorize live Hydra changes, production database migration, release publication, merge/deploy, email campaigns or credential rotation. An implementation agent must obtain the applicable execution authorization separately. No tokens, client secrets, Hydra administration secrets or personal client inventories belong in PRs, Notion, fixtures or logs.
flowchart TD
T00["T00: branch / deployment / writer inventory"] --> T01["T01: contract and golden fixtures"]
T01 --> T02["T02: gateway + quota compatibility"]
T01 --> T03["T03: consent + public reflections"]
T01 --> T04["T04: origin and response-boundary audit"]
T01 --> T05["T05: Platform catalog + policy"]
T05 --> T06["T06: resumable migration engine"]
T05 --> T07["T07: Admin Dashboard writers"]
T05 --> T08["T08: Developer Console"]
T01 --> T09["T09: OpenAPI and docs sources"]
T09 --> T10["T10: JavaScript SDK"]
T09 --> T11["T11: Python SDK"]
T10 --> T12["T12: starter / template follow-through"]
T02 --> T13["T13: cross-repo integration + release evidence"]
T03 --> T13
T04 --> T13
T06 --> T13
T07 --> T13
T08 --> T13
T11 --> T13
T12 --> T13
T13 --> T14["T14: approved operational rollout"]
Dependencies describe integration order, not a requirement to wait before drafting independent disabled code. T02/T03/T05 compatible readers must be deployed before migration or new-scope issuance. T09/T10/T11 customer-facing releases must be ready before new granular-only credentials are delivered.
Owner role: technical lead / release engineer. Dependencies: none.
Read current repository instructions, manifests and workflows for the nine in-scope repositories in the parent source map. Record qf-form-handler separately as owner-confirmed retired/historical-only, not an active writer needing another retirement approval or a new release lane. First revalidate the branch matrix in parent section 6A and record the initial base, all ordered promotion targets and current HEADs. For application implementation, analyze the testing-stage code rather than relying only on the earlier default/production snapshots. In Content API this means testing-warsh, then compare do-staging, pre-live and do; do not base the initial feature on do.
Record deployment receipts, runtime versions, schema state, relevant open PRs and service boundaries for each stage. Distinguish branch names, GitHub environment labels, deployed service origins and Hydra/Platform target identifiers. Gateway, Users Backend and Admin use pre-live; Platform and Developer Console use prelive. Do not infer a physical Hydra/database target from either spelling. Inspect each stage's own workflow and the actual App State promotion diffs before reconciling multi-client links, rate-limiter changes and migration history. Identify any merge that triggers deployment in the current in-scope repositories. Do not treat the retired Form Handler's retained workflow as evidence of an active deployment or a release dependency.
Search every scoped repository for content token strings, scope catalogs, scope writes, Hydra create/update/patch calls, grant recomputation, hard-coded defaults, credential rotation, import/claim, reconciliation and automation. Inventory each active creation/update path and its lock/provisioning policy, including Developer Console → Platform API and relevant Admin Dashboard operations. Accept the owner's confirmation that Form Handler was retired when Developer Console was introduced; exclude that repository from active-writer work. Include existing clients originally issued through it in the legacy-client inventory. Inventory current routed operations against sheet/OpenAPI/Rails sources and locate ingress/cache/auth checks.
Deliverables: release manifest, writer ownership table, full route-difference report, relevant PR conflict notes and legacy behavior fixtures. Done when: each writer is marked update / retire with owner approval / not deployed with evidence; unknown deployment facts remain explicit and block the relevant activation only.
Owner: API/security. Dependencies: T00; D1–D5 before approval.
Implement the proposed contract/schema/snapshot files from Appendix A in qf-api-docs. Generate the 208-row provenance report, 95-entry Content mapping, alias resolution, finite migration prerequisites, quota references and machine-readable cross-repo fixtures. Preserve original rows 47/48 alongside approved overrides. Classify missing routes and public QuranReflect duplicates; preserve independent OAuth/User/Search policies.
Tests: schema validation; nine-label/count fixtures; no unknown scopes; no conflicting normalized keys; exact route precedence; no content.create read migration; no reflection grant from content alone; no overlap with user sync or restricted scopes. A generated manifest must fail if source/decision hashes change unexpectedly.