Audit root leftovers and src transition

Author: ToolboxAid

dev/build/ProjectInstructions/PROJECT_INSTRUCTIONS.md

@@ -117,7 +117,7 @@ Rules:
 
 ## Current Version/Date
 
-- Project Instructions Version: 2026.06.28.014
+- Project Instructions Version: 2026.06.28.015
 - Date: 2026-06-28
 - Owner: OWNER
 

dev/build/ProjectInstructions/PROJECT_INSTRUCTIONS_VERSION.md

@@ -1,6 +1,6 @@
 # Project Instructions Version
 
-Current Project Instructions Version: 2026.06.28.014
+Current Project Instructions Version: 2026.06.28.015
 
 Last Updated: 2026-06-28
 
@@ -22,6 +22,7 @@ Last Updated: 2026-06-28
 - Updated CI, package scripts, and developer utilities for the `www/`, `api/`, and `dev/` layout.
 - Removed active references to obsolete legacy layout paths after the `www/`, `api/`, and `dev/` migration steps.
 - Moved the tracked browser-served favicon under `www/`, added remaining root/src audit governance, and documented root `.env` placement policy.
+- Added root leftover audit and `src/` transition plan for the final repository layout cleanup stage.
 - 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.

dev/build/ProjectInstructions/PROJECT_STATE.md

@@ -1,7 +1,7 @@
 # Project State
 
 ```yaml
-project_state_version: "2026.06.28.014"
+project_state_version: "2026.06.28.015"
 last_updated: "2026-06-28"
 current_main_commit: "40de767476d70cadfd1292c916844c2f31b6f185"
 repository_status:
@@ -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.014"
-repository_structure_version: "2026.06.28.014"
-canonical_layout_version: "2026.06.28.014"
+project_instructions_version: "2026.06.28.015"
+repository_structure_version: "2026.06.28.015"
+canonical_layout_version: "2026.06.28.015"
 active_teams:
   - "Owner"
   - "Alfa"
   - "Bravo"
   - "Charlie"
   - "Delta"
   - "Golf"
-latest_owner_pr: "PR_26180_OWNER_014-remaining-legacy-layout-cleanup"
-latest_structure_pr: "PR_26180_OWNER_014-remaining-legacy-layout-cleanup"
+latest_owner_pr: "PR_26180_OWNER_015-root-empty-folder-and-src-transition-audit"
+latest_structure_pr: "PR_26180_OWNER_015-root-empty-folder-and-src-transition-audit"
 valid_top_level_folders:
   - "api/"
   - "deploy/"

dev/build/ProjectInstructions/backlog/BACKLOG_MASTER.md

@@ -39,8 +39,8 @@ The backlog is the authoritative source for determining the next logical PRs.
 - Team: Owner
 - Product Area: Repository Architecture Simplification
 - Status: Active
-- Percent Complete: 90%
-- Active PR: PR_26180_OWNER_014-remaining-legacy-layout-cleanup
+- Percent Complete: 95%
+- Active PR: PR_26180_OWNER_015-root-empty-folder-and-src-transition-audit
 - Next Milestone: Final layout validation and completion report
 - Source / Reference: `dev/build/ProjectInstructions/repository/repository_layout_architecture_plan.md`; `dev/build/ProjectInstructions/repository/www_migration_map.md`
 

dev/build/ProjectInstructions/repository/repository_layout_architecture_plan.md

@@ -38,6 +38,8 @@ No browser, API, server, test, script, or runtime files move in the scaffold or
 
 `PR_26180_OWNER_014-remaining-legacy-layout-cleanup` audits remaining tracked root and `src/` layout items, moves the browser-served favicon into `www/`, and records root `.env` placement policy before final validation.
 
+`PR_26180_OWNER_015-root-empty-folder-and-src-transition-audit` audits named root leftovers and records the `src/` transition plan without moving application source or changing product behavior.
+
 ## Proposed Future Layout
 
 ```text
@@ -173,7 +175,13 @@ Rules:
    - Document `.env` placement policy for local and deployed environments.
    - Preserve product behavior and public routes.
 
