PR_26172_CHARLIE_035-game-journey-api-client-migration-or-exception

Author: ToolboxAid

docs_build/dev/reports/PR_26172_CHARLIE_035-game-journey-api-client-migration-or-exception.md

@@ -0,0 +1,90 @@
+# PR_26172_CHARLIE_035-game-journey-api-client-migration-or-exception
+
+## Summary
+
+Status: PASS with temporary legacy exception retained.
+
+No executable implementation files were changed in this PR. The remaining Game Journey API client was reviewed after the PR_034 entrypoint migration:
+
+- `toolbox/game-journey/game-journey-api-client.js`
+
+The file remains in its approved legacy location because moving it into `assets/toolbox/game-journey/js/` would create a second canonical tool JS file that the current guardrail does not allow.
+
+## Files Reviewed
+
+- `docs_build/dev/ProjectInstructions/README.txt`
+- `docs_build/dev/ProjectInstructions/PROJECT_INSTRUCTIONS.md`
+- `docs_build/dev/reports/PR_26172_CHARLIE_033-game-journey-canonical-js-migration-audit.md`
+- `docs_build/dev/reports/PR_26172_CHARLIE_034-game-journey-safe-entrypoint-migration.md`
+- `assets/toolbox/game-journey/js/index.js`
+- `toolbox/game-journey/game-journey-api-client.js`
+- `toolbox/game-journey/index.html`
+- `tests/playwright/tools/GameJourneyTool.spec.mjs`
+- `scripts/validate-canonical-repository-structure.mjs`
+- `scripts/validate-browser-env-agnostic.mjs`
+
+## Decision
+
+Decision: retain `toolbox/game-journey/game-journey-api-client.js` as a temporary legacy exception.
+
+Reason:
+
+- The current canonical guardrail approves the tool entrypoint path `assets/toolbox/{tool-name}/js/index.js`.
+- It does not approve an additional tool-local API client file under `assets/toolbox/game-journey/js/`.
+- Folding the API client into `index.js` would be a larger refactor and could obscure the completion-metrics API boundary.
+- The API client re-exports completion metrics helpers from `src/api/game-journey-completion-api-client.js`, so it should stay isolated until the shared-client/secondary-file rule is explicit.
+
+Removal plan:
+
+1. Add or clarify a canonical rule for tool-local secondary modules, or approve a shared API-client location.
+2. Move the API client only after the guardrail recognizes the destination.
+3. Update the canonical Game Journey entrypoint import.
+4. Re-run Game Journey route validation and completion-metrics validation.
+5. Remove `toolbox/game-journey/game-journey-api-client.js` from approved legacy exceptions after validation passes.
+
+## Validation Lane Report
+
+- `node --check toolbox/game-journey/game-journey-api-client.js`
+  - Result: PASS
+- `npm run validate:canonical-structure`
+  - Result: PASS
+  - Blocking violations: 0
+  - Approved legacy exceptions: 481
+- Active reference check
+  - Result: PASS
+  - The canonical entrypoint imports `toolbox/game-journey/game-journey-api-client.js`.
+  - Guardrail and hardening tests still list the retained exception.
+  - Historical `docs_build/pr` references to old `game-journey.js` remain unchanged.
+- Targeted Game Journey Playwright validation:
+  - Command: `npx playwright test tests/playwright/tools/GameJourneyTool.spec.mjs --grep "Game Journey summary table uses inline notes" --workers=1 --reporter=line --timeout=90000`
+  - Result: PASS
+
+## Completion Metrics Note
+
+The targeted validation used the existing test Postgres completion-metrics stub and passed. The local legacy SQLite preservation blocker documented in PR_26172_CHARLIE_006A remains a separate recovery/data-preservation concern, not a reason to move the API client in this PR.
+
+## Branch Validation
+
+- Current branch: `PR_26172_CHARLIE_repository-compliance-stack`
+- Expected branch: `PR_26172_CHARLIE_repository-compliance-stack`
+- Local/origin sync before PR: `0 0`
+- Branch validation: PASS
+
+## Requirement Checklist
+
+- Use PR_033 and PR_034 results: PASS
+- Move API client if safe: PASS, not safe under current guardrail.
+- Retain API client and document temporary legacy exception if not safe: PASS
+- Preserve behavior: PASS
+- No feature changes: PASS
+- Run targeted Game Journey validation: PASS
+- Run canonical structure guardrail: PASS
+- Confirm ZIP exists: PASS after artifact creation.
+
+## Manual Validation Notes
+
+The canonical Game Journey entrypoint is already active. Keeping the API client in the existing legacy path avoids introducing an unapproved secondary JS file pattern and avoids changing completion-metrics behavior.
+
+## Recommendation
+
+Continue to PR_036 final target-tool compliance reaudit. Treat `toolbox/game-journey/game-journey-api-client.js` as a retained exception with a defined removal plan.

