Combine the remaining Section-6 Samples Program work into one low-PR pass

BUILD_PR_LEVEL_06_SAMPLES_PROGRAM_COMBINED_PASS

Author: DavidQ

docs/dev/CODEX_COMMANDS.md

@@ -2,26 +2,28 @@ MODEL: GPT-5.4
 REASONING: high
 
 COMMAND:
-Create `BUILD_PR_LEVEL_04_STATE_REPLAY_TIMELINE_COMBINED_PASS` as one combined Section-4 PR.
+Create `BUILD_PR_LEVEL_06_SAMPLES_PROGRAM_COMBINED_PASS` as one combined Section-6 PR.
 
 Goal:
-Finish as much of State, Replay, Timeline, and Authoritative Flow as truthfully possible in one pass.
+Finish as much of the Samples Program lane as truthfully possible in one pass.
 
 Target items to close in this PR if supported:
-- replay/timeline boundaries normalized
-- state contracts extracted/confirmed
-- replay model
-- timeline orchestration
-- authoritative state slices
+- phase grouping normalized
+- `samples/shared` boundaries defined and used
+- sample-to-engine dependency cleanup completed
+- sample curriculum progression validated
 
 Required work:
-1. Treat the remaining open Section-4 items as one coherent state-flow lane.
-2. Complete/confirm the state contracts needed to support replay and timeline work.
-3. Normalize replay model and timeline orchestration together.
-4. Normalize replay/timeline boundaries as part of that same pass.
-5. Close any remaining authoritative-state-slice residue truthfully without reopening already-stable work.
-6. Reuse the already-established authoritative/passive, promotion-gate, selector, and rollback work instead of redoing it.
-7. Close as many Section-4 items as truthfully possible in this one PR.
+1. Treat the remaining open Section-6 items as one coherent lane.
+2. Complete phase grouping normalization where still incomplete.
+3. Define and apply `samples/shared` boundaries:
+   - what belongs in `samples/shared`
+   - what stays sample-owned
+   - what must not leak into engine/shared incorrectly
+4. Clean up sample-to-engine dependencies truthfully and surgically.
+5. Validate curriculum progression after grouping/boundary cleanup.
+6. Reuse established numbering/formatting/index work instead of redoing it.
+7. Close as many Section-6 items as truthfully possible in this one PR.
 8. If anything remains open:
    - keep the residue very small
    - report exact blockers
@@ -33,7 +35,7 @@ Roadmap:
 
 Final packaging step is REQUIRED:
 - package ALL changed files into this exact repo-structured ZIP:
-  `<project folder>/tmp/BUILD_PR_LEVEL_04_STATE_REPLAY_TIMELINE_COMBINED_PASS.zip`
+  `<project folder>/tmp/BUILD_PR_LEVEL_06_SAMPLES_PROGRAM_COMBINED_PASS.zip`
 
 Hard rules:
 - combine aggressively to reduce PR count

docs/dev/COMMIT_COMMENT.txt

@@ -1,2 +1,2 @@
-Combine the remaining Section-4 state/replay/timeline work into one low-PR pass
-BUILD_PR_LEVEL_04_STATE_REPLAY_TIMELINE_COMBINED_PASS
+Combine the remaining Section-6 Samples Program work into one low-PR pass
+BUILD_PR_LEVEL_06_SAMPLES_PROGRAM_COMBINED_PASS

docs/dev/NEXT_COMMAND.txt

@@ -1 +1 @@
-BUILD_PR_LEVEL_04_STATE_REPLAY_TIMELINE_RESIDUE_ONLY
+BUILD_PR_LEVEL_06_SAMPLES_PROGRAM_RESIDUE_ONLY

docs/dev/reports/change_summary.txt

@@ -1,3 +1,3 @@
-- Added a combined PR for the remaining Section-4 state/replay/timeline lane
-- Bundles contracts, replay model, timeline orchestration, authoritative slices, and boundary normalization
-- Intended to finish most or all of Section 4 in one pass and leave only tiny residue if needed
+- Added a combined PR for the remaining Section-6 Samples Program lane
+- Bundles phase grouping, samples/shared boundaries, dependency cleanup, and curriculum validation
+- Intended to finish most or all of Section 6 in one pass and leave only tiny residue if needed

docs/dev/reports/validation_checklist.txt

@@ -1,9 +1,8 @@
-- replay/timeline boundaries addressed
-- state contracts addressed
-- replay model addressed
-- timeline orchestration addressed
-- authoritative state slices addressed
+- phase grouping addressed
+- samples/shared boundaries addressed
+- sample-to-engine dependency cleanup addressed
+- sample curriculum progression addressed
 - any residue is explicit and minimal
 - roadmap updated by status markers only
 - output ZIP created at:
-  <project folder>/tmp/BUILD_PR_LEVEL_04_STATE_REPLAY_TIMELINE_COMBINED_PASS.zip
+  <project folder>/tmp/BUILD_PR_LEVEL_06_SAMPLES_PROGRAM_COMBINED_PASS.zip

docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md

@@ -310,12 +310,12 @@
 ## 6. Samples Program
 - [x] sample numbering normalization completed
 - [x] sample formatting alignment completed
-- [.] phase grouping normalized
-- [ ] `samples/shared` boundaries defined and used
+- [x] phase grouping normalized
+- [x] `samples/shared` boundaries defined and used
 - [x] sample index normalized to phase structure
-- [ ] sample-to-engine dependency cleanup completed
+- [x] sample-to-engine dependency cleanup completed
 - [x] sample duplicate helper usage reduced
-- [.] sample curriculum progression validated
+- [x] sample curriculum progression validated
 
 ### Sample Phase Tracks
 - [ ] foundational phases normalized