-11. `PR_26180_OWNER_015-final-layout-validation`
+11. `PR_26180_OWNER_015-root-empty-folder-and-src-transition-audit`
+   - Audit root leftovers after the `www/`, `api/`, and `dev/` migration.
+   - Classify local-only legacy folder shells, ignored/generated leftovers, and tracked `src/` transition content.
+   - Produce the `src/` transition plan for the follow-up final validation stage.
+   - Preserve product behavior.
+
+12. `PR_26180_OWNER_016-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.

dev/reports/PR_26180_OWNER_015-root-empty-folder-and-src-transition-audit_branch-validation.md

@@ -0,0 +1,11 @@
+# PR_26180_OWNER_015 Branch Validation
+
+| Check | Result | Evidence |
+|---|---:|---|
+| Current branch | PASS | `PR_26180_OWNER_015-root-empty-folder-and-src-transition-audit` |
+| Expected stacked base | PASS | Created from `PR_26180_OWNER_014-remaining-legacy-layout-cleanup` |
+| Base branch for PR | PASS | `PR_26180_OWNER_014-remaining-legacy-layout-cleanup` |
+| Project Instructions loaded | PASS | Repository Project Instructions version `2026.06.28.015` |
+| Branching policy loaded | PASS | `PROJECT_BRANCHING_POLICY.md` version `2026.06.28.002` |
+| Scope | PASS | Root leftover audit, `src/` transition plan, governance reports only |
+| Runtime/API/database implementation changes | PASS | None |

dev/reports/PR_26180_OWNER_015-root-empty-folder-and-src-transition-audit_manual-validation-notes.md

@@ -0,0 +1,8 @@
+# PR_26180_OWNER_015 Manual Validation Notes
+
+- No named local-only root folder was deleted in this PR.
+- `assets/DemoGame-26168-001.gfsp` is ignored local data and remains untouched.
+- Empty local directory shells under `games/`, `learn/`, `tmp/`, and `toolbox/` are not tracked and do not affect the PR diff.
+- `src/` is intentionally retained pending explicit source-layer migration PRs.
+- Codex output ZIP is generated under `dev/workspace/zips/`, not root `tmp/`.
+- Public favicon ownership remains `www/favicon.svg`.

dev/reports/PR_26180_OWNER_015-root-empty-folder-and-src-transition-audit_report.md

@@ -0,0 +1,52 @@
+# PR_26180_OWNER_015 Root Empty Folder and src Transition Audit
+
+## Executive Summary
+
+PR_26180_OWNER_015 completes a no-runtime-change audit of named root leftovers after the `www/`, `api/`, and `dev/` migration. No tracked placeholder folders were removed because Git has no tracked content in the named root leftovers except `src/`.
+
+`src/` remains active and tracked. It should not move in this PR because it contains deployable engine/runtime/shared modules and browser API clients still referenced by `www/`, `api/`, `dev/tests/`, and `dev/tools/`.
+
+## Root Folder Audit
+
+| Folder | Exists Locally | Tracked Content | Local/Generated Status | Decision |
+|---|---:|---:|---|---|
+| `assets/` | Yes | 0 tracked files | Contains ignored local `assets/DemoGame-26168-001.gfsp`; remaining entries are local directory shells. | Do not delete in PR. User/local cleanup only unless Owner explicitly approves moving/removing the ignored file. |
+| `games/` | Yes | 0 tracked files | Empty local directory shell. | Do not delete in PR because it is untracked/local-only; safe local cleanup may remove it outside a commit. |
+| `learn/` | Yes | 0 tracked files | Empty local directory shell. | Do not delete in PR because it is untracked/local-only; safe local cleanup may remove it outside a commit. |
+| `src/` | Yes | 596 tracked files | Active transition namespace. | Keep. Requires explicit follow-up migration PRs. |
+| `test-results/` | No | 0 tracked files | Absent. | No action. |
+| `tmp/` | Yes | 0 tracked files | Empty local directory shell. | Do not use for Codex output; canonical ZIPs remain under `dev/workspace/zips/`. |
+| `toolbox/` | Yes | 0 tracked files | Empty local directory shell. | Do not delete in PR because it is untracked/local-only; safe local cleanup may remove it outside a commit. |
+
+## Required Confirmations
+
+- `.env` remains root/local-only and ignored by `.gitignore`.
+- `.env.example` remains tracked as the repository template.
+- `www/favicon.svg` remains the browser-served favicon.
+- No runtime behavior changes were made.
+- No product feature changes were made.
+
+## src Transition Plan
+
+| Current Area | Tracked Files | Why It Remains | Destination | Proposed Follow-Up |
+|---|---:|---|---|---|
+| `src/advanced/` | 10 | Advanced state and promotion logic remains actively tested/referenced. | `src/runtime/advanced/` or another Owner-approved runtime bucket. | Runtime transition PR for advanced state modules. |
+| `src/api/` | 20 | Browser API clients and browser admin/client helpers remain used by `www/` and tests. Browser clients must stay outside top-level `api/`. | `src/web/api-clients/` or `src/runtime/api-clients/`, depending on final source-layer naming. | Browser API client source-layer migration PR. |
+| `src/dev-runtime/admin/` | 4 | Legacy Admin Notes browser-viewer compatibility path is documented in Project Instructions. | `www/admin/` if browser-served, or retire after replacement. | Scoped Admin Notes compatibility retirement PR. |
+| `src/engine/` | 327 | Core game/runtime engine remains heavily referenced by tests and dev tooling. | `src/runtime/engine/`. | Engine source-layer migration PR. |
+| `src/shared/` | 233 | Shared contracts, utilities, random/hash/noise/geometry/color/text/time helpers, and toolbox pipeline logic remain actively referenced. | Split by usage: `src/runtime/shared/`, `src/web/shared/`, and/or `src/api-runtime/shared/`. | Shared source-layer classification and migration PR. |
+| `src/tools/` | 2 | Tool helper modules remain referenced by current tooling/tests. | `src/web/tools/` or `src/runtime/tools/` after ownership review. | Tool helper source-layer migration PR. |
+
+## Follow-Up Recommendation
+
+Do not move `src/` wholesale. Create focused source-layer migration PRs after the layout stack is merged:
+
+1. Browser API clients and browser helper modules.
+2. Engine/runtime modules.
+3. Shared contracts/utilities classification.
+4. Legacy Admin Notes compatibility retirement.
+5. Tool helper modules.
+
+## Scope Boundary
+
+This PR is audit/governance/reporting only. It does not move `src/`, delete local-only root folders, change runtime behavior, change product features, or alter API/database behavior.

dev/reports/PR_26180_OWNER_015-root-empty-folder-and-src-transition-audit_requirement-checklist.md

@@ -0,0 +1,20 @@
+# PR_26180_OWNER_015 Requirement Checklist
+
+| Requirement | Result | Notes |
+|---|---:|---|
+| Base on `PR_26180_OWNER_014-remaining-legacy-layout-cleanup` | PASS | Branch created from PR014. |
+| Inspect `assets/` | PASS | 0 tracked files; local ignored `DemoGame-26168-001.gfsp` remains untouched. |
+| Inspect `games/` | PASS | 0 tracked files; empty local-only directory shell. |
+| Inspect `learn/` | PASS | 0 tracked files; empty local-only directory shell. |
+| Inspect `src/` | PASS | 596 tracked files; active transition namespace retained. |
+| Inspect `test-results/` | PASS | Folder absent; 0 tracked files. |
+| Inspect `tmp/` | PASS | 0 tracked files; empty local-only directory shell; not used for Codex output. |
+| Inspect `toolbox/` | PASS | 0 tracked files; empty local-only directory shell. |
+| Remove empty tracked placeholder folders only if safe | PASS | No tracked placeholder folders found in the named root leftovers. |
+| Do not delete untracked local-only folders unless explicitly safe and documented | PASS | No untracked local-only folders were deleted. |
+| Do not move `src/` in this PR unless clearly misplaced and low-risk | PASS | `src/` was not moved. |
+| Produce a clear `src/` transition plan | PASS | Included in PR report. |
+| Confirm `.env` remains root/local-only | PASS | `.env` is ignored; `.env.example` is tracked. |
+| Confirm `www/favicon.svg` remains browser-served favicon | PASS | `www/favicon.svg` is tracked. |
+| No runtime behavior changes | PASS | Reports/governance only. |
+| No product feature changes | PASS | Reports/governance only. |

dev/reports/PR_26180_OWNER_015-root-empty-folder-and-src-transition-audit_validation-report.md

@@ -0,0 +1,15 @@
+# PR_26180_OWNER_015 Validation Report
+
+| Validation | Result | Notes |
+|---|---:|---|
+| Root folder audit | PASS | Named folders classified by local existence, tracked content, ignored/generated status, and follow-up need. |
+| `.env` policy confirmation | PASS | `.env` is ignored by `.gitignore`; `.env.example` is tracked. |
+| `www/favicon.svg` confirmation | PASS | `www/favicon.svg` is tracked. |
+| Targeted root legacy path scan | PASS | No tracked `assets/`, `games/`, `learn/`, `test-results/`, `tmp/`, or `toolbox/` files remain. |
+| `node --test dev/tests/dev-runtime/TeamAwareBootstrap.test.mjs` | PASS | Bootstrap command surface remains valid. |
+| `git diff --check` | PASS | Whitespace check passed. |
+| `npm run validate:canonical-structure` | PASS | Blocking violations: 0. |
+
+## Notes
+
+The bootstrap test was run as a targeted safety check even though this PR does not touch startup/runtime files.