docs_build/dev/reports/codex_changed_files.txt

@@ -1,5 +1 @@
-R099	toolbox/game-journey/game-journey.js	assets/toolbox/game-journey/js/index.js
-A	docs_build/dev/reports/PR_26172_CHARLIE_034-game-journey-safe-entrypoint-migration.md
-M	scripts/validate-canonical-repository-structure.mjs
-M	tests/playwright/tools/GameJourneyTool.spec.mjs
-M	toolbox/game-journey/index.html
+A	docs_build/dev/reports/PR_26172_CHARLIE_035-game-journey-api-client-migration-or-exception.md

docs_build/dev/reports/codex_review.diff

@@ -1,99 +1,73 @@
-diff --git a/toolbox/game-journey/game-journey.js b/assets/toolbox/game-journey/js/index.js
-similarity index 99%
-rename from toolbox/game-journey/game-journey.js
-rename to assets/toolbox/game-journey/js/index.js
-index c2b2f876c..0ebc4f2ca 100644
---- a/toolbox/game-journey/game-journey.js
-+++ b/assets/toolbox/game-journey/js/index.js
-@@ -6,11 +6,11 @@ import {
-   GAME_JOURNEY_SUGGESTED_TOOLS,
-   createGameJourneyApiRepository,
-   readGameJourneyCompletionMetrics,
--} from "./game-journey-api-client.js";
-+} from "../../../../toolbox/game-journey/game-journey-api-client.js";
- import {
-   getActiveToolRegistry,
-   getToolRegistryApiDiagnostic,
--} from "../tool-registry-api-client.js";
-+} from "../../../../toolbox/tool-registry-api-client.js";
-
- const repository = createGameJourneyApiRepository();
- const registryDiagnostic = getToolRegistryApiDiagnostic();
-diff --git a/docs_build/dev/reports/PR_26172_CHARLIE_034-game-journey-safe-entrypoint-migration.md b/docs_build/dev/reports/PR_26172_CHARLIE_034-game-journey-safe-entrypoint-migration.md
+diff --git a/docs_build/dev/reports/PR_26172_CHARLIE_035-game-journey-api-client-migration-or-exception.md b/docs_build/dev/reports/PR_26172_CHARLIE_035-game-journey-api-client-migration-or-exception.md
 new file mode 100644
-index 000000000..c03cd09f5
+index 000000000..d0f945e60
 --- /dev/null
-+++ b/docs_build/dev/reports/PR_26172_CHARLIE_034-game-journey-safe-entrypoint-migration.md
-@@ -0,0 +1,98 @@
-+# PR_26172_CHARLIE_034-game-journey-safe-entrypoint-migration
++++ b/docs_build/dev/reports/PR_26172_CHARLIE_035-game-journey-api-client-migration-or-exception.md
+@@ -0,0 +1,90 @@
++# PR_26172_CHARLIE_035-game-journey-api-client-migration-or-exception
 +
 +## Summary
 +
-+Status: PASS.
++Status: PASS with temporary legacy exception retained.
 +
-+The Game Journey browser entrypoint was moved from the active legacy toolbox path to the canonical tool asset path:
++No executable implementation files were changed in this PR. The remaining Game Journey API client was reviewed after the PR_034 entrypoint migration:
 +
-+- From: `toolbox/game-journey/game-journey.js`
-+- To: `assets/toolbox/game-journey/js/index.js`
++- `toolbox/game-journey/game-journey-api-client.js`
 +
-+The Game Journey API client was retained for PR_035 review.
++The file remains in its approved legacy location because moving it into `assets/toolbox/game-journey/js/` would create a second canonical tool JS file that the current guardrail does not allow.
 +
 +## Files Reviewed
 +
 +- `docs_build/dev/ProjectInstructions/README.txt`
 +- `docs_build/dev/ProjectInstructions/PROJECT_INSTRUCTIONS.md`
 +- `docs_build/dev/reports/PR_26172_CHARLIE_033-game-journey-canonical-js-migration-audit.md`