docs/pr/BUILD_PR_LEVEL_06_SAMPLES_PROGRAM_COMBINED_PASS.md

@@ -0,0 +1,60 @@
+# BUILD_PR_LEVEL_06_SAMPLES_PROGRAM_COMBINED_PASS
+
+## Purpose
+Complete the remaining Section-6 Samples Program lane in one coherent pass by finalizing phase grouping checks, normalizing the `samples/shared` boundary, confirming sample-to-engine boundary cleanup, and validating curriculum progression.
+
+## Scope Implemented
+- normalized the shared-sample boundary so `samples/shared` is canonical for reusable sample helpers
+- converted `samples/_shared` JS/CSS surfaces into compatibility shims that proxy to `samples/shared`
+- added explicit `samples/shared` boundary documentation
+- added focused Section-6 validation coverage for phase grouping, shared-boundary usage, dependency boundaries, and curriculum progression
+- updated Section-6 roadmap status markers only
+
+## Boundary Decisions Applied
+- canonical shared sample surface: `samples/shared`
+- compatibility-only surface: `samples/_shared` (shims forwarding to `samples/shared`)
+- sample-to-engine rule source: `samples/metadata/samples.shared.boundaries.report.json` (`engineBoundaryViolations: 0`)
+- curriculum validation source: `samples/metadata/samples.curriculum.validation.json` + `samples/metadata/samples.index.metadata.json`
+
+## Section-6 Status Outcome
+Closed in this PR:
+- phase grouping normalized
+- `samples/shared` boundaries defined and used
+- sample-to-engine dependency cleanup completed
+- sample curriculum progression validated
+
+Remaining Section-6 residue:
+- phase-track and dependency-driven build checklist items remain open as separate deeper-track work
+
+## Validation Performed
+- node parse checks on touched JS/MJS files
+- focused run:
+  - `tests/samples/SamplesProgramCombinedPass.test.mjs`
+
+Validation assertions include:
+- canonical phase directories (`phase-01` through `phase-15`) exist and sample IDs align to owning phase
+- canonical `samples/shared` files exist and `_shared` shims proxy to `samples/shared`
+- sample-engine boundary report still shows zero engine boundary violations
+- curriculum progression metadata remains ordered and consistent with sample index metadata
+
+## Changed Files
+- `samples/shared/README.md`
+- `samples/shared/debugConfigUtils.js`
+- `samples/shared/lateSampleBootstrap.js`
+- `samples/shared/networkDebugUtils.js`
+- `samples/shared/numberUtils.js`
+- `samples/shared/platformerHelpers.js`
+- `samples/shared/sampleBaseLayout.css`
+- `samples/shared/sampleDetailPageEnhancement.js`
+- `samples/shared/snapshotCloneUtils.js`
+- `samples/_shared/debugConfigUtils.js`
+- `samples/_shared/lateSampleBootstrap.js`
+- `samples/_shared/networkDebugUtils.js`
+- `samples/_shared/numberUtils.js`
+- `samples/_shared/platformerHelpers.js`
+- `samples/_shared/sampleBaseLayout.css`
+- `samples/_shared/sampleDetailPageEnhancement.js`
+- `samples/_shared/snapshotCloneUtils.js`
+- `tests/samples/SamplesProgramCombinedPass.test.mjs`
+- `tests/run-tests.mjs`
+- `docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md`

samples/_shared/debugConfigUtils.js

@@ -1 +1 @@
-export { resolveDebugConfig } from "../../src/shared/utils/debugConfigUtils.js";
+export * from "../shared/debugConfigUtils.js";

samples/_shared/lateSampleBootstrap.js

@@ -1,57 +1 @@
-/*
-Toolbox Aid
-David Quesenberry
-03/23/2026
-lateSampleBootstrap.js
-*/
-import Engine from '/src/engine/core/Engine.js';
-import { Theme, ThemeTokens } from '/src/engine/theme/index.js';
-
-const DEFAULT_WIDTH = 960;
-const DEFAULT_HEIGHT = 540;
-
-export function bootLateSample({
-  SceneClass = null,
-  sceneFactory = null,
-  controls = [],
-  canvasId = 'game',
-  width = DEFAULT_WIDTH,
-  height = DEFAULT_HEIGHT,
-  engineOptions = {},
-} = {}) {
-  const theme = new Theme(ThemeTokens);
-  theme.applyDocumentTheme();
-
-  const canvas = document.getElementById(canvasId);
-  if (!canvas) {
-    throw new Error(`Late sample bootstrap requires a canvas with id "${canvasId}".`);
-  }
-
-  const engine = new Engine({
-    canvas,
-    width,
-    height,
-    ...engineOptions,
-  });
-
-  const scene = typeof sceneFactory === 'function'
-    ? sceneFactory({ engine, canvas })
-    : SceneClass
-      ? new SceneClass()
-      : null;
-
-  if (!scene) {
-    throw new Error('Late sample bootstrap requires a SceneClass or sceneFactory.');
-  }
-
-  engine.setScene(scene);
-  engine.start();
-
-  controls.forEach(({ id, eventName = 'click', action }) => {
-    document.getElementById(id)?.addEventListener(eventName, (event) => {
-      action?.({ event, scene, engine, canvas });
-    });
-  });
-
-  return { scene, engine, canvas };
-}
+export * from "../shared/lateSampleBootstrap.js";

samples/_shared/networkDebugUtils.js

@@ -1,6 +1 @@
-export {
-  asNumber,
-  commandLinesForTrace,
-  getCommandSnapshot,
-  toNetworkSnapshot
-} from "../../src/shared/utils/networkDebugUtils.js";
+export * from "../shared/networkDebugUtils.js";