Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion dev/build/ProjectInstructions/PROJECT_INSTRUCTIONS.md
Original file line number Diff line number Diff line change
Expand Up @@ -117,7 +117,7 @@ Rules:

## Current Version/Date

- Project Instructions Version: 2026.06.28.009
- Project Instructions Version: 2026.06.28.010
- Date: 2026-06-28
- Owner: OWNER

Expand Down
5 changes: 3 additions & 2 deletions dev/build/ProjectInstructions/PROJECT_INSTRUCTIONS_VERSION.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Project Instructions Version

Current Project Instructions Version: 2026.06.28.009
Current Project Instructions Version: 2026.06.28.010

Last Updated: 2026-06-28

Expand All @@ -16,7 +16,8 @@ Last Updated: 2026-06-28
- Added `www/` migration map for safe browser-served application movement planning.
- Added local route-root compatibility toggle documentation for future `www/` activation.
- Moved browser-served application files under `www/` and made local static serving prefer `www/` by default.
- Moved server/API application runtime under `api/`; browser API clients remain outside `api/` and developer-only bootstrap remains in `dev/` until the local-runtime migration PR.
- Moved server/API application runtime under `api/`; browser API clients remain outside `api/`.
- Moved developer-only local runtime/bootstrap entrypoints under `dev/local-runtime/` and preserved the public npm command surface.
- 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.
12 changes: 6 additions & 6 deletions dev/build/ProjectInstructions/PROJECT_STATE.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# Project State