-+- `toolbox/game-journey/index.html`
-+- `toolbox/game-journey/game-journey.js`
++- `docs_build/dev/reports/PR_26172_CHARLIE_034-game-journey-safe-entrypoint-migration.md`
++- `assets/toolbox/game-journey/js/index.js`
 +- `toolbox/game-journey/game-journey-api-client.js`
++- `toolbox/game-journey/index.html`
 +- `tests/playwright/tools/GameJourneyTool.spec.mjs`
 +- `scripts/validate-canonical-repository-structure.mjs`
++- `scripts/validate-browser-env-agnostic.mjs`
 +
-+## Files Changed
++## Decision
 +
-+- `assets/toolbox/game-journey/js/index.js`
-+- `toolbox/game-journey/index.html`
-+- `scripts/validate-canonical-repository-structure.mjs`
-+- `tests/playwright/tools/GameJourneyTool.spec.mjs`
-+- `docs_build/dev/reports/PR_26172_CHARLIE_034-game-journey-safe-entrypoint-migration.md`
-+- `docs_build/dev/reports/codex_review.diff`
-+- `docs_build/dev/reports/codex_changed_files.txt`
++Decision: retain `toolbox/game-journey/game-journey-api-client.js` as a temporary legacy exception.
 +
-+## Migration Notes
++Reason:
 +
-+- Updated the Game Journey page module script to load `assets/toolbox/game-journey/js/index.js`.
-+- Updated the moved module imports to continue using:
-+  - `toolbox/game-journey/game-journey-api-client.js`
-+  - `toolbox/tool-registry-api-client.js`
-+- Removed `toolbox/game-journey/game-journey.js` from the approved legacy JS exception list.
-+- Updated the Game Journey source separation test to read the canonical entrypoint path.
++- The current canonical guardrail approves the tool entrypoint path `assets/toolbox/{tool-name}/js/index.js`.
++- It does not approve an additional tool-local API client file under `assets/toolbox/game-journey/js/`.
++- Folding the API client into `index.js` would be a larger refactor and could obscure the completion-metrics API boundary.
++- The API client re-exports completion metrics helpers from `src/api/game-journey-completion-api-client.js`, so it should stay isolated until the shared-client/secondary-file rule is explicit.
 +
-+## Retained Exception
++Removal plan:
 +
-+- `toolbox/game-journey/game-journey-api-client.js`
-+  - Reason: reviewed separately in PR_035.
-+  - Risk: the canonical guardrail currently approves the tool `index.js` entrypoint path but does not approve additional tool JS files under the same folder.
++1. Add or clarify a canonical rule for tool-local secondary modules, or approve a shared API-client location.
++2. Move the API client only after the guardrail recognizes the destination.
++3. Update the canonical Game Journey entrypoint import.
++4. Re-run Game Journey route validation and completion-metrics validation.
++5. Remove `toolbox/game-journey/game-journey-api-client.js` from approved legacy exceptions after validation passes.
 +
 +## Validation Lane Report
 +
-+- `node --check assets/toolbox/game-journey/js/index.js`
-+  - Result: PASS
-+- `git diff --check`
++- `node --check toolbox/game-journey/game-journey-api-client.js`
 +  - Result: PASS
 +- `npm run validate:canonical-structure`
 +  - Result: PASS
 +  - Blocking violations: 0
 +  - Approved legacy exceptions: 481
-+- Active stale reference check for `toolbox/game-journey/game-journey.js`
++- Active reference check
 +  - Result: PASS
-+  - Only historical `docs_build/pr` references remain.
++  - The canonical entrypoint imports `toolbox/game-journey/game-journey-api-client.js`.
++  - Guardrail and hardening tests still list the retained exception.
++  - Historical `docs_build/pr` references to old `game-journey.js` remain unchanged.
 +- Targeted Game Journey Playwright validation:
 +  - Command: `npx playwright test tests/playwright/tools/GameJourneyTool.spec.mjs --grep "Game Journey summary table uses inline notes" --workers=1 --reporter=line --timeout=90000`
 +  - Result: PASS
 +
 +## Completion Metrics Note
 +
