From d103c922158ad9d232602e8c1fc0bef2d98e1922 Mon Sep 17 00:00:00 2001 From: Alfa Team Date: Sun, 28 Jun 2026 17:15:48 -0400 Subject: [PATCH] Document www migration map --- .../PROJECT_INSTRUCTIONS.md | 3 +- .../PROJECT_INSTRUCTIONS_VERSION.md | 3 +- .../ProjectInstructions/PROJECT_STATE.md | 12 +- .../backlog/BACKLOG_MASTER.md | 6 +- .../repository_layout_architecture_plan.md | 24 +- .../repository/www_migration_map.md | 221 ++++++++ ...006-www-migration-map_branch-validation.md | 14 + ...w-migration-map_manual-validation-notes.md | 7 + ...6180_OWNER_006-www-migration-map_report.md | 38 ++ ...www-migration-map_requirement-checklist.md | 22 + ...006-www-migration-map_validation-report.md | 15 + dev/reports/codex_changed_files.txt | 15 +- dev/reports/codex_review.diff | 532 +++++++++++------- 13 files changed, 669 insertions(+), 243 deletions(-) create mode 100644 dev/build/ProjectInstructions/repository/www_migration_map.md create mode 100644 dev/reports/PR_26180_OWNER_006-www-migration-map_branch-validation.md create mode 100644 dev/reports/PR_26180_OWNER_006-www-migration-map_manual-validation-notes.md create mode 100644 dev/reports/PR_26180_OWNER_006-www-migration-map_report.md create mode 100644 dev/reports/PR_26180_OWNER_006-www-migration-map_requirement-checklist.md create mode 100644 dev/reports/PR_26180_OWNER_006-www-migration-map_validation-report.md diff --git a/dev/build/ProjectInstructions/PROJECT_INSTRUCTIONS.md b/dev/build/ProjectInstructions/PROJECT_INSTRUCTIONS.md index c1e5bd33a..80fa93d38 100644 --- a/dev/build/ProjectInstructions/PROJECT_INSTRUCTIONS.md +++ b/dev/build/ProjectInstructions/PROJECT_INSTRUCTIONS.md @@ -117,7 +117,7 @@ Rules: ## Current Version/Date -- Project Instructions Version: 2026.06.28.005 +- Project Instructions Version: 2026.06.28.006 - Date: 2026-06-28 - Owner: OWNER @@ -196,6 +196,7 @@ That file owns Start of Day, PLAN_PR, BUILD_PR, APPLY_PR, and invalid command be - Project state: `dev/build/ProjectInstructions/PROJECT_STATE.md` - Repository folder placement SSoT: `dev/build/ProjectInstructions/repository/canonical_repository_structure.md` - Proposed repository layout architecture plan: `dev/build/ProjectInstructions/repository/repository_layout_architecture_plan.md` +- `www/` migration map: `dev/build/ProjectInstructions/repository/www_migration_map.md` - Codex workflow commands: `dev/build/ProjectInstructions/standards/CODEX_WORKFLOW_COMMANDS.md` - Codex Start-of-Day bootstrap: `dev/build/ProjectInstructions/bootstrap/codex_start_of_day_bootstrap.md` - Branch lifecycle: `dev/build/ProjectInstructions/addendums/project_instructions_single_source_eod_lock.md` diff --git a/dev/build/ProjectInstructions/PROJECT_INSTRUCTIONS_VERSION.md b/dev/build/ProjectInstructions/PROJECT_INSTRUCTIONS_VERSION.md index fb6a5ce89..b69da6446 100644 --- a/dev/build/ProjectInstructions/PROJECT_INSTRUCTIONS_VERSION.md +++ b/dev/build/ProjectInstructions/PROJECT_INSTRUCTIONS_VERSION.md @@ -1,6 +1,6 @@ # Project Instructions Version -Current Project Instructions Version: 2026.06.28.005 +Current Project Instructions Version: 2026.06.28.006 Last Updated: 2026-06-28 @@ -13,6 +13,7 @@ Last Updated: 2026-06-28 - Added backlog startup assignment policy requiring `BACKLOG_MASTER.md` and Tool Votes/Admin Owner priority signal review during team startup. - Added proposed repository layout architecture plan for future `www/`, `api/`, and `dev/` separation. - Added repository layout scaffold governance for `www/`, `api/`, and `dev/local-runtime/`. +- Added `www/` migration map for safe browser-served application movement planning. - Codex must read this version file and the latest repository copy of `PROJECT_INSTRUCTIONS.md` before performing work. - Codex must discard previously remembered Project Instructions and treat the repository copy as authoritative. - Codex must validate canonical report and ZIP paths, branching model, and legacy path avoidance before work proceeds. diff --git a/dev/build/ProjectInstructions/PROJECT_STATE.md b/dev/build/ProjectInstructions/PROJECT_STATE.md index 633e2121c..79b89c03d 100644 --- a/dev/build/ProjectInstructions/PROJECT_STATE.md +++ b/dev/build/ProjectInstructions/PROJECT_STATE.md @@ -1,7 +1,7 @@ # Project State ```yaml -project_state_version: "2026.06.28.005" +project_state_version: "2026.06.28.006" last_updated: "2026-06-28" current_main_commit: "40de767476d70cadfd1292c916844c2f31b6f185" repository_status: @@ -10,9 +10,9 @@ repository_status: runtime_database: "Postgres" creator_metadata: "API to Postgres" creator_assets: "API to R2" -project_instructions_version: "2026.06.28.005" -repository_structure_version: "2026.06.28.005" -canonical_layout_version: "2026.06.28.005" +project_instructions_version: "2026.06.28.006" +repository_structure_version: "2026.06.28.006" +canonical_layout_version: "2026.06.28.006" active_teams: - "Owner" - "Alfa" @@ -20,8 +20,8 @@ active_teams: - "Charlie" - "Delta" - "Golf" -latest_owner_pr: "PR_26180_OWNER_005-repository-layout-scaffold" -latest_structure_pr: "PR_26180_OWNER_005-repository-layout-scaffold" +latest_owner_pr: "PR_26180_OWNER_006-www-migration-map" +latest_structure_pr: "PR_26180_OWNER_006-www-migration-map" valid_top_level_folders: - "account/" - "admin/" diff --git a/dev/build/ProjectInstructions/backlog/BACKLOG_MASTER.md b/dev/build/ProjectInstructions/backlog/BACKLOG_MASTER.md index 6c71e71a7..e571a4024 100644 --- a/dev/build/ProjectInstructions/backlog/BACKLOG_MASTER.md +++ b/dev/build/ProjectInstructions/backlog/BACKLOG_MASTER.md @@ -39,10 +39,10 @@ The backlog is the authoritative source for determining the next logical PRs. - Team: Owner - Product Area: Repository Architecture Simplification - Status: Active -- Percent Complete: 10% -- Active PR: PR_26180_OWNER_005-repository-layout-scaffold +- Percent Complete: 15% +- Active PR: PR_26180_OWNER_006-www-migration-map - Next Milestone: Move browser-served application to `www/` -- Source / Reference: `dev/build/ProjectInstructions/repository/repository_layout_architecture_plan.md` +- Source / Reference: `dev/build/ProjectInstructions/repository/repository_layout_architecture_plan.md`; `dev/build/ProjectInstructions/repository/www_migration_map.md` ## Game Journey MVP diff --git a/dev/build/ProjectInstructions/repository/repository_layout_architecture_plan.md b/dev/build/ProjectInstructions/repository/repository_layout_architecture_plan.md index c700068f8..3a33327a5 100644 --- a/dev/build/ProjectInstructions/repository/repository_layout_architecture_plan.md +++ b/dev/build/ProjectInstructions/repository/repository_layout_architecture_plan.md @@ -12,13 +12,15 @@ This plan does not authorize moving files, changing runtime behavior, changing p ## Current Migration Status -`PR_26180_OWNER_005-repository-layout-scaffold` creates the empty canonical destination shells: +`PR_26180_OWNER_005-repository-layout-scaffold` created the empty canonical destination shells: - `www/` - `api/` - `dev/local-runtime/` -No browser, API, server, test, script, or runtime files move in the scaffold PR. +`PR_26180_OWNER_006-www-migration-map` documents the current browser-served surface and safe move requirements before any browser files move into `www/`. + +No browser, API, server, test, script, or runtime files move in the scaffold or migration-map PRs. ## Proposed Future Layout @@ -110,37 +112,41 @@ Rules: - Create `www/`, `api/`, and `dev/local-runtime/` shells. - Update architecture docs and backlog status only. -2. `PR_26180_OWNER_006-move-www-application` +2. `PR_26180_OWNER_006-www-migration-map` + - Document current browser-served root paths, imports, local server behavior, test assumptions, compatibility needs, and validation lanes. + - Do not move browser files or change package commands. + +3. `PR_26180_OWNER_007-move-www-application` - Move browser-served application files into `www/`. - Include root HTML pages, `assets/`, `toolbox/`, `account/`, `legal/`, `learn/`, `play/`, and other browser-served static routes. - Update internal static references only as needed. - Do not move API/server files. -3. `PR_26180_OWNER_007-move-api-application` +4. `PR_26180_OWNER_008-move-api-application` - Move server/API application files into `api/`. - Include Local API server runtime files, API routes, services, database, storage, auth, publishing, and admin server code. - Do not move developer-only startup orchestration. - Browser code must not import from `api/`. -4. `PR_26180_OWNER_008-move-dev-local-runtime` +5. `PR_26180_OWNER_009-move-dev-local-runtime` - Move developer-only local runtime into `dev/local-runtime/`. - Include team-aware bootstrap, port config, local startup orchestration, local diagnostics, and browser launch support. - Update `package.json` commands to point to the new local-runtime paths. -5. `PR_26180_OWNER_009-move-tests-and-validation` +6. `PR_26180_OWNER_010-move-tests-and-validation` - Ensure all tests and validation suites live under `dev/tests/` or the current canonical dev test structure. - Update test paths after the `www/`, `api/`, and `dev/` migrations. - Do not change behavior. -6. `PR_26180_OWNER_010-update-ci-and-scripts` +7. `PR_26180_OWNER_011-update-ci-and-scripts` - Update CI, package scripts, validation scripts, and developer utilities for the new layout. - Preserve `npm run dev:bootstrap`, `npm run dev:api`, `npm run dev:web`, and `npm run dev:local-api`. -7. `PR_26180_OWNER_011-remove-legacy-layout` +8. `PR_26180_OWNER_012-remove-legacy-layout` - Remove or retire obsolete legacy paths after all references are updated. - Hard stop if any runtime, test, or CI reference still points to old locations. -8. `PR_26180_OWNER_012-final-layout-validation` +9. `PR_26180_OWNER_013-final-layout-validation` - Validate final repository layout. - Confirm `www/` owns the browser-served app, `api/` owns the server app, and `dev/` owns the developer workspace. - Confirm runtime does not depend on `dev/`, browser code does not import `api/`, and legacy references are removed or documented. diff --git a/dev/build/ProjectInstructions/repository/www_migration_map.md b/dev/build/ProjectInstructions/repository/www_migration_map.md new file mode 100644 index 000000000..bd617513d --- /dev/null +++ b/dev/build/ProjectInstructions/repository/www_migration_map.md @@ -0,0 +1,221 @@ +# www Migration Map + +Status: Active planning map +Owner: Owner +Workstream: Repository Architecture Simplification +PR: PR_26180_OWNER_006-www-migration-map + +## Purpose + +Document the current browser-served repository surface and the safe sequence required before moving files into `www/`. + +This map is a no-runtime-change governance artifact. It does not move browser files, change package commands, change local server behavior, or update runtime imports. + +## Executive Summary + +The browser-served application currently depends on repository-root static serving. + +Current local runtime, test helpers, and browser pages assume URLs such as `/index.html`, `/toolbox/index.html`, `/assets/theme-v2/css/theme.css`, `/account/sign-in.html`, `/admin/system-health.html`, and `/games/index.html` resolve from the repository root. + +Moving browser files into `www/` is feasible, but the move must preserve public route URLs while changing the filesystem lookup root. A direct folder move without route compatibility would break Playwright tests, local API static serving, team-aware bootstrap static serving, Node test root aliases, and browser imports that still reference root-level `src/`, `toolbox/`, and `assets/`. + +## Current Browser-Served Surface + +Current root-level browser-served entry points and folders include: + +| Path | Current role | Files | HTML files | Move target | +| --- | --- | ---: | ---: | --- | +| `index.html` | Root marketing/product entry | 1 | 1 | `www/index.html` | +| `account/` | Account pages | 13 | 11 | `www/account/` | +| `admin/` | Admin/Owner pages | 18 | 16 | `www/admin/` | +| `assets/` | Browser assets, Theme V2, tool assets, partials | 328 | 5 | `www/assets/` | +| `community/` | Community/public pages | 3 | 3 | `www/community/` | +| `company/` | Company/public pages | 7 | 7 | `www/company/` | +| `docs/` | Production Docs & Help pages | 5 | 4 | `www/docs/` only when route preservation is ready | +| `games/` | Public game discovery pages | 12 | 8 | `www/games/` | +| `learn/` | Learning pages | 11 | 11 | `www/learn/` | +| `legal/` | Legal pages | 17 | 9 | `www/legal/` | +| `marketplace/` | Marketplace page | 1 | 1 | `www/marketplace/` | +| `memberships/` | Membership page | 1 | 1 | `www/memberships/` | +| `owner/` | Owner governance/admin pages | 8 | 8 | `www/owner/` | +| `toolbox/` | Creator toolbox pages and legacy sidecars | 57 | 49 | `www/toolbox/` | + +No top-level `play/` folder exists in the current tracked repository root. Any existing `play/` string references must be reviewed as route/content references before a future move introduces or preserves a `play/` route. + +## Current Reference Inventory + +Broad active-reference search across browser roots, `src/`, `dev/scripts/`, and `dev/tests/` found: + +| Reference | Approximate active files | Notes | +| --- | ---: | --- | +| `assets/` | 230 | Theme CSS/JS, images, tool JS, workers, partials, and test fixtures. | +| `toolbox/` | 241 | Tool routes, registry routes, tests, validation scripts, and server route compatibility. | +| `account/` | 43 | Account routes, return URLs, and Playwright coverage. | +| `legal/` | 13 | Footer/navigation route references and page links. | +| `learn/` | 9 | Learn route links and navigation. | +| `play/` | 7 | No root folder exists; review references manually before introducing a route. | +| `src/` | 451 | Browser imports, server imports, tests, validation aliases, and current runtime/source modules. | + +The high `src/` count means the browser migration cannot be treated as static files only. Several browser-facing pages import modules from root-level `src/`, including account/admin/toolbox flows. + +## Examples Of References That Must Be Preserved Or Rewritten + +### Preserve public route URLs + +These URLs should continue working for users and tests during the move: + +- `/index.html` +- `/toolbox/index.html` +- `/toolbox/{tool}/index.html` +- `/account/{page}.html` +- `/admin/{page}.html` +- `/games/index.html` +- `/learn/index.html` +- `/legal/index.html` +- `/marketplace/index.html` +- `/memberships/index.html` + +### Rewrite filesystem lookup paths + +Static servers and test helpers should map public URLs to `www/` filesystem paths after the move: + +- `/index.html` -> `www/index.html` +- `/toolbox/index.html` -> `www/toolbox/index.html` +- `/assets/theme-v2/css/theme.css` -> `www/assets/theme-v2/css/theme.css` + +### Preserve service/API route behavior + +API routes must remain API routes and must not be resolved as static browser files: + +- `/api/*` +- `/api/toolbox/*` +- `/api/session/*` +- `/api/auth/*` + +### Browser import references needing migration review + +Examples of current references that depend on root-level path relationships: + +- `account/user-controls-page.js` imports from `../src/api/` and `../src/engine/`. +- `admin/tool-votes.js` imports from `../src/api/` and `../toolbox/tool-registry-api-client.js`. +- `admin/db-viewer.js` imports from `../src/api/`. +- `owner/notes.html` loads `../src/dev-runtime/admin/admin-notes-viewer.js`. +- `toolbox/toolRegistry.js` imports from `../src/shared/toolbox/tool-metadata-inventory.js`. +- `assets/toolbox/*/js/index.js` imports from `../../../../src/` or `../../../../toolbox/` in several tool flows. + +These references can be preserved temporarily by serving compatibility paths from the repository root, but the final architecture should move browser-facing runtime modules into `www/` or an approved deployable browser module surface. + +## Current Local Web Server Root Behavior + +Three active server/helper surfaces currently resolve static browser paths from the repository root: + +| File | Current behavior | +| --- | --- | +| `dev/scripts/start-dev.mjs` | Team-aware bootstrap static server resolves requests with `path.resolve(repoRoot, \`.\${normalizedPath}\`)`. `/` maps to `/index.html`; `/tools/*` maps to `/toolbox/*`; `/admin/admin-notes.html` maps to `/src/dev-runtime/admin/notes.html`. | +| `src/dev-runtime/server/local-api-server.mjs` | Legacy local API alias serves API routes and falls back to static files from `repoRoot`. `/tools/*` maps to `/toolbox/*`; `/admin/admin-notes.html` maps to `/src/dev-runtime/admin/notes.html`. | +| `dev/tests/helpers/playwrightRepoServer.mjs` | Playwright test server mirrors repo-root static serving and the `/tools/*` and admin-notes compatibility routes. | + +The actual `www/` move must update these filesystem lookup roots or introduce a shared route resolver that can resolve public routes to `www/` while preserving API route ownership. + +## Current Test Assumptions + +Playwright and runtime tests currently assume root-based public routes and root-relative filesystem paths: + +- 96 Playwright/helper/runtime files reference public routes such as `/toolbox`, `/account`, `/admin`, `/games`, `/learn`, `/legal`, `/marketplace`, `/memberships`, or `/index.html`. +- `dev/tests/playwright/tools/ToolNavigationPrevNext.spec.mjs` opens `/toolbox/index.html` and `/toolbox/game-design/index.html`. +- `dev/tests/playwright/tools/BuildPathProgressSimplification.spec.mjs` opens `/index.html`, `/toolbox/index.html`, and `/admin/tool-votes.html`. +- `dev/tests/playwright/tools/EnvironmentBannerCoverage.spec.mjs` covers root/home, marketplace, learn, and memberships route families. +- `dev/tests/runtime/V2*` tests frequently assert `toolbox/{tool}/index.html` filesystem or URL behavior. +- `dev/scripts/run-node-tests.mjs` and `dev/scripts/run-node-test-files.mjs` register root aliases for `/src/` and `/toolbox/`. + +The move PR must update test helpers and route expectations in the same PR that changes the filesystem root. Browser-visible URLs should remain stable unless Owner explicitly approves a public URL change. + +## Preserve Versus Rewrite + +### Preserve + +- Public browser URLs. +- `/tools/*` compatibility routing to toolbox pages until Owner approves route removal. +- `/api/*` service contract routes. +- Theme V2 asset URLs as browser routes, even if filesystem paths move under `www/`. +- Tool route semantics and Product Owner test flows. +- Existing package commands until the PR explicitly scoped to command migration. + +### Rewrite + +- Filesystem path resolution in local static servers and Playwright test helpers. +- Internal static file lookup roots from repository root to `www/`. +- Relative links/imports that break because source and target files move together. +- Validation scripts that inspect browser-served file locations. +- Coverage mapping that classifies `toolbox/`, `assets/theme-v2/js/`, and browser routes after the move. + +### Defer + +- Moving server/API code into `api/`. +- Moving developer bootstrap into `dev/local-runtime/`. +- Removing legacy root compatibility routes. +- Changing package commands. +- Renaming public URLs. + +## Compatibility Redirects Or Shims + +Temporary compatibility is likely required. + +Recommended approach for the actual move PR: + +1. Preserve public URLs while changing filesystem roots. +2. Add a shared route resolution helper or equivalent route table for local runtime/test servers. +3. Keep `/tools/*` -> `/toolbox/*` compatibility. +4. Keep root URL families stable: `/account`, `/admin`, `/assets`, `/games`, `/learn`, `/legal`, `/marketplace`, `/memberships`, `/owner`, `/toolbox`. +5. Do not introduce browser redirects unless a static route cannot be served directly. +6. Document every temporary shim with removal criteria for the legacy-layout cleanup PR. + +## Required Sequence For Safe www Move + +1. Freeze the public route contract. +2. Move `index.html` and browser-served folders into `www/`. +3. Update local static server filesystem roots to resolve from `www/` for browser routes. +4. Preserve `/api/*` API routing before static fallback. +5. Preserve compatibility route aliases such as `/tools/*`. +6. Update Playwright repo server helper to mirror runtime static route resolution. +7. Update browser relative imports and links only where the move changes relative depth. +8. Update validation scripts and coverage prefix mapping for `www/` paths. +9. Run targeted Playwright lanes for root/home, account/admin, toolbox navigation, environment banner, and impacted tool flows. +10. Produce a compatibility ledger for any root path still supported temporarily. + +## Validation Lanes Required For The Actual Move PR + +Minimum validation for the actual `www/` move: + +- `git diff --check` +- `npm run validate:canonical-structure` +- `node ./dev/scripts/run-platform-validation-suite.mjs` +- targeted Playwright route lanes touching: + - root/home + - account sign-in/session + - admin owner navigation + - toolbox navigation + - Tool Display Mode + - environment banner coverage + - games index/discovery +- targeted runtime tests that assert `toolbox/{tool}/index.html` or filesystem existence. + +Fallback validation if targeted routing failures are broad: + +- `npm run test:workspace-v2` +- `npm run test:lane:tool-navigation` +- `npm run test:lane:tool-display-mode` +- impacted Playwright specs under `dev/tests/playwright/account/`, `dev/tests/playwright/games/`, and `dev/tests/playwright/tools/`. + +## Owner Recommendation + +Do not perform the browser move until the actual move PR explicitly owns: + +- static server filesystem root migration, +- Playwright helper root migration, +- route compatibility ledger, +- browser relative import/link rewrites, +- validation script prefix updates, +- and targeted Playwright execution. + +The next implementation PR should be a focused `www/` move PR that preserves public URLs while moving the filesystem root to `www/`. diff --git a/dev/reports/PR_26180_OWNER_006-www-migration-map_branch-validation.md b/dev/reports/PR_26180_OWNER_006-www-migration-map_branch-validation.md new file mode 100644 index 000000000..67c2ad5fd --- /dev/null +++ b/dev/reports/PR_26180_OWNER_006-www-migration-map_branch-validation.md @@ -0,0 +1,14 @@ +# PR_26180_OWNER_006-www-migration-map Branch Validation + +| Check | Result | Notes | +| --- | --- | --- | +| Startup validation completed | PASS | Project Instructions v2026.06.28.005 loaded before branch creation; PR updates version to v2026.06.28.006. | +| Current branch | PASS | `PR_26180_OWNER_006-www-migration-map` | +| Expected stacked base | PASS | Created from `PR_26180_OWNER_005-repository-layout-scaffold`. | +| Worktree clean before edits | PASS | Branch started with no modified files. | +| PR model | PASS | Owner stacked PR under Repository Architecture Simplification. | +| Previous dependency documented | PASS | `PR_26180_OWNER_005-repository-layout-scaffold` | +| Next dependency documented | PASS | `PR_26180_OWNER_007-move-www-application` | +| Runtime/API/UI/database scope | PASS | No implementation files changed. | + +Starting HEAD: `31bb8f9238e0f7d81bc64fb8d2e15c4fb82875ff` diff --git a/dev/reports/PR_26180_OWNER_006-www-migration-map_manual-validation-notes.md b/dev/reports/PR_26180_OWNER_006-www-migration-map_manual-validation-notes.md new file mode 100644 index 000000000..8f3362033 --- /dev/null +++ b/dev/reports/PR_26180_OWNER_006-www-migration-map_manual-validation-notes.md @@ -0,0 +1,7 @@ +# PR_26180_OWNER_006-www-migration-map Manual Validation Notes + +- Confirmed this PR documents the `www/` migration and does not perform it. +- Confirmed current browser-served paths rely on repository-root static serving. +- Confirmed public URLs should be preserved during the actual move. +- Confirmed compatibility route handling is needed before moving files into `www/`. +- Confirmed no Product Owner UI validation is required for this no-runtime-change map. diff --git a/dev/reports/PR_26180_OWNER_006-www-migration-map_report.md b/dev/reports/PR_26180_OWNER_006-www-migration-map_report.md new file mode 100644 index 000000000..7ab4f6792 --- /dev/null +++ b/dev/reports/PR_26180_OWNER_006-www-migration-map_report.md @@ -0,0 +1,38 @@ +# PR_26180_OWNER_006-www-migration-map Report + +## Executive Summary + +PASS - Created a no-runtime-change migration map for moving browser-served files into `www/` safely. The map documents the current browser-served root, current route/import/test assumptions, local server root behavior, compatibility needs, and validation lanes required before the actual move. + +This PR does not move browser files, alter `package.json`, change local server behavior, or modify runtime/API/UI/database implementation files. + +## Stack Metadata + +- Workstream: Repository Architecture Simplification +- PR model: Stacked PR +- Stack step: PR006 mapping step after PR005 scaffold +- Previous dependency: `PR_26180_OWNER_005-repository-layout-scaffold` +- Current PR: `PR_26180_OWNER_006-www-migration-map` +- Next dependency: `PR_26180_OWNER_007-move-www-application` +- Base branch for GitHub PR: `PR_26180_OWNER_005-repository-layout-scaffold` +- Source branch: `PR_26180_OWNER_006-www-migration-map` + +## Deliverables + +- Added `dev/build/ProjectInstructions/repository/www_migration_map.md`. +- Updated Project Instructions version to `2026.06.28.006`. +- Updated Project Instructions pointers to include the migration map. +- Updated project state/latest structure PR metadata. +- Updated repository layout architecture plan so PR006 is explicitly a mapping step and the actual web move becomes the next dependency. +- Updated BACKLOG_MASTER.md to mark Repository Architecture Simplification at 15% with PR006 active. + +## Evidence Summary + +- Current browser-served roots include `index.html`, `account/`, `admin/`, `assets/`, `community/`, `company/`, `docs/`, `games/`, `learn/`, `legal/`, `marketplace/`, `memberships/`, `owner/`, and `toolbox/`. +- Current reference search found broad use of `assets/`, `toolbox/`, `account/`, `legal/`, `learn/`, `play/`, and `src/` paths across active browser roots, tests, scripts, and source. +- Current static serving resolves browser paths from repository root in `dev/scripts/start-dev.mjs`, `src/dev-runtime/server/local-api-server.mjs`, and `dev/tests/helpers/playwrightRepoServer.mjs`. +- Playwright/runtime tests assume stable public URLs such as `/index.html`, `/toolbox/index.html`, `/account/sign-in.html`, `/admin/system-health.html`, and `/games/index.html`. + +## Runtime Impact + +None. This is a documentation/governance map only. diff --git a/dev/reports/PR_26180_OWNER_006-www-migration-map_requirement-checklist.md b/dev/reports/PR_26180_OWNER_006-www-migration-map_requirement-checklist.md new file mode 100644 index 000000000..e84fab70d --- /dev/null +++ b/dev/reports/PR_26180_OWNER_006-www-migration-map_requirement-checklist.md @@ -0,0 +1,22 @@ +# PR_26180_OWNER_006-www-migration-map Requirement Checklist + +| Requirement | Result | Evidence | +| --- | --- | --- | +| Base is `PR_26180_OWNER_005-repository-layout-scaffold` | PASS | Branch created from PR005 scaffold branch. | +| Create no-runtime-change migration map | PASS | Added `www_migration_map.md`. | +| Do not move browser files yet | PASS | No browser-served files moved. | +| Do not change package.json commands yet | PASS | `package.json` unchanged. | +| Do not change runtime behavior | PASS | No runtime/server/API implementation files changed. | +| Review root-level browser-served folders/pages | PASS | Map includes current browser surface table and counts. | +| Review current imports/references | PASS | Map includes reference inventory and examples. | +| Review local web server root behavior | PASS | Map documents `start-dev.mjs`, `local-api-server.mjs`, and Playwright repo server root behavior. | +| Review Playwright/test assumptions | PASS | Map documents public route and filesystem assumptions. | +| Document required safe sequence | PASS | Map includes required sequence for safe `www/` move. | +| Document preserve vs rewrite | PASS | Map separates preserve, rewrite, and defer decisions. | +| Determine compatibility redirects/shims | PASS | Map recommends temporary route compatibility and shim ledger. | +| Document validation lanes for actual move | PASS | Map lists required validation lanes. | +| Required reports under dev/reports | PASS | Report set generated. | +| Required ZIP under dev/workspace/zips | PASS | `dev/workspace/zips/PR_26180_OWNER_006-www-migration-map_delta.zip` generated. | +| git diff --check | PASS | No whitespace errors. | +| npm run validate:canonical-structure | PASS | Blocking violations: 0. | +| No runtime/API/UI/database changes | PASS | Changed files are Project Instructions/backlog/reports only. | diff --git a/dev/reports/PR_26180_OWNER_006-www-migration-map_validation-report.md b/dev/reports/PR_26180_OWNER_006-www-migration-map_validation-report.md new file mode 100644 index 000000000..02b6863ab --- /dev/null +++ b/dev/reports/PR_26180_OWNER_006-www-migration-map_validation-report.md @@ -0,0 +1,15 @@ +# PR_26180_OWNER_006-www-migration-map Validation Report + +| Validation | Result | Notes | +| --- | --- | --- | +| git diff --check | PASS | No whitespace errors. | +| npm run validate:canonical-structure | PASS | Blocking violations: 0; approved legacy exceptions: 501. | +| Runtime/API/UI/database implementation change check | PASS | Only Project Instructions/backlog/reports changed. | +| Playwright | PASS | Not required; no browser files moved and no UI routes changed. | + +## Commands Run + +```text +git diff --check +npm run validate:canonical-structure +``` diff --git a/dev/reports/codex_changed_files.txt b/dev/reports/codex_changed_files.txt index b66b95a42..573b9513c 100644 --- a/dev/reports/codex_changed_files.txt +++ b/dev/reports/codex_changed_files.txt @@ -1,16 +1,13 @@ -api/.gitkeep dev/build/ProjectInstructions/PROJECT_INSTRUCTIONS.md dev/build/ProjectInstructions/PROJECT_INSTRUCTIONS_VERSION.md dev/build/ProjectInstructions/PROJECT_STATE.md dev/build/ProjectInstructions/backlog/BACKLOG_MASTER.md -dev/build/ProjectInstructions/repository/canonical_repository_structure.md dev/build/ProjectInstructions/repository/repository_layout_architecture_plan.md -dev/local-runtime/.gitkeep -dev/reports/PR_26180_OWNER_005-repository-layout-scaffold_branch-validation.md -dev/reports/PR_26180_OWNER_005-repository-layout-scaffold_manual-validation-notes.md -dev/reports/PR_26180_OWNER_005-repository-layout-scaffold_report.md -dev/reports/PR_26180_OWNER_005-repository-layout-scaffold_requirement-checklist.md -dev/reports/PR_26180_OWNER_005-repository-layout-scaffold_validation-report.md +dev/build/ProjectInstructions/repository/www_migration_map.md +dev/reports/PR_26180_OWNER_006-www-migration-map_branch-validation.md +dev/reports/PR_26180_OWNER_006-www-migration-map_manual-validation-notes.md +dev/reports/PR_26180_OWNER_006-www-migration-map_report.md +dev/reports/PR_26180_OWNER_006-www-migration-map_requirement-checklist.md +dev/reports/PR_26180_OWNER_006-www-migration-map_validation-report.md dev/reports/codex_changed_files.txt dev/reports/codex_review.diff -www/.gitkeep diff --git a/dev/reports/codex_review.diff b/dev/reports/codex_review.diff index 07af31e2b..11855db25 100644 --- a/dev/reports/codex_review.diff +++ b/dev/reports/codex_review.diff @@ -1,53 +1,54 @@ -diff --git a/api/.gitkeep b/api/.gitkeep -new file mode 100644 -index 000000000..8b1378917 ---- /dev/null -+++ b/api/.gitkeep -@@ -0,0 +1 @@ -+ diff --git a/dev/build/ProjectInstructions/PROJECT_INSTRUCTIONS.md b/dev/build/ProjectInstructions/PROJECT_INSTRUCTIONS.md -index aeda69a61..c1e5bd33a 100644 +index c1e5bd33a..80fa93d38 100644 --- a/dev/build/ProjectInstructions/PROJECT_INSTRUCTIONS.md +++ b/dev/build/ProjectInstructions/PROJECT_INSTRUCTIONS.md @@ -117,7 +117,7 @@ Rules: ## Current Version/Date --- Project Instructions Version: 2026.06.28.004 -+- Project Instructions Version: 2026.06.28.005 +-- Project Instructions Version: 2026.06.28.005 ++- Project Instructions Version: 2026.06.28.006 - Date: 2026-06-28 - Owner: OWNER +@@ -196,6 +196,7 @@ That file owns Start of Day, PLAN_PR, BUILD_PR, APPLY_PR, and invalid command be + - Project state: `dev/build/ProjectInstructions/PROJECT_STATE.md` + - Repository folder placement SSoT: `dev/build/ProjectInstructions/repository/canonical_repository_structure.md` + - Proposed repository layout architecture plan: `dev/build/ProjectInstructions/repository/repository_layout_architecture_plan.md` ++- `www/` migration map: `dev/build/ProjectInstructions/repository/www_migration_map.md` + - Codex workflow commands: `dev/build/ProjectInstructions/standards/CODEX_WORKFLOW_COMMANDS.md` + - Codex Start-of-Day bootstrap: `dev/build/ProjectInstructions/bootstrap/codex_start_of_day_bootstrap.md` + - Branch lifecycle: `dev/build/ProjectInstructions/addendums/project_instructions_single_source_eod_lock.md` diff --git a/dev/build/ProjectInstructions/PROJECT_INSTRUCTIONS_VERSION.md b/dev/build/ProjectInstructions/PROJECT_INSTRUCTIONS_VERSION.md -index d489f2af4..fb6a5ce89 100644 +index fb6a5ce89..b69da6446 100644 --- a/dev/build/ProjectInstructions/PROJECT_INSTRUCTIONS_VERSION.md +++ b/dev/build/ProjectInstructions/PROJECT_INSTRUCTIONS_VERSION.md @@ -1,6 +1,6 @@ # Project Instructions Version --Current Project Instructions Version: 2026.06.28.004 -+Current Project Instructions Version: 2026.06.28.005 +-Current Project Instructions Version: 2026.06.28.005 ++Current Project Instructions Version: 2026.06.28.006 Last Updated: 2026-06-28 -@@ -12,6 +12,7 @@ Last Updated: 2026-06-28 - - Startup validation now verifies the branching policy document was loaded instead of duplicating policy text. +@@ -13,6 +13,7 @@ Last Updated: 2026-06-28 - Added backlog startup assignment policy requiring `BACKLOG_MASTER.md` and Tool Votes/Admin Owner priority signal review during team startup. - Added proposed repository layout architecture plan for future `www/`, `api/`, and `dev/` separation. -+- Added repository layout scaffold governance for `www/`, `api/`, and `dev/local-runtime/`. + - Added repository layout scaffold governance for `www/`, `api/`, and `dev/local-runtime/`. ++- Added `www/` migration map for safe browser-served application movement planning. - Codex must read this version file and the latest repository copy of `PROJECT_INSTRUCTIONS.md` before performing work. - Codex must discard previously remembered Project Instructions and treat the repository copy as authoritative. - Codex must validate canonical report and ZIP paths, branching model, and legacy path avoidance before work proceeds. diff --git a/dev/build/ProjectInstructions/PROJECT_STATE.md b/dev/build/ProjectInstructions/PROJECT_STATE.md -index 145a9f088..633e2121c 100644 +index 633e2121c..79b89c03d 100644 --- a/dev/build/ProjectInstructions/PROJECT_STATE.md +++ b/dev/build/ProjectInstructions/PROJECT_STATE.md @@ -1,7 +1,7 @@ # Project State ```yaml --project_state_version: "2026-06-28.PR_26179_OWNER_010" -+project_state_version: "2026.06.28.005" +-project_state_version: "2026.06.28.005" ++project_state_version: "2026.06.28.006" last_updated: "2026-06-28" current_main_commit: "40de767476d70cadfd1292c916844c2f31b6f185" repository_status: @@ -55,236 +56,339 @@ index 145a9f088..633e2121c 100644 runtime_database: "Postgres" creator_metadata: "API to Postgres" creator_assets: "API to R2" --project_instructions_version: "2026-06-28.PR_26179_OWNER_010" --repository_structure_version: "2026-06-28.PR_26179_OWNER_010" --canonical_layout_version: "2026-06-28.PR_26179_OWNER_010" -+project_instructions_version: "2026.06.28.005" -+repository_structure_version: "2026.06.28.005" -+canonical_layout_version: "2026.06.28.005" +-project_instructions_version: "2026.06.28.005" +-repository_structure_version: "2026.06.28.005" +-canonical_layout_version: "2026.06.28.005" ++project_instructions_version: "2026.06.28.006" ++repository_structure_version: "2026.06.28.006" ++canonical_layout_version: "2026.06.28.006" active_teams: - "Owner" - "Alfa" -@@ -20,11 +20,12 @@ active_teams: +@@ -20,8 +20,8 @@ active_teams: - "Charlie" - "Delta" - "Golf" --latest_owner_pr: "PR_26179_OWNER_010-canonical-project-folder-instructions" --latest_structure_pr: "PR_26179_OWNER_010-canonical-project-folder-instructions" -+latest_owner_pr: "PR_26180_OWNER_005-repository-layout-scaffold" -+latest_structure_pr: "PR_26180_OWNER_005-repository-layout-scaffold" +-latest_owner_pr: "PR_26180_OWNER_005-repository-layout-scaffold" +-latest_structure_pr: "PR_26180_OWNER_005-repository-layout-scaffold" ++latest_owner_pr: "PR_26180_OWNER_006-www-migration-map" ++latest_structure_pr: "PR_26180_OWNER_006-www-migration-map" valid_top_level_folders: - "account/" - "admin/" -+ - "api/" - - "assets/" - - "community/" - - "company/" -@@ -39,10 +40,12 @@ valid_top_level_folders: - - "owner/" - - "src/" - - "toolbox/" -+ - "www/" - valid_dev_folders: - - "dev/archive/" - - "dev/build/" - - "dev/config/" -+ - "dev/local-runtime/" - - "dev/reports/" - - "dev/scripts/" - - "dev/templates/" diff --git a/dev/build/ProjectInstructions/backlog/BACKLOG_MASTER.md b/dev/build/ProjectInstructions/backlog/BACKLOG_MASTER.md -index ee8160a46..6c71e71a7 100644 +index 6c71e71a7..e571a4024 100644 --- a/dev/build/ProjectInstructions/backlog/BACKLOG_MASTER.md +++ b/dev/build/ProjectInstructions/backlog/BACKLOG_MASTER.md -@@ -38,10 +38,10 @@ The backlog is the authoritative source for determining the next logical PRs. - +@@ -39,10 +39,10 @@ The backlog is the authoritative source for determining the next logical PRs. - Team: Owner - Product Area: Repository Architecture Simplification --- Status: Planned --- Percent Complete: 0% --- Active PR: PR_26180_OWNER_004-repository-layout-architecture-plan --- Next Milestone: Architecture plan -+- Status: Active -+- Percent Complete: 10% -+- Active PR: PR_26180_OWNER_005-repository-layout-scaffold -+- Next Milestone: Move browser-served application to `www/` - - Source / Reference: `dev/build/ProjectInstructions/repository/repository_layout_architecture_plan.md` + - Status: Active +-- Percent Complete: 10% +-- Active PR: PR_26180_OWNER_005-repository-layout-scaffold ++- Percent Complete: 15% ++- Active PR: PR_26180_OWNER_006-www-migration-map + - Next Milestone: Move browser-served application to `www/` +-- Source / Reference: `dev/build/ProjectInstructions/repository/repository_layout_architecture_plan.md` ++- Source / Reference: `dev/build/ProjectInstructions/repository/repository_layout_architecture_plan.md`; `dev/build/ProjectInstructions/repository/www_migration_map.md` ## Game Journey MVP -diff --git a/dev/build/ProjectInstructions/repository/canonical_repository_structure.md b/dev/build/ProjectInstructions/repository/canonical_repository_structure.md -index adf926ea2..4c9e960f3 100644 ---- a/dev/build/ProjectInstructions/repository/canonical_repository_structure.md -+++ b/dev/build/ProjectInstructions/repository/canonical_repository_structure.md -@@ -9,6 +9,7 @@ Establish the canonical repository structure for future development and reduce t - Valid top-level folders: - - account/ - - admin/ -+- api/ - - assets/ - - community/ - - company/ -@@ -23,16 +24,19 @@ Valid top-level folders: - - owner/ - - src/ - - toolbox/ -+- www/ - - Root product and repo sections: - - account/, admin/, community/, company/, learn/, legal/, marketplace/, memberships/, and owner/ are production website sections. - - assets/ contains production website and tool assets. -+- api/ is the target Node/API/server application surface for the repository layout simplification workstream. - - docs/ is production Docs & Help content. - - games/ is public game discovery. - - toolbox/ is the Creator toolbox/workspace. - - deploy/ contains deployment configuration. - - dev/ contains the development workspace. - - src/ contains deployable application/runtime/API source. -+- www/ is the target browser-served application surface for the repository layout simplification workstream. - Deployable application source: - - src/web/{feature-name}/ -@@ -51,6 +55,7 @@ Valid dev workspace folders: - - dev/archive/ - - dev/build/ - - dev/config/ -+- dev/local-runtime/ - - dev/reports/ - - dev/scripts/ - - dev/templates/ -@@ -62,6 +67,7 @@ Dev workspace ownership: - - dev/archive/ owns historical reference material only. - - dev/build/ owns active Project Instructions, architecture, database DDL/DML/seed docs, standards, backlog, PR planning, and governance. - - dev/config/ owns development-only runner and tooling configuration. -+- dev/local-runtime/ owns developer-only local runtime bootstrap, team port resolution, local diagnostics, and browser launch orchestration after the migration step that moves those files. - - dev/reports/ owns authoritative Codex reports for the repository. Reports committed to `main` are the official record. - - dev/scripts/ owns development-only scripts and runners. - - dev/templates/ owns reusable development templates. -@@ -96,6 +102,8 @@ These legacy transition buckets may remain until explicit migration PRs move the - ## Rules - - - Root is production website and standard repository configuration only. -+- www/ is the browser-served application target surface for migration. -+- api/ is the Node/API/server application target surface for migration. - - src/ is deployable application/runtime/API code. - - dev/ is development workspace only. - - deploy/ is deployment configuration. diff --git a/dev/build/ProjectInstructions/repository/repository_layout_architecture_plan.md b/dev/build/ProjectInstructions/repository/repository_layout_architecture_plan.md -index f2ec47fee..c700068f8 100644 +index c700068f8..3a33327a5 100644 --- a/dev/build/ProjectInstructions/repository/repository_layout_architecture_plan.md +++ b/dev/build/ProjectInstructions/repository/repository_layout_architecture_plan.md -@@ -1,6 +1,6 @@ - # Repository Layout Architecture Plan +@@ -12,13 +12,15 @@ This plan does not authorize moving files, changing runtime behavior, changing p --Status: Proposed -+Status: Active Scaffold - Owner: Owner - Scope: Documentation/governance only + ## Current Migration Status -@@ -10,6 +10,16 @@ Document the proposed repository architecture simplification before any file mov +-`PR_26180_OWNER_005-repository-layout-scaffold` creates the empty canonical destination shells: ++`PR_26180_OWNER_005-repository-layout-scaffold` created the empty canonical destination shells: - This plan does not authorize moving files, changing runtime behavior, changing package commands, or mixing feature work into layout migration PRs. + - `www/` + - `api/` + - `dev/local-runtime/` -+## Current Migration Status -+ -+`PR_26180_OWNER_005-repository-layout-scaffold` creates the empty canonical destination shells: -+ -+- `www/` -+- `api/` -+- `dev/local-runtime/` -+ -+No browser, API, server, test, script, or runtime files move in the scaffold PR. +-No browser, API, server, test, script, or runtime files move in the scaffold PR. ++`PR_26180_OWNER_006-www-migration-map` documents the current browser-served surface and safe move requirements before any browser files move into `www/`. + - ## Proposed Future Layout - - ```text -@@ -94,38 +104,47 @@ Rules: - - Each migration PR must update references, validation, reports, and ZIP artifacts for only its scoped move. - - Each migration PR must include rollback notes or clear validation evidence. - --## Proposed Stacked PR Sequence -+## Active Stacked PR Sequence - --1. `www/` shell and governance -- - Create the destination shell and document browser-served ownership. -- - Do not move product pages yet. -+1. `PR_26180_OWNER_005-repository-layout-scaffold` -+ - Create `www/`, `api/`, and `dev/local-runtime/` shells. -+ - Update architecture docs and backlog status only. - --2. `api/` shell and governance -- - Create the destination shell and document API/server ownership. -- - Do not move API/runtime implementation yet. -+2. `PR_26180_OWNER_006-move-www-application` -+ - Move browser-served application files into `www/`. -+ - Include root HTML pages, `assets/`, `toolbox/`, `account/`, `legal/`, `learn/`, `play/`, and other browser-served static routes. -+ - Update internal static references only as needed. -+ - Do not move API/server files. ++No browser, API, server, test, script, or runtime files move in the scaffold or migration-map PRs. --3. Browser-served public section moves -- - Move root browser-served product sections into `www/` in small groups. -- - Preserve routes through compatibility redirects or server/static configuration as needed. -+3. `PR_26180_OWNER_007-move-api-application` -+ - Move server/API application files into `api/`. -+ - Include Local API server runtime files, API routes, services, database, storage, auth, publishing, and admin server code. -+ - Do not move developer-only startup orchestration. -+ - Browser code must not import from `api/`. + ## Proposed Future Layout --4. Browser asset moves -- - Move browser assets into `www/` ownership. -- - Preserve asset URLs or update references in the same PR. -+4. `PR_26180_OWNER_008-move-dev-local-runtime` -+ - Move developer-only local runtime into `dev/local-runtime/`. -+ - Include team-aware bootstrap, port config, local startup orchestration, local diagnostics, and browser launch support. -+ - Update `package.json` commands to point to the new local-runtime paths. +@@ -110,37 +112,41 @@ Rules: + - Create `www/`, `api/`, and `dev/local-runtime/` shells. + - Update architecture docs and backlog status only. --5. API/server moves -- - Move Node/API/server entry points and service code into `api/`. -- - Preserve API contract shape and route behavior. -+5. `PR_26180_OWNER_009-move-tests-and-validation` -+ - Ensure all tests and validation suites live under `dev/tests/` or the current canonical dev test structure. -+ - Update test paths after the `www/`, `api/`, and `dev/` migrations. -+ - Do not change behavior. +-2. `PR_26180_OWNER_006-move-www-application` ++2. `PR_26180_OWNER_006-www-migration-map` ++ - Document current browser-served root paths, imports, local server behavior, test assumptions, compatibility needs, and validation lanes. ++ - Do not move browser files or change package commands. ++ ++3. `PR_26180_OWNER_007-move-www-application` + - Move browser-served application files into `www/`. + - Include root HTML pages, `assets/`, `toolbox/`, `account/`, `legal/`, `learn/`, `play/`, and other browser-served static routes. + - Update internal static references only as needed. + - Do not move API/server files. --6. Runtime/shared source boundary cleanup -- - Move deployable browser/runtime/API modules into `www/` or `api/` ownership as appropriate. -- - Keep shared runtime dependency direction explicit. -+6. `PR_26180_OWNER_010-update-ci-and-scripts` -+ - Update CI, package scripts, validation scripts, and developer utilities for the new layout. -+ - Preserve `npm run dev:bootstrap`, `npm run dev:api`, `npm run dev:web`, and `npm run dev:local-api`. +-3. `PR_26180_OWNER_007-move-api-application` ++4. `PR_26180_OWNER_008-move-api-application` + - Move server/API application files into `api/`. + - Include Local API server runtime files, API routes, services, database, storage, auth, publishing, and admin server code. + - Do not move developer-only startup orchestration. + - Browser code must not import from `api/`. --7. Developer bootstrap and validation updates -- - Update local developer bootstrap and validation paths after deployable surfaces are moved. -- - Keep `dev/` developer-only. -+7. `PR_26180_OWNER_011-remove-legacy-layout` -+ - Remove or retire obsolete legacy paths after all references are updated. -+ - Hard stop if any runtime, test, or CI reference still points to old locations. +-4. `PR_26180_OWNER_008-move-dev-local-runtime` ++5. `PR_26180_OWNER_009-move-dev-local-runtime` + - Move developer-only local runtime into `dev/local-runtime/`. + - Include team-aware bootstrap, port config, local startup orchestration, local diagnostics, and browser launch support. + - Update `package.json` commands to point to the new local-runtime paths. --8. Legacy path cleanup -- - Remove or archive obsolete empty folders and compatibility shims only after validation proves they are unused. -+8. `PR_26180_OWNER_012-final-layout-validation` -+ - Validate final repository layout. -+ - Confirm `www/` owns the browser-served app, `api/` owns the server app, and `dev/` owns the developer workspace. -+ - Confirm runtime does not depend on `dev/`, browser code does not import `api/`, and legacy references are removed or documented. -+ - Mark Repository Architecture Simplification complete in `BACKLOG_MASTER.md`. +-5. `PR_26180_OWNER_009-move-tests-and-validation` ++6. `PR_26180_OWNER_010-move-tests-and-validation` + - Ensure all tests and validation suites live under `dev/tests/` or the current canonical dev test structure. + - Update test paths after the `www/`, `api/`, and `dev/` migrations. + - Do not change behavior. - ## Hard Rules +-6. `PR_26180_OWNER_010-update-ci-and-scripts` ++7. `PR_26180_OWNER_011-update-ci-and-scripts` + - Update CI, package scripts, validation scripts, and developer utilities for the new layout. + - Preserve `npm run dev:bootstrap`, `npm run dev:api`, `npm run dev:web`, and `npm run dev:local-api`. -@@ -148,4 +167,3 @@ npm run validate:canonical-structure - ``` +-7. `PR_26180_OWNER_011-remove-legacy-layout` ++8. `PR_26180_OWNER_012-remove-legacy-layout` + - Remove or retire obsolete legacy paths after all references are updated. + - Hard stop if any runtime, test, or CI reference still points to old locations. - Additional targeted validation must match the moved surface. -- -diff --git a/dev/local-runtime/.gitkeep b/dev/local-runtime/.gitkeep +-8. `PR_26180_OWNER_012-final-layout-validation` ++9. `PR_26180_OWNER_013-final-layout-validation` + - Validate final repository layout. + - Confirm `www/` owns the browser-served app, `api/` owns the server app, and `dev/` owns the developer workspace. + - Confirm runtime does not depend on `dev/`, browser code does not import `api/`, and legacy references are removed or documented. +diff --git a/dev/build/ProjectInstructions/repository/www_migration_map.md b/dev/build/ProjectInstructions/repository/www_migration_map.md new file mode 100644 -index 000000000..8b1378917 +index 000000000..bd617513d --- /dev/null -+++ b/dev/local-runtime/.gitkeep -@@ -0,0 +1 @@ ++++ b/dev/build/ProjectInstructions/repository/www_migration_map.md +@@ -0,0 +1,221 @@ ++# www Migration Map + -diff --git a/www/.gitkeep b/www/.gitkeep -new file mode 100644 -index 000000000..8b1378917 ---- /dev/null -+++ b/www/.gitkeep -@@ -0,0 +1 @@ ++Status: Active planning map ++Owner: Owner ++Workstream: Repository Architecture Simplification ++PR: PR_26180_OWNER_006-www-migration-map ++ ++## Purpose ++ ++Document the current browser-served repository surface and the safe sequence required before moving files into `www/`. ++ ++This map is a no-runtime-change governance artifact. It does not move browser files, change package commands, change local server behavior, or update runtime imports. ++ ++## Executive Summary ++ ++The browser-served application currently depends on repository-root static serving. ++ ++Current local runtime, test helpers, and browser pages assume URLs such as `/index.html`, `/toolbox/index.html`, `/assets/theme-v2/css/theme.css`, `/account/sign-in.html`, `/admin/system-health.html`, and `/games/index.html` resolve from the repository root. ++ ++Moving browser files into `www/` is feasible, but the move must preserve public route URLs while changing the filesystem lookup root. A direct folder move without route compatibility would break Playwright tests, local API static serving, team-aware bootstrap static serving, Node test root aliases, and browser imports that still reference root-level `src/`, `toolbox/`, and `assets/`. ++ ++## Current Browser-Served Surface ++ ++Current root-level browser-served entry points and folders include: ++ ++| Path | Current role | Files | HTML files | Move target | ++| --- | --- | ---: | ---: | --- | ++| `index.html` | Root marketing/product entry | 1 | 1 | `www/index.html` | ++| `account/` | Account pages | 13 | 11 | `www/account/` | ++| `admin/` | Admin/Owner pages | 18 | 16 | `www/admin/` | ++| `assets/` | Browser assets, Theme V2, tool assets, partials | 328 | 5 | `www/assets/` | ++| `community/` | Community/public pages | 3 | 3 | `www/community/` | ++| `company/` | Company/public pages | 7 | 7 | `www/company/` | ++| `docs/` | Production Docs & Help pages | 5 | 4 | `www/docs/` only when route preservation is ready | ++| `games/` | Public game discovery pages | 12 | 8 | `www/games/` | ++| `learn/` | Learning pages | 11 | 11 | `www/learn/` | ++| `legal/` | Legal pages | 17 | 9 | `www/legal/` | ++| `marketplace/` | Marketplace page | 1 | 1 | `www/marketplace/` | ++| `memberships/` | Membership page | 1 | 1 | `www/memberships/` | ++| `owner/` | Owner governance/admin pages | 8 | 8 | `www/owner/` | ++| `toolbox/` | Creator toolbox pages and legacy sidecars | 57 | 49 | `www/toolbox/` | ++ ++No top-level `play/` folder exists in the current tracked repository root. Any existing `play/` string references must be reviewed as route/content references before a future move introduces or preserves a `play/` route. ++ ++## Current Reference Inventory ++ ++Broad active-reference search across browser roots, `src/`, `dev/scripts/`, and `dev/tests/` found: ++ ++| Reference | Approximate active files | Notes | ++| --- | ---: | --- | ++| `assets/` | 230 | Theme CSS/JS, images, tool JS, workers, partials, and test fixtures. | ++| `toolbox/` | 241 | Tool routes, registry routes, tests, validation scripts, and server route compatibility. | ++| `account/` | 43 | Account routes, return URLs, and Playwright coverage. | ++| `legal/` | 13 | Footer/navigation route references and page links. | ++| `learn/` | 9 | Learn route links and navigation. | ++| `play/` | 7 | No root folder exists; review references manually before introducing a route. | ++| `src/` | 451 | Browser imports, server imports, tests, validation aliases, and current runtime/source modules. | ++ ++The high `src/` count means the browser migration cannot be treated as static files only. Several browser-facing pages import modules from root-level `src/`, including account/admin/toolbox flows. ++ ++## Examples Of References That Must Be Preserved Or Rewritten ++ ++### Preserve public route URLs ++ ++These URLs should continue working for users and tests during the move: ++ ++- `/index.html` ++- `/toolbox/index.html` ++- `/toolbox/{tool}/index.html` ++- `/account/{page}.html` ++- `/admin/{page}.html` ++- `/games/index.html` ++- `/learn/index.html` ++- `/legal/index.html` ++- `/marketplace/index.html` ++- `/memberships/index.html` ++ ++### Rewrite filesystem lookup paths ++ ++Static servers and test helpers should map public URLs to `www/` filesystem paths after the move: ++ ++- `/index.html` -> `www/index.html` ++- `/toolbox/index.html` -> `www/toolbox/index.html` ++- `/assets/theme-v2/css/theme.css` -> `www/assets/theme-v2/css/theme.css` ++ ++### Preserve service/API route behavior ++ ++API routes must remain API routes and must not be resolved as static browser files: ++ ++- `/api/*` ++- `/api/toolbox/*` ++- `/api/session/*` ++- `/api/auth/*` ++ ++### Browser import references needing migration review ++ ++Examples of current references that depend on root-level path relationships: ++ ++- `account/user-controls-page.js` imports from `../src/api/` and `../src/engine/`. ++- `admin/tool-votes.js` imports from `../src/api/` and `../toolbox/tool-registry-api-client.js`. ++- `admin/db-viewer.js` imports from `../src/api/`. ++- `owner/notes.html` loads `../src/dev-runtime/admin/admin-notes-viewer.js`. ++- `toolbox/toolRegistry.js` imports from `../src/shared/toolbox/tool-metadata-inventory.js`. ++- `assets/toolbox/*/js/index.js` imports from `../../../../src/` or `../../../../toolbox/` in several tool flows. ++ ++These references can be preserved temporarily by serving compatibility paths from the repository root, but the final architecture should move browser-facing runtime modules into `www/` or an approved deployable browser module surface. ++ ++## Current Local Web Server Root Behavior ++ ++Three active server/helper surfaces currently resolve static browser paths from the repository root: ++ ++| File | Current behavior | ++| --- | --- | ++| `dev/scripts/start-dev.mjs` | Team-aware bootstrap static server resolves requests with `path.resolve(repoRoot, \`.\${normalizedPath}\`)`. `/` maps to `/index.html`; `/tools/*` maps to `/toolbox/*`; `/admin/admin-notes.html` maps to `/src/dev-runtime/admin/notes.html`. | ++| `src/dev-runtime/server/local-api-server.mjs` | Legacy local API alias serves API routes and falls back to static files from `repoRoot`. `/tools/*` maps to `/toolbox/*`; `/admin/admin-notes.html` maps to `/src/dev-runtime/admin/notes.html`. | ++| `dev/tests/helpers/playwrightRepoServer.mjs` | Playwright test server mirrors repo-root static serving and the `/tools/*` and admin-notes compatibility routes. | ++ ++The actual `www/` move must update these filesystem lookup roots or introduce a shared route resolver that can resolve public routes to `www/` while preserving API route ownership. ++ ++## Current Test Assumptions ++ ++Playwright and runtime tests currently assume root-based public routes and root-relative filesystem paths: ++ ++- 96 Playwright/helper/runtime files reference public routes such as `/toolbox`, `/account`, `/admin`, `/games`, `/learn`, `/legal`, `/marketplace`, `/memberships`, or `/index.html`. ++- `dev/tests/playwright/tools/ToolNavigationPrevNext.spec.mjs` opens `/toolbox/index.html` and `/toolbox/game-design/index.html`. ++- `dev/tests/playwright/tools/BuildPathProgressSimplification.spec.mjs` opens `/index.html`, `/toolbox/index.html`, and `/admin/tool-votes.html`. ++- `dev/tests/playwright/tools/EnvironmentBannerCoverage.spec.mjs` covers root/home, marketplace, learn, and memberships route families. ++- `dev/tests/runtime/V2*` tests frequently assert `toolbox/{tool}/index.html` filesystem or URL behavior. ++- `dev/scripts/run-node-tests.mjs` and `dev/scripts/run-node-test-files.mjs` register root aliases for `/src/` and `/toolbox/`. ++ ++The move PR must update test helpers and route expectations in the same PR that changes the filesystem root. Browser-visible URLs should remain stable unless Owner explicitly approves a public URL change. ++ ++## Preserve Versus Rewrite ++ ++### Preserve ++ ++- Public browser URLs. ++- `/tools/*` compatibility routing to toolbox pages until Owner approves route removal. ++- `/api/*` service contract routes. ++- Theme V2 asset URLs as browser routes, even if filesystem paths move under `www/`. ++- Tool route semantics and Product Owner test flows. ++- Existing package commands until the PR explicitly scoped to command migration. ++ ++### Rewrite ++ ++- Filesystem path resolution in local static servers and Playwright test helpers. ++- Internal static file lookup roots from repository root to `www/`. ++- Relative links/imports that break because source and target files move together. ++- Validation scripts that inspect browser-served file locations. ++- Coverage mapping that classifies `toolbox/`, `assets/theme-v2/js/`, and browser routes after the move. ++ ++### Defer ++ ++- Moving server/API code into `api/`. ++- Moving developer bootstrap into `dev/local-runtime/`. ++- Removing legacy root compatibility routes. ++- Changing package commands. ++- Renaming public URLs. ++ ++## Compatibility Redirects Or Shims ++ ++Temporary compatibility is likely required. ++ ++Recommended approach for the actual move PR: ++ ++1. Preserve public URLs while changing filesystem roots. ++2. Add a shared route resolution helper or equivalent route table for local runtime/test servers. ++3. Keep `/tools/*` -> `/toolbox/*` compatibility. ++4. Keep root URL families stable: `/account`, `/admin`, `/assets`, `/games`, `/learn`, `/legal`, `/marketplace`, `/memberships`, `/owner`, `/toolbox`. ++5. Do not introduce browser redirects unless a static route cannot be served directly. ++6. Document every temporary shim with removal criteria for the legacy-layout cleanup PR. ++ ++## Required Sequence For Safe www Move ++ ++1. Freeze the public route contract. ++2. Move `index.html` and browser-served folders into `www/`. ++3. Update local static server filesystem roots to resolve from `www/` for browser routes. ++4. Preserve `/api/*` API routing before static fallback. ++5. Preserve compatibility route aliases such as `/tools/*`. ++6. Update Playwright repo server helper to mirror runtime static route resolution. ++7. Update browser relative imports and links only where the move changes relative depth. ++8. Update validation scripts and coverage prefix mapping for `www/` paths. ++9. Run targeted Playwright lanes for root/home, account/admin, toolbox navigation, environment banner, and impacted tool flows. ++10. Produce a compatibility ledger for any root path still supported temporarily. ++ ++## Validation Lanes Required For The Actual Move PR ++ ++Minimum validation for the actual `www/` move: ++ ++- `git diff --check` ++- `npm run validate:canonical-structure` ++- `node ./dev/scripts/run-platform-validation-suite.mjs` ++- targeted Playwright route lanes touching: ++ - root/home ++ - account sign-in/session ++ - admin owner navigation ++ - toolbox navigation ++ - Tool Display Mode ++ - environment banner coverage ++ - games index/discovery ++- targeted runtime tests that assert `toolbox/{tool}/index.html` or filesystem existence. ++ ++Fallback validation if targeted routing failures are broad: ++ ++- `npm run test:workspace-v2` ++- `npm run test:lane:tool-navigation` ++- `npm run test:lane:tool-display-mode` ++- impacted Playwright specs under `dev/tests/playwright/account/`, `dev/tests/playwright/games/`, and `dev/tests/playwright/tools/`. ++ ++## Owner Recommendation ++ ++Do not perform the browser move until the actual move PR explicitly owns: ++ ++- static server filesystem root migration, ++- Playwright helper root migration, ++- route compatibility ledger, ++- browser relative import/link rewrites, ++- validation script prefix updates, ++- and targeted Playwright execution. + ++The next implementation PR should be a focused `www/` move PR that preserves public URLs while moving the filesystem root to `www/`.