```yaml
project_state_version: "2026.06.28.009"
project_state_version: "2026.06.28.010"
last_updated: "2026-06-28"
current_main_commit: "40de767476d70cadfd1292c916844c2f31b6f185"
repository_status:
Expand All @@ -10,18 +10,18 @@ repository_status:
runtime_database: "Postgres"
creator_metadata: "API to Postgres"
creator_assets: "API to R2"
project_instructions_version: "2026.06.28.009"
repository_structure_version: "2026.06.28.009"
canonical_layout_version: "2026.06.28.009"
project_instructions_version: "2026.06.28.010"
repository_structure_version: "2026.06.28.010"
canonical_layout_version: "2026.06.28.010"
active_teams:
- "Owner"
- "Alfa"
- "Bravo"
- "Charlie"
- "Delta"
- "Golf"
latest_owner_pr: "PR_26180_OWNER_009-move-api-application"
latest_structure_pr: "PR_26180_OWNER_009-move-api-application"
latest_owner_pr: "PR_26180_OWNER_010-move-dev-local-runtime"
latest_structure_pr: "PR_26180_OWNER_010-move-dev-local-runtime"
valid_top_level_folders:
- "api/"
- "deploy/"
Expand Down
10 changes: 5 additions & 5 deletions dev/build/ProjectInstructions/backlog/BACKLOG_MASTER.md
Original file line number Diff line number Diff line change
Expand Up @@ -39,9 +39,9 @@ The backlog is the authoritative source for determining the next logical PRs.
- Team: Owner
- Product Area: Repository Architecture Simplification
- Status: Active
- Percent Complete: 40%
- Active PR: PR_26180_OWNER_009-move-api-application
- Next Milestone: Move developer-only local runtime into `dev/local-runtime/`
- Percent Complete: 50%
- Active PR: PR_26180_OWNER_010-move-dev-local-runtime
- Next Milestone: Move tests and validation path references for the new layout
- Source / Reference: `dev/build/ProjectInstructions/repository/repository_layout_architecture_plan.md`; `dev/build/ProjectInstructions/repository/www_migration_map.md`

## Game Journey MVP
Expand Down Expand Up @@ -214,8 +214,8 @@ The backlog is the authoritative source for determining the next logical PRs.
- `npm run dev:local-api` remains as the legacy API alias.
- `npm run dev:api` supports API-only startup.
- `npm run dev:web` supports web-only startup.
- `dev/bootstrap/start-dev.mjs` owns bootstrap orchestration.
- `dev/bootstrap/team-port-config.mjs` owns team port resolution.
- `dev/local-runtime/start-dev.mjs` owns bootstrap orchestration.
- `dev/local-runtime/team-port-config.mjs` owns team port resolution.
- Team-aware `--team` runtime support is implemented.
- Bootstrap orchestration, browser launch reporting, and port resolution are implemented.
- Verified command: `npm run dev:bootstrap -- --team bravo`.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -52,7 +52,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/local-runtime/ owns developer-only local runtime bootstrap, team port resolution, local diagnostics, and browser launch orchestration.
- 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.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,9 @@ No browser, API, server, test, script, or runtime files move in the scaffold or

`PR_26180_OWNER_008-move-www-application` moved browser-served application files under `www/` and made local static serving prefer `www/` while preserving public URLs.

`PR_26180_OWNER_009-move-api-application` moves server/API application runtime under `api/` while preserving `/api/*` route behavior. Browser API client modules remain outside `api/`, and developer-only local startup orchestration remains under `dev/` until the local-runtime migration PR.
`PR_26180_OWNER_009-move-api-application` moves server/API application runtime under `api/` while preserving `/api/*` route behavior. Browser API client modules remain outside `api/`.

`PR_26180_OWNER_010-move-dev-local-runtime` moves developer-only local runtime/bootstrap entrypoints under `dev/local-runtime/` while preserving `npm run dev:bootstrap`, `npm run dev:api`, `npm run dev:web`, and `npm run dev:local-api`.

## Proposed Future Layout

Expand Down Expand Up @@ -95,7 +97,7 @@ Local development may use the team-aware developer bootstrap and local runtime s
Developer command -> dev bootstrap -> local www server + local api server -> Postgres/R2 or approved local provider
```

Current local bootstrap commands remain unchanged by this plan. This PR does not modify `package.json` commands.
Current local bootstrap command names remain stable. `PR_26180_OWNER_010-move-dev-local-runtime` updates the command targets to `dev/local-runtime/` without changing the user-facing command names.

The local developer workflow must continue to prove the same browser/API/database contract that deployed environments use.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -111,7 +111,7 @@ Three active server/helper surfaces currently resolve static browser paths throu

| File | Current behavior |
| --- | --- |
| `dev/scripts/start-dev.mjs` | Team-aware bootstrap static server resolves requests with `resolveStaticRouteTarget()`, preferring `www/` while preserving public route URLs and compatibility routes. |
| `dev/local-runtime/start-dev.mjs` | Team-aware bootstrap static server resolves requests with `resolveStaticRouteTarget()`, preferring `www/` while preserving public route URLs and compatibility routes. |
| `api/server/local-api-server.mjs` | Legacy local API alias serves API routes and falls back to `resolveStaticRouteTarget()`, preferring `www/` while preserving public route URLs and compatibility routes. |
| `dev/tests/helpers/playwrightRepoServer.mjs` | Playwright test server mirrors the shared static route resolver and compatibility routes. |

Expand Down Expand Up @@ -151,7 +151,6 @@ The `www/` move PR updated test helpers and route expectations for the filesyste

### Defer

- Moving developer bootstrap into `dev/local-runtime/`.
- Removing legacy root compatibility routes.
- Changing package commands.
- Renaming public URLs.
Expand Down
1 change: 0 additions & 1 deletion dev/local-runtime/.gitkeep

This file was deleted.

File renamed without changes.
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
# PR_26180_OWNER_010 Branch Validation

## Startup Validation

- Project Instructions version: 2026.06.28.010
- Repository source: PASS
- Cached memory discarded: PASS
- Canonical paths loaded: PASS
- `PROJECT_BRANCHING_POLICY.md` loaded: PASS

## Branch

- Current branch: `PR_26180_OWNER_010-move-dev-local-runtime`
- Expected stacked base: `PR_26180_OWNER_009-move-api-application`
- Stacked PR model: PASS
- Worktree before branch creation: clean

## Scope Validation

- Local runtime/bootstrap files moved into `dev/local-runtime/`: PASS
- API/server files not moved: PASS
- Browser/www files not moved: PASS
- Public npm command names preserved: PASS
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
# PR_26180_OWNER_010 Manual Validation Notes

## Manual Review

- Confirmed `dev/local-runtime/` now owns local bootstrap, team port config, startup diagnostics, and browser launch support.
- Confirmed `dev/scripts/` no longer owns the moved local-runtime entrypoints.
- Confirmed `api/` server application files were not moved.
- Confirmed `www/` browser files were not moved.
- Confirmed package command names remain stable.
- Confirmed no stale active references remain to old `dev/scripts/start-dev.mjs`, `dev/scripts/start-local-api-server.mjs`, `dev/scripts/team-port-config.mjs`, or old `dev/bootstrap` paths.

## Process Notes

- The command smoke harness stopped each npm process after diagnostics printed.
- A remaining listener on `127.0.0.1:5501` was identified as a VS Code utility process, not a leftover validation server.
38 changes: 38 additions & 0 deletions dev/reports/PR_26180_OWNER_010-move-dev-local-runtime_report.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
# PR_26180_OWNER_010-move-dev-local-runtime Report

## Executive Summary

PASS. This PR moves developer-only local runtime/bootstrap entrypoints into `dev/local-runtime/` while preserving the public npm command surface.

## Scope Completed

- Moved `dev/scripts/start-dev.mjs` to `dev/local-runtime/start-dev.mjs`.
- Moved `dev/scripts/start-local-api-server.mjs` to `dev/local-runtime/start-local-api-server.mjs`.
- Moved `dev/scripts/team-port-config.mjs` to `dev/local-runtime/team-port-config.mjs`.
- Removed `dev/local-runtime/.gitkeep` because the folder now contains active files.
- Updated package scripts while preserving command names:
- `npm run dev:bootstrap`
- `npm run dev:api`
- `npm run dev:web`
- `npm run dev:local-api`
- Updated targeted tests and validation references to the new local-runtime paths.
- Updated Project Instructions version to `2026.06.28.010`.
- Updated Repository Architecture Simplification backlog status to 50%.

## Scope Boundaries

- API/server application files were not moved.
- Browser/www files were not moved.
- Product behavior was not changed.
- Public command names were preserved.

## Stacked Dependency

- Previous PR dependency: `PR_26180_OWNER_009-move-api-application`
- Current PR: `PR_26180_OWNER_010-move-dev-local-runtime`
- Next planned PR: `PR_26180_OWNER_011-move-tests-and-validation`
- Intended merge order: PR009, then PR010, then PR011.

## Playwright

Playwright was not run because this PR moved local developer entrypoint file locations and preserved route/runtime behavior. Targeted node tests and controlled command smoke checks covered the moved startup surface.
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
# PR_26180_OWNER_010 Requirement Checklist

| Requirement | Status | Evidence |
| --- | --- | --- |
| Base on `PR_26180_OWNER_009-move-api-application` | PASS | Branch was created from PR009 stacked base. |
| Move team-aware bootstrap orchestration into `dev/local-runtime/` | PASS | `start-dev.mjs` moved to `dev/local-runtime/`. |
| Move local port/team config into `dev/local-runtime/` | PASS | `team-port-config.mjs` moved to `dev/local-runtime/`. |
| Move local diagnostics and browser launch support into `dev/local-runtime/` | PASS | `start-dev.mjs` and `start-local-api-server.mjs` moved together. |
| Update package commands to new paths | PASS | `package.json` points commands at `dev/local-runtime/`. |
| Preserve `npm run dev:bootstrap` | PASS | Command smoke produced expected owner diagnostics. |
| Preserve `npm run dev:api` | PASS | Command smoke produced expected owner diagnostics. |
| Preserve `npm run dev:web` | PASS | Command smoke produced expected owner diagnostics. |
| Preserve `npm run dev:local-api` legacy alias | PASS | Alias remains in `package.json`; startup logging tests pass. |
| Do not move API/server app files | PASS | No `api/server` ownership changes in this PR. |
| Do not move www/browser files | PASS | No `www/` files changed. |
| Do not change product behavior | PASS | Path-only local runtime move plus tests/docs/package references. |
| Required reports under `dev/reports/` | PASS | Reports generated. |
| Required ZIP under `dev/workspace/zips/` | PASS | ZIP generated. |
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
# PR_26180_OWNER_010 Validation Report

## Commands

| Command | Result |
| --- | --- |
| `git diff --check` | PASS |
| `npm run validate:canonical-structure` | PASS |
| `node --check dev/local-runtime/start-dev.mjs` | PASS |
| `node --check dev/local-runtime/start-local-api-server.mjs` | PASS |
| `node --check dev/local-runtime/team-port-config.mjs` | PASS |
| `node --check dev/scripts/validate-browser-env-agnostic.mjs` | PASS |
| `node --check dev/tests/dev-runtime/TeamAwareBootstrap.test.mjs` | PASS |
| `node --check dev/tests/dev-runtime/LocalApiStartupLogging.test.mjs` | PASS |
| `node --check dev/tests/dev-runtime/StaticWebRootCompatibility.test.mjs` | PASS |
| `node ./dev/scripts/run-node-test-files.mjs dev/tests/dev-runtime/TeamAwareBootstrap.test.mjs dev/tests/dev-runtime/LocalApiStartupLogging.test.mjs dev/tests/dev-runtime/StaticWebRootCompatibility.test.mjs` | PASS, 3/3 files and 18/18 subtests |

## Bootstrap Command Smoke

Each command was started through npm, observed until expected diagnostics printed, and then stopped.

| Command | Result |
| --- | --- |
| `npm run dev:bootstrap -- --team owner` | PASS |
| `npm run dev:api -- --team owner` | PASS |
| `npm run dev:web -- --team owner` | PASS |

Expected diagnostics observed:

- `Mode: bootstrap`, `Team: owner`, `Web URL: http://127.0.0.1:5500`, `API URL: http://127.0.0.1:5501/api`
- `Mode: api`, `Team: owner`, `API URL: http://127.0.0.1:5501/api`
- `Mode: web`, `Team: owner`, `Web URL: http://127.0.0.1:5500`

## Playwright

Not run. This PR moves local developer entrypoint file locations and preserves route behavior. Targeted startup diagnostics and command smoke checks cover the changed surface.
17 changes: 12 additions & 5 deletions dev/reports/codex_changed_files.txt
Original file line number Diff line number Diff line change
@@ -1,5 +1,12 @@
dev/reports/PR_26180_OWNER_009-move-api-application_branch-validation.md
dev/reports/PR_26180_OWNER_009-move-api-application_manual-validation-notes.md
dev/reports/PR_26180_OWNER_009-move-api-application_report.md
dev/reports/PR_26180_OWNER_009-move-api-application_requirement-checklist.md
dev/reports/PR_26180_OWNER_009-move-api-application_validation-report.md
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/build/ProjectInstructions/repository/www_migration_map.md
dev/scripts/validate-browser-env-agnostic.mjs
dev/tests/dev-runtime/LocalApiStartupLogging.test.mjs
dev/tests/dev-runtime/StaticWebRootCompatibility.test.mjs
dev/tests/dev-runtime/TeamAwareBootstrap.test.mjs
package.json
Loading
Loading