TenantAtlas/specs/182-platform-relocation/tasks.md

Tasks: Platform Relocation to apps/platform

Input: Design documents from /specs/182-platform-relocation/ Prerequisites: plan.md (required), spec.md (required for user stories), research.md, data-model.md, contracts/, quickstart.md

Tests: Tests are REQUIRED for this feature. Use focused Pest coverage under apps/platform/tests/Feature/PlatformRelocation/ plus the documented smoke validation from specs/182-platform-relocation/quickstart.md. Operations: This feature does not introduce a new OperationRun type or change existing operations UX semantics. Queue and worker smoke validation is still required because the relocation changes runtime pathing for existing queued flows. RBAC: No authorization model changes are allowed. Smoke and regression validation must preserve existing 404 versus 403 behavior on /admin, /admin/t/{tenant}/..., and /system routes after the move. Operator Surfaces: No operator-surface redesign is part of this slice. Existing public, admin, tenant, and system surfaces must continue to render with the same route and authorization semantics after relocation. Filament UI Action Surfaces: No new Filament action surfaces are introduced. Existing resources and pages must continue to work unchanged once the app runs from apps/platform. Filament UI UX-001: No layout or information-architecture redesign is part of this feature. Filament panels, themes, and existing surface contracts must remain intact. Badges: No badge semantics change is planned. Existing badge rendering must continue to work after relocation.

Organization: Tasks are grouped by user story so each story can be implemented and validated as an independent increment after the blocking relocation groundwork is complete.

Phase 1: Setup (Shared Relocation Scaffolding)

Purpose: Prepare the target app root and shared relocation-specific scaffolding before moving the app.

• T001 Create the relocated app root scaffold under apps/platform/ and reserve the repo-root orchestration layer in apps/platform/ and .gitignore
• T002 [P] Create the relocation smoke test namespace in apps/platform/tests/Feature/PlatformRelocation/
• T003 [P] Create the compatibility-only Sail delegation helper scaffold in scripts/platform-sail

---

Phase 2: Foundational (Blocking Prerequisites)

Purpose: Complete the blocking file move and runtime boundary changes before any story-specific work begins.

⚠️ CRITICAL: No user story work should begin until this phase is complete.

• T004 Move all Laravel-owned runtime directories and files into apps/platform/app/, apps/platform/bootstrap/, apps/platform/config/, apps/platform/database/, apps/platform/public/, apps/platform/resources/, apps/platform/routes/, apps/platform/storage/, apps/platform/tests/, apps/platform/artisan, apps/platform/composer.json, apps/platform/package.json, apps/platform/vite.config.js, apps/platform/phpunit.xml, apps/platform/phpunit.pgsql.xml, apps/platform/drizzle.config.ts, and apps/platform/.env.example
• T005 Update compose mounts, build contexts, and queue command resolution for the relocated app in docker-compose.yml
• T006 [P] Re-home app env ownership and PHPUnit bootstrap configuration in apps/platform/.env.example, apps/platform/phpunit.xml, and apps/platform/phpunit.pgsql.xml
• T007 [P] Add foundational relocated-app bootstrap-path smoke coverage in apps/platform/tests/Feature/PlatformRelocation/BootstrapPathSmokeTest.php
• T008 Align repo-level ignore and boundary files with the new topology in .gitignore and .dockerignore

Checkpoint: The Laravel app now lives only in apps/platform, and the repo root is ready to act as orchestration only.

---

Phase 3: User Story 1 - Run the Platform From the New Location (Priority: P1) 🎯 MVP

Goal: Make apps/platform the one official local command model for install, boot, build, and test workflows.

Independent Test: Starting from a clean checkout, a developer can follow the documented workflow in apps/platform and reach a running application plus a passing focused smoke run without ad-hoc path fixes.

Tests for User Story 1

• T009 [P] [US1] Add command-model smoke coverage for app-local Sail delegation and CLI bootstrap in apps/platform/tests/Feature/PlatformRelocation/CommandModelSmokeTest.php

Implementation for User Story 1

• T010 [US1] Implement the app-local Sail compose bridge in apps/platform/.env.example and scripts/platform-sail
• T011 [P] [US1] Normalize developer install, build, and test commands in apps/platform/composer.json and apps/platform/package.json
• T012 [P] [US1] Update the canonical setup, file-placement contract, and command documentation in README.md and specs/182-platform-relocation/quickstart.md
• T013 [US1] Align human and assistant guidance to the single apps/platform workflow in Agents.md, GEMINI.md, and .github/copilot-instructions.md
• T014 [US1] Run and time the clean-checkout command flow from specs/182-platform-relocation/quickstart.md

Checkpoint: The repo now has one official local workflow, centered on apps/platform.

---

Phase 4: User Story 2 - Keep Existing Runtime Surfaces Stable (Priority: P1)

Goal: Preserve public entry, panels, assets, and queue-backed runtime behavior after the move.

Independent Test: The relocated app boots through Sail, serves the public and Filament shells, preserves choose-workspace and representative tenant-route behavior including 404 versus 403 semantics, builds assets correctly, and runs a representative queue-backed flow without root-path errors.

Tests for User Story 2

• T015 [P] [US2] Add preserved HTTP surface and authorization smoke coverage for /, /admin, /admin/choose-workspace, /admin/t/{tenant}/backup-sets, and /system, including expected 404 versus 403 behavior, in apps/platform/tests/Feature/PlatformRelocation/PanelRouteSmokeTest.php
• T016 [P] [US2] Add queue and runtime smoke coverage for health, storage, and worker boot in apps/platform/tests/Feature/PlatformRelocation/RuntimeSmokeTest.php

Implementation for User Story 2

• T017 [US2] Preserve bootstrap and public-entry behavior in apps/platform/artisan, apps/platform/bootstrap/app.php, and apps/platform/public/index.php
• T018 [P] [US2] Re-home Vite inputs and Tailwind or Filament theme source scanning in apps/platform/vite.config.js, apps/platform/resources/css/filament/admin/theme.css, and apps/platform/resources/css/filament/system/theme.css
• T019 [P] [US2] Preserve Filament provider registration and panel asset integrity in apps/platform/bootstrap/providers.php, apps/platform/app/Providers/Filament/AdminPanelProvider.php, apps/platform/app/Providers/Filament/TenantPanelProvider.php, and apps/platform/app/Providers/Filament/SystemPanelProvider.php
• T020 [US2] Finalize container runtime, queue worker, and node_modules handling in docker-compose.yml
• T021 [US2] Run the runtime smoke pack from specs/182-platform-relocation/quickstart.md against build, panel, workspace-selection, route-semantics, tenant-route authorization, and queue flows

Checkpoint: The relocated app serves the same runtime surfaces and background behavior as before the move.

---

Phase 5: User Story 3 - Review and Roll Back the Move Safely (Priority: P2)

Goal: Provide a realistic rollback path, open-branch guidance, and visible deployment unknowns for the topology move.

Independent Test: A maintainer can read the rollout docs and understand how to revert the move locally, clean up dependencies and Docker state, and communicate branch impact without reverse-engineering the implementation.

Implementation for User Story 3

• T022 [US3] Document git rollback and local environment recovery in README.md and specs/182-platform-relocation/quickstart.md
• T023 [P] [US3] Document branch-impact, merge, and rebase guidance for the topology move in Agents.md and docs/HANDOVER.md
• T024 [P] [US3] Capture external deployment unknowns and rollout gates in docs/HANDOVER.md and README.md
• T025 [US3] Validate rollback notes and rollback timing evidence against relocated env, vendor, node_modules, and Docker cleanup paths in specs/182-platform-relocation/quickstart.md

Checkpoint: Rollback and rollout risk are explicit, reviewable, and grounded in the relocated path structure.

---

Phase 6: User Story 4 - Keep Repo Tooling Aligned With the New Topology (Priority: P3)

Goal: Ensure repo-level tooling, tasks, and MCP launchers target the relocated app correctly.

Independent Test: At least one MCP flow and one VS Code task succeed against the relocated app without manual path correction.

Implementation for User Story 4

• T026 [P] [US4] Repoint repo-level MCP launchers to the relocated app in .vscode/mcp.json and opencode.json
• T027 [US4] Normalize maintained VS Code task commands to delegate into apps/platform or scripts/platform-sail in .vscode/tasks.json
• T028 [P] [US4] Align assistant context and workspace automation assumptions with the relocated path model in .github/agents/copilot-instructions.md and .github/copilot-instructions.md
• T029 [US4] Validate one MCP flow and one VS Code task from specs/182-platform-relocation/quickstart.md

Checkpoint: Repo tooling no longer assumes the Laravel app lives at repo root.

---

Phase 7: Polish & Cross-Cutting Concerns

Purpose: Remove stale references, format touched files, and finish the full smoke pass.

• T030 [P] Remove stale root-relative platform command references across README.md, Agents.md, GEMINI.md, .github/copilot-instructions.md, .vscode/tasks.json, .vscode/mcp.json, and opencode.json
• T031 [P] Run formatting for relocated PHP and config changes using the workflow documented in specs/182-platform-relocation/quickstart.md
• T032 [P] Run the focused relocation Pest smoke suite in apps/platform/tests/Feature/PlatformRelocation/
• T033 Run the full documented smoke validation and capture final rollout evidence, including setup and rollback timing proof, from specs/182-platform-relocation/quickstart.md

---

Dependencies & Execution Order

Phase Dependencies

• Setup (Phase 1): Starts immediately and prepares the target directory and shared scaffolding.
• Foundational (Phase 2): Depends on Setup and blocks all user stories until the app move and compose boundary work are complete.
• User Story 1 (Phase 3): Starts after Foundational and establishes the official command model.
• User Story 2 (Phase 4): Starts after Foundational and should be completed alongside or immediately after User Story 1 because runtime validation depends on the new command model.
• User Story 3 (Phase 5): Starts after User Stories 1 and 2 because rollback and rollout guidance must reflect the final relocated runtime.
• User Story 4 (Phase 6): Starts after User Story 1 because tooling should target the finalized command model and helper strategy.
• Polish (Phase 7): Starts after all desired user stories are complete.

User Story Dependencies

• US1: Depends only on Setup and Foundational work.
• US2: Depends on Setup and Foundational work and should reuse the command model established in US1.
• US3: Depends on US1 and US2 so rollback and rollout notes describe the final relocated runtime.
• US4: Depends on US1 so tooling delegates to the canonical app-local workflow rather than a temporary path.

Within Each User Story

• Tests or validation coverage should be added before the corresponding story is considered complete.
• File-move and compose changes must land before docs or tooling that depend on the relocated paths.
• Focused smoke validation should pass before moving to the next story or phase.

Parallel Opportunities

• T002 and T003 can run in parallel during Setup.
• T006 and T007 can run in parallel once T004 establishes the relocated app root.
• T009, T011, and T012 can run in parallel for US1 after the Sail bridge direction is fixed.
• T015, T016, T018, and T019 can run in parallel for US2 once bootstrap paths are stable.
• T023 and T024 can run in parallel for US3.
• T026 and T028 can run in parallel for US4.
• T030, T031, and T032 can run in parallel during Polish.

---

Parallel Example: User Story 1

# Story 1 command-model work in parallel:
Task: T009 apps/platform/tests/Feature/PlatformRelocation/CommandModelSmokeTest.php
Task: T011 apps/platform/composer.json and apps/platform/package.json
Task: T012 README.md and specs/182-platform-relocation/quickstart.md

Parallel Example: User Story 2

# Story 2 runtime work in parallel:
Task: T015 apps/platform/tests/Feature/PlatformRelocation/PanelRouteSmokeTest.php
Task: T016 apps/platform/tests/Feature/PlatformRelocation/RuntimeSmokeTest.php
Task: T018 apps/platform/vite.config.js and apps/platform/resources/css/filament/*/theme.css
Task: T019 apps/platform/bootstrap/providers.php and apps/platform/app/Providers/Filament/*.php

Parallel Example: User Story 4

# Story 4 tooling work in parallel:
Task: T026 .vscode/mcp.json and opencode.json
Task: T028 .github/agents/copilot-instructions.md and .github/copilot-instructions.md

---

Implementation Strategy

MVP First

1. Complete Phase 1: Setup.
2. Complete Phase 2: Foundational.
3. Complete Phase 3: User Story 1.
4. Complete Phase 4: User Story 2.
5. STOP and VALIDATE: Run the focused smoke pack and confirm the relocated app boots, serves panels, and runs queue-backed behavior.

Incremental Delivery

1. Finish Setup and Foundational to establish the relocated app root.
2. Deliver US1 to lock the canonical command model.
3. Deliver US2 to prove runtime integrity.
4. Deliver US3 to document rollback and rollout boundaries.
5. Deliver US4 to align repo tooling and automation.

Parallel Team Strategy

With multiple developers:

1. Complete Setup and Foundational together.
2. After Foundational:
   • Developer A: US1 command model and documentation
   • Developer B: US2 runtime and panel smoke
3. After US1 is stable:
   • Developer C: US4 tooling and MCP alignment
4. After US1 and US2 are stable:
   • Developer D: US3 rollback and rollout documentation

---

Notes

• Suggested MVP scope for this feature is US1 + US2, not US1 alone, because a repository-topology move is only viable when the canonical command model and the relocated runtime both work.
• Keep any root-level helper explicitly labeled as compatibility-only so the repo does not drift back into a dual-workflow state.