|
| 1 | +# PR_26172_CHARLIE_001 Repository Compliance Audit |
| 2 | + |
| 3 | +## Scope |
| 4 | + |
| 5 | +Audit repository compliance against: |
| 6 | + |
| 7 | +- PR_034 Canonical Repository Structure |
| 8 | +- PR_035 Test Structure Standardization |
| 9 | +- PR_036 Legacy Migration Policy |
| 10 | + |
| 11 | +Reviewed areas: |
| 12 | + |
| 13 | +- `toolbox/` |
| 14 | +- `assets/` |
| 15 | +- `tests/` |
| 16 | +- `api/` |
| 17 | +- `serverside/` |
| 18 | +- `src/engine/` |
| 19 | + |
| 20 | +This PR is audit-only. No executable implementation changes were made. |
| 21 | + |
| 22 | +## Team Ownership |
| 23 | + |
| 24 | +- TEAM token: CHARLIE |
| 25 | +- Ownership classification: governance / repository compliance / diagnostics |
| 26 | +- TEAM ownership result: PASS |
| 27 | + |
| 28 | +## Branch Validation |
| 29 | + |
| 30 | +| Requirement | Status | Evidence | |
| 31 | +| --- | --- | --- | |
| 32 | +| Started from latest main | PASS | `main` was pulled before branch creation; source commit `c4a495f0aa8e32d499ca64555c4a3547e6fcb298`. | |
| 33 | +| Worktree clean before branch | PASS | `git status --short` returned no output before branch creation. | |
| 34 | +| Local/origin sync before branch | PASS | `git rev-list --left-right --count HEAD...origin/main` returned `0 0`. | |
| 35 | +| PR branch created from main | PASS | Branch `pr/26172-CHARLIE-001-repository-compliance-audit` was created from latest `main`. | |
| 36 | +| Runtime/source edits avoided | PASS | Planned changed files are reports only under `docs_build/dev/reports/`. | |
| 37 | + |
| 38 | +## Repository Area Results |
| 39 | + |
| 40 | +| Area | Status | Findings | |
| 41 | +| --- | --- | --- | |
| 42 | +| `toolbox/` | FAIL | Active tool JavaScript remains beside tool HTML entries instead of canonical `assets/toolbox/{tool-name}/js/index.js` or shared asset roots. | |
| 43 | +| `assets/` | PASS | No non-compliant JS or CSS files were found in `assets/`; scanned JS/CSS lives under `assets/theme-v2/`. | |
| 44 | +| `tests/` | FAIL | 494 files are in non-canonical top-level test locations outside `tests/toolbox/`, `tests/engine/`, `tests/api/`, `tests/server/`, `tests/js/shared/`, or `tests/regression/`. | |
| 45 | +| `api/` | FAIL | Canonical root is absent. No API files were found to classify, but the expected top-level API area is not physically present. | |
| 46 | +| `serverside/` | FAIL | Canonical root is absent. No serverside files were found to classify, but the expected top-level serverside area is not physically present. | |
| 47 | +| `src/engine/` | FAIL | Most engine JS is under feature folders, but `src/engine/paletteList.js` is a root-level JS file and `src/engine/ui/*.css` contains CSS outside canonical asset/theme roots. | |
| 48 | + |
| 49 | +## Non-Compliant JS Locations |
| 50 | + |
| 51 | +### `toolbox/` |
| 52 | + |
| 53 | +These active JavaScript files are outside the canonical tool asset structure: |
| 54 | + |
| 55 | +- `toolbox/assets/assets-api-client.js` |
| 56 | +- `toolbox/assets/assets-upload-worker.js` |
| 57 | +- `toolbox/assets/assets.js` |
| 58 | +- `toolbox/colors/colors.js` |
| 59 | +- `toolbox/colors/palette-api-client.js` |
| 60 | +- `toolbox/controls/controls-api-client.js` |
| 61 | +- `toolbox/controls/controls.js` |
| 62 | +- `toolbox/game-configuration/game-configuration-api-client.js` |
| 63 | +- `toolbox/game-configuration/game-configuration.js` |
| 64 | +- `toolbox/game-design/game-design-api-client.js` |
| 65 | +- `toolbox/game-design/game-design.js` |
| 66 | +- `toolbox/game-hub/game-hub-api-client.js` |
| 67 | +- `toolbox/game-hub/game-hub.js` |
| 68 | +- `toolbox/game-journey/game-journey-api-client.js` |
| 69 | +- `toolbox/game-journey/game-journey.js` |
| 70 | +- `toolbox/idea-board/index.js` |
| 71 | +- `toolbox/messages/message-tts-service-registry.js` |
| 72 | +- `toolbox/messages/messages-api-client.js` |
| 73 | +- `toolbox/messages/messages.js` |
| 74 | +- `toolbox/objects/objects-api-client.js` |
| 75 | +- `toolbox/objects/objects.js` |
| 76 | +- `toolbox/tags/tags-api-client.js` |
| 77 | +- `toolbox/tags/tags.js` |
| 78 | +- `toolbox/text-to-speech/text2speech.js` |
| 79 | +- `toolbox/tool-registry-api-client.js` |
| 80 | +- `toolbox/toolRegistry.js` |
| 81 | +- `toolbox/tools-page-accordions.js` |
| 82 | + |
| 83 | +Recommended target pattern: |
| 84 | + |
| 85 | +- Tool-specific JS: `assets/toolbox/{tool-name}/js/index.js` |
| 86 | +- Shared toolbox JS: `assets/js/shared/` |
| 87 | + |
| 88 | +### `src/engine/` |
| 89 | + |
| 90 | +- `src/engine/paletteList.js` |
| 91 | + |
| 92 | +Recommended target pattern: |
| 93 | + |
| 94 | +- Move under a feature folder such as `src/engine/palette/` after import-impact review. |
| 95 | + |
| 96 | +## Non-Compliant CSS Locations |
| 97 | + |
| 98 | +### `toolbox/` |
| 99 | + |
| 100 | +- None found. |
| 101 | + |
| 102 | +### `assets/` |
| 103 | + |
| 104 | +- None found. |
| 105 | + |
| 106 | +### `src/engine/` |
| 107 | + |
| 108 | +These CSS files are active style assets under engine source: |
| 109 | + |
| 110 | +- `src/engine/ui/baseLayout.css` |
| 111 | +- `src/engine/ui/hubCommon.css` |
| 112 | +- `src/engine/ui/spriteEditor.css` |
| 113 | + |
| 114 | +Recommended target pattern: |
| 115 | + |
| 116 | +- Move shared UI/theme styling into `assets/theme-v2/css/` or create an approved engine UI style policy before relocation. |
| 117 | + |
| 118 | +## Non-Compliant Test Locations |
| 119 | + |
| 120 | +Canonical test roots from PR_035: |
| 121 | + |
| 122 | +- `tests/toolbox/{tool-name}/` |
| 123 | +- `tests/engine/{feature-name}/` |
| 124 | +- `tests/api/{feature-name}/` |
| 125 | +- `tests/server/{feature-name}/` |
| 126 | +- `tests/js/shared/` |
| 127 | +- `tests/regression/` |
| 128 | + |
| 129 | +The audit found 494 files in non-canonical test locations: |
| 130 | + |
| 131 | +| Path | File Count | Examples | |
| 132 | +| --- | ---: | --- | |
| 133 | +| `tests/ai/` | 1 | `tests/ai/AIBehaviors.test.mjs` | |
| 134 | +| `tests/assets/` | 1 | `tests/assets/AssetLoaderSystem.test.mjs` | |
| 135 | +| `tests/audio/` | 1 | `tests/audio/AudioService.test.mjs` | |
| 136 | +| `tests/combat/` | 1 | `tests/combat/Combat.test.mjs` | |
| 137 | +| `tests/config/` | 1 | `tests/config/ConfigStore.test.mjs` | |
| 138 | +| `tests/core/` | 11 | `tests/core/EngineCoreBoundaryBaseline.test.mjs` | |
| 139 | +| `tests/dev-runtime/` | 31 | `tests/dev-runtime/AdminHealthOperations.test.mjs` | |
| 140 | +| `tests/entity/` | 1 | `tests/entity/Entity.test.mjs` | |
| 141 | +| `tests/events/` | 2 | `tests/events/EventBus.test.mjs` | |
| 142 | +| `tests/final/` | 11 | `tests/final/ReleaseReadinessSystems.test.mjs` | |
| 143 | +| `tests/fixtures/` | 52 | `tests/fixtures/assets/asset-scenarios.json` | |
| 144 | +| `tests/fx/` | 1 | `tests/fx/ParticleSystem.test.mjs` | |
| 145 | +| `tests/games/` | 35 | `tests/games/AsteroidsValidation.test.mjs` | |
| 146 | +| `tests/helpers/` | 11 | `tests/helpers/playwrightRepoServer.mjs` | |
| 147 | +| `tests/index.html` | 1 | `tests/index.html` | |
| 148 | +| `tests/input/` | 8 | `tests/input/InputService.test.mjs` | |
| 149 | +| `tests/persistence/` | 1 | `tests/persistence/StorageService.test.mjs` | |
| 150 | +| `tests/playwright/` | 44 | `tests/playwright/tools/GameJourneyTool.spec.mjs` | |
| 151 | +| `tests/playwright_installation.txt` | 1 | `tests/playwright_installation.txt` | |
| 152 | +| `tests/production/` | 3 | `tests/production/ProductionReadiness.test.mjs` | |
| 153 | +| `tests/README.md` | 1 | `tests/README.md` | |
| 154 | +| `tests/render/` | 1 | `tests/render/Renderer.test.mjs` | |
| 155 | +| `tests/replay/` | 2 | `tests/replay/ReplaySystem.test.mjs` | |
| 156 | +| `tests/results/` | 26 | `tests/results/playwright-results.json` | |
| 157 | +| `tests/run-tests.mjs` | 1 | `tests/run-tests.mjs` | |
| 158 | +| `tests/runtime/` | 81 | `tests/runtime/V2SessionPersistence.test.mjs` | |
| 159 | +| `tests/samples/` | 1 | `tests/samples/FullscreenRuleEnforcement.test.mjs` | |
| 160 | +| `tests/scenes/` | 3 | `tests/scenes/SceneManager.test.mjs` | |
| 161 | +| `tests/schemas/` | 1 | `tests/schemas/tool.manifest.schema.json` | |
| 162 | +| `tests/shared/` | 92 | `tests/shared/ProjectContract.test.mjs` | |
| 163 | +| `tests/testRunner.html` | 1 | `tests/testRunner.html` | |
| 164 | +| `tests/testRunner.js` | 1 | `tests/testRunner.js` | |
| 165 | +| `tests/tools/` | 57 | `tests/tools/ToolBoundaryEnforcement.test.mjs` | |
| 166 | +| `tests/validation/` | 3 | `tests/validation/samples.runtime.validation.report.json` | |
| 167 | +| `tests/vector/` | 1 | `tests/vector/VectorMath.test.mjs` | |
| 168 | +| `tests/world/` | 4 | `tests/world/WorldSystems.test.mjs` | |
| 169 | + |
| 170 | +Generated Playwright result artifacts under `tests/results/` should be treated as cleanup/archive candidates rather than active test source. |
| 171 | + |
| 172 | +## Legacy Migration Candidates |
| 173 | + |
| 174 | +| Priority | Candidate | Reason | Recommended Handling | |
| 175 | +| --- | --- | --- | --- | |
| 176 | +| P0 | `tests/results/` | Generated result artifacts are tracked under active tests. | Move to ignored output or archive/report storage after owner approval. | |
| 177 | +| P1 | `toolbox/*/*.js` and shared `toolbox/*.js` | Active JS is colocated with HTML entries instead of canonical asset roots. | Migrate tool JS to `assets/toolbox/{tool-name}/js/index.js`; migrate shared JS to `assets/js/shared/`. | |
| 178 | +| P1 | `tests/dev-runtime/`, `tests/playwright/`, `tests/runtime/`, `tests/shared/`, `tests/tools/` | Large active test buckets conflict with PR_035 canonical test roots. | Split by ownership into `tests/toolbox/`, `tests/engine/`, `tests/api/`, `tests/server/`, `tests/js/shared/`, and `tests/regression/`. | |
| 179 | +| P2 | `src/engine/paletteList.js` | Root-level engine JS file is outside `src/engine/{feature-name}/`. | Move to an approved feature folder with import compatibility reviewed. | |
| 180 | +| P2 | `src/engine/ui/*.css` | CSS lives under engine source instead of theme/tool asset roots. | Move to `assets/theme-v2/css/` or define an explicit engine UI CSS policy. | |
| 181 | +| P3 | Missing `api/` and `serverside/` roots | Canonical target roots are absent. | Create roots when the first API/server migration needs them, with placeholder README only if governance permits. | |
| 182 | + |
| 183 | +## Prioritized Remediation List |
| 184 | + |
| 185 | +1. Remove or archive tracked generated artifacts under `tests/results/`. |
| 186 | +2. Create a staged migration plan for `toolbox/` JavaScript sidecars, starting with shared files (`toolRegistry.js`, `tool-registry-api-client.js`, `tools-page-accordions.js`). |
| 187 | +3. Standardize high-volume test buckets in phases: `tests/dev-runtime/`, `tests/playwright/`, `tests/runtime/`, `tests/shared/`, then `tests/tools/`. |
| 188 | +4. Move `src/engine/paletteList.js` into an engine feature folder after import-impact review. |
| 189 | +5. Resolve engine CSS placement for `src/engine/ui/*.css`. |
| 190 | +6. Add or defer canonical `api/` and `serverside/` roots with explicit owner-approved scope. |
| 191 | + |
| 192 | +## Recommended Next Charlie PRs |
| 193 | + |
| 194 | +- `PR_26172_CHARLIE_002-test-results-artifact-cleanup-plan` |
| 195 | +- `PR_26172_CHARLIE_003-toolbox-js-canonical-asset-migration-plan` |
| 196 | +- `PR_26172_CHARLIE_004-test-structure-standardization-plan` |
| 197 | +- `PR_26172_CHARLIE_005-engine-root-js-and-css-migration-plan` |
| 198 | +- `PR_26172_CHARLIE_006-api-serverside-root-readiness-plan` |
| 199 | + |
| 200 | +## Requirement Checklist |
| 201 | + |
| 202 | +| Requirement | Status | Evidence | |
| 203 | +| --- | --- | --- | |
| 204 | +| Follow ProjectInstructions | PASS | Read active `docs_build/dev/ProjectInstructions/` governance before work. | |
| 205 | +| Start from latest main | PASS | Main pulled and branch created from `c4a495f0aa8e32d499ca64555c4a3547e6fcb298`. | |
| 206 | +| Worktree clean before work | PASS | `git status --short` returned no output before edits. | |
| 207 | +| Audit PR_034 structure | PASS | Compared scoped paths to canonical toolbox, assets, engine, API, and serverside roots. | |
| 208 | +| Audit PR_035 tests | PASS | Compared `tests/` contents to canonical test roots. | |
| 209 | +| Audit PR_036 legacy migration policy | PASS | Classified migration candidates without moving or deleting files. | |
| 210 | +| Review `toolbox/` | PASS | Identified 27 non-compliant JS files. | |
| 211 | +| Review `assets/` | PASS | Found no non-compliant active JS/CSS in `assets/`. | |
| 212 | +| Review `tests/` | PASS | Identified 494 files in non-canonical test locations. | |
| 213 | +| Review `api/` | PASS | Directory absent; recorded as structural failure. | |
| 214 | +| Review `serverside/` | PASS | Directory absent; recorded as structural failure. | |
| 215 | +| Review `src/engine/` | PASS | Identified root JS and engine CSS placement issues. | |
| 216 | +| No executable implementation changes | PASS | Audit/report-only scope. | |
| 217 | +| Create audit report | PASS | This file. | |
| 218 | +| Create standard Codex reports | PASS | `docs_build/dev/reports/codex_review.diff` and `docs_build/dev/reports/codex_changed_files.txt` exist. | |
| 219 | +| Create ZIP artifact | PASS | `tmp/PR_26172_CHARLIE_001-repository-compliance-audit_delta.zip` exists. | |
| 220 | + |
| 221 | +## Validation Lane Report |
| 222 | + |
| 223 | +- `git diff --check`: PASS. |
| 224 | +- Report exists: PASS. |
| 225 | +- Required Codex reports exist: PASS. |
| 226 | +- ZIP artifact exists: PASS. |
| 227 | +- Runtime source files changed: PASS, changed files are limited to `docs_build/dev/reports/`. |
| 228 | +- Playwright: SKIP, audit-only documentation/report PR. |
| 229 | +- Samples: SKIP, audit-only documentation/report PR. |
| 230 | + |
| 231 | +## Manual Validation Notes |
| 232 | + |
| 233 | +- The audit intentionally did not move files, delete generated artifacts, create canonical roots, or modify executable source. |
| 234 | +- `api/` and `serverside/` were missing from the working tree; this was recorded as a structural finding, not remediated in this PR. |
| 235 | +- Non-canonical test locations were counted by top-level path under `tests/` to keep the report actionable without rewriting the test tree. |
| 236 | +- Tracked generated artifacts under `tests/results/` are listed as a high-priority cleanup candidate because they are active repository files but not active test source. |
0 commit comments