-+The targeted Playwright route test uses the existing Postgres completion-metrics stub and passed. The known local legacy SQLite preservation failure documented in PR_26172_CHARLIE_006A did not appear in this validation lane.
++The targeted validation used the existing test Postgres completion-metrics stub and passed. The local legacy SQLite preservation blocker documented in PR_26172_CHARLIE_006A remains a separate recovery/data-preservation concern, not a reason to move the API client in this PR.
 +
 +## Branch Validation
 +
@@ -104,60 +78,19 @@ index 000000000..c03cd09f5
 +
 +## Requirement Checklist
 +
-+- Use PR_033 audit: PASS
-+- Move only `game-journey.js` to canonical path: PASS
-+- Update `toolbox/game-journey/index.html`: PASS
-+- Update tests/references for old path: PASS
++- Use PR_033 and PR_034 results: PASS
++- Move API client if safe: PASS, not safe under current guardrail.
++- Retain API client and document temporary legacy exception if not safe: PASS
 +- Preserve behavior: PASS
-+- Do not move API client unless PR_033 proves safe: PASS, retained.
 +- No feature changes: PASS
 +- Run targeted Game Journey validation: PASS
 +- Run canonical structure guardrail: PASS
-+- Document known SQLite preservation blocker separately if encountered: PASS, not encountered.
 +- Confirm ZIP exists: PASS after artifact creation.
 +
 +## Manual Validation Notes
 +
-+The entrypoint migration is isolated and validated. The retained API client should be resolved in PR_035 without changing completion-metrics behavior.
++The canonical Game Journey entrypoint is already active. Keeping the API client in the existing legacy path avoids introducing an unapproved secondary JS file pattern and avoids changing completion-metrics behavior.
 +
 +## Recommendation
 +
-+Continue to PR_035 and keep `toolbox/game-journey/game-journey-api-client.js` as an exception unless a safe guardrail-compliant placement is available.
-diff --git a/scripts/validate-canonical-repository-structure.mjs b/scripts/validate-canonical-repository-structure.mjs
-index 62ef269c2..ef3cfd8db 100644
---- a/scripts/validate-canonical-repository-structure.mjs
-+++ b/scripts/validate-canonical-repository-structure.mjs
-@@ -12,7 +12,6 @@ export const APPROVED_LEGACY_JS_PATHS = Object.freeze(new Set([
-   "toolbox/game-hub/game-hub-api-client.js",
-   "toolbox/game-hub/game-hub.js",
-   "toolbox/game-journey/game-journey-api-client.js",
--  "toolbox/game-journey/game-journey.js",
-   "toolbox/messages/message-tts-service-registry.js",
-   "toolbox/messages/messages-api-client.js",
-   "toolbox/messages/messages.js",
-diff --git a/tests/playwright/tools/GameJourneyTool.spec.mjs b/tests/playwright/tools/GameJourneyTool.spec.mjs
-index 390d1cc89..4d8f05378 100644
---- a/tests/playwright/tools/GameJourneyTool.spec.mjs
-+++ b/tests/playwright/tools/GameJourneyTool.spec.mjs
-@@ -1531,7 +1531,7 @@ test("Toolbox registration exposes Game Journey navigation", async ({ page }) =>
- test("Game Journey source stays separate from notes files and browser persistence", async () => {
-   const sourcePaths = [
-     "toolbox/game-journey/index.html",
--    "toolbox/game-journey/game-journey.js",
-+    "assets/toolbox/game-journey/js/index.js",
-     "src/dev-runtime/persistence/tool-repositories/game-journey-mock-repository.js"
-   ];
-   const banned = [
-diff --git a/toolbox/game-journey/index.html b/toolbox/game-journey/index.html
-index aa1a408aa..2965e2b19 100644
---- a/toolbox/game-journey/index.html
-+++ b/toolbox/game-journey/index.html
-@@ -195,7 +195,7 @@
-     <div data-partial="footer"></div>
-     <script src="assets/theme-v2/js/gamefoundry-partials.js"></script>
-     <script src="assets/theme-v2/js/tool-display-mode.js"></script>
--    <script type="module" src="toolbox/game-journey/game-journey.js"></script>
-+    <script type="module" src="assets/toolbox/game-journey/js/index.js"></script>
- </body>
-
- </html>
++Continue to PR_036 final target-tool compliance reaudit. Treat `toolbox/game-journey/game-journey-api-client.js` as a retained exception with a defined removal plan.