Skip to content

Commit 8a0da73

Browse files
author
DavidQ
committed
Baseline current /src/engine import usage and record the active engine import contract
1 parent 5b97133 commit 8a0da73

9 files changed

Lines changed: 259 additions & 41 deletions

‎docs/dev/CODEX_COMMANDS.md‎

Lines changed: 19 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -1,32 +1,29 @@
11
MODEL: GPT-5.3-codex
2-
REASONING: medium
2+
REASONING: low
33

44
COMMAND:
5-
Execute BUILD_PR_STARTER_PROJECT_TEMPLATE_MOVE_TOOLS.
5+
Execute BUILD_PR_ENGINE_IMPORT_BASELINE_AND_CONTRACT.
66

7-
Do the work in this PR. Do not ask for clarification.
7+
Do not ask for clarification.
88

9-
Required actions:
10-
1. Move:
11-
templates/starter-project-template/
12-
->
13-
tools/templates/starter-project-template/
14-
2. Update only exact references that must change for correctness after the move.
15-
3. Do NOT touch:
16-
- tools/templates/vector-native-arcade/
9+
Create exactly:
10+
- docs/dev/reports/engine_import_baseline_report.md
11+
- docs/dev/reports/engine_import_contract_decision.md
12+
- docs/dev/reports/BUILD_PR_ENGINE_IMPORT_BASELINE_AND_CONTRACT_report.md
13+
- docs/dev/reports/validation_checklist.txt
14+
15+
Required work:
16+
1. Baseline current `/src/engine/` usage across src/, games/, samples/, tools/, and relevant HTML files.
17+
2. Summarize whether the current import style is already a stable baseline contract.
18+
3. Do NOT rewrite imports in this PR.
19+
4. Do NOT move files or folders.
20+
5. Do NOT touch templates/archive lanes.
21+
6. Do NOT change anything under:
1722
- docs/dev/start_of_day/chatGPT/
1823
- docs/dev/start_of_day/codex/
19-
- docs/archive/
20-
21-
Create:
22-
- docs/dev/reports/starter_project_template_move_report.md
23-
- docs/dev/reports/validation_checklist.txt
2424

25-
Validation required:
26-
- new tools/templates starter-project-template path exists
27-
- old templates/starter-project-template path no longer exists
28-
- vector-native template location remains untouched
29-
- protected start_of_day directories untouched
25+
If exact roadmap lines already exist and are justified by findings, bracket-only state updates are allowed.
26+
Otherwise, record unapplied delta and leave roadmap wording untouched.
3027

3128
Package output to:
32-
<project folder>/tmp/BUILD_PR_STARTER_PROJECT_TEMPLATE_MOVE_TOOLS.zip
29+
<project folder>/tmp/BUILD_PR_ENGINE_IMPORT_BASELINE_AND_CONTRACT.zip

‎docs/dev/COMMIT_COMMENT.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
Relocate starter-project-template to tools/templates and preserve active template surfaces
1+
Baseline current /src/engine import usage and record the active engine import contract

‎docs/dev/NEXT_COMMAND.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,2 @@
11
After Codex completes and validation passes:
2-
APPLY_PR_STARTER_PROJECT_TEMPLATE_MOVE_TOOLS_VALIDATE
2+
APPLY_PR_ENGINE_IMPORT_BASELINE_AND_CONTRACT_VALIDATE

‎docs/dev/reports/BUILD_PR_ENGINE_IMPORT_BASELINE_AND_CONTRACT_report.md‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
# BUILD_PR_ENGINE_IMPORT_BASELINE_AND_CONTRACT Report
2+
3+
Generated: 2026-04-12
4+
5+
## Deliverables Created
6+
- `docs/dev/reports/engine_import_baseline_report.md`
7+
- `docs/dev/reports/engine_import_contract_decision.md`
8+
- `docs/dev/reports/BUILD_PR_ENGINE_IMPORT_BASELINE_AND_CONTRACT_report.md`
9+
- `docs/dev/reports/validation_checklist.txt`
10+
11+
## Work Performed
12+
1. Baseline scan executed for `/src/engine/` usage across `src/`, `games/`, `samples/`, `tools/`, and HTML files.
13+
2. Import-style contract assessment documented from scan evidence.
14+
3. No import rewrites performed.
15+
4. No file/folder moves performed.
16+
17+
## Roadmap Handling
18+
- Checked `docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md` for exact bracket-only candidates.
19+
- Existing exact line found already complete:
20+
- `[x] imports normalized after moves`
21+
- No roadmap text change applied in this lane.
22+
- Unapplied delta record: no additional exact bracket-only status delta was justified by this baseline-only pass.
23+
24+
## Constraint Compliance
25+
- No import rewriting in this PR.
26+
- No move/delete operations in this PR.
27+
- No edits under:
28+
- `docs/dev/start_of_day/chatGPT/`
29+
- `docs/dev/start_of_day/codex/`
30+
- No edits under templates/archive lanes in this PR.

‎docs/dev/reports/change_summary.txt‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
- codex-only execution lane
2-
- move starter-project-template to tools/templates
3-
- preserve vector-native template under tools/templates
4-
- no archive move
1+
- low-token engine import baseline lane
2+
- no import rewrites
3+
- no structural moves
4+
- records current /src/engine usage as contract candidate

‎docs/dev/reports/engine_import_baseline_report.md‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
# Engine Import Baseline Report
2+
3+
Generated: 2026-04-12
4+
Lane: BUILD_PR_ENGINE_IMPORT_BASELINE_AND_CONTRACT
5+
6+
## Scope Scanned
7+
- `src/`
8+
- `games/`
9+
- `samples/`
10+
- `tools/`
11+
- relevant HTML files under those directories
12+
- docs and templates excluded from baseline metrics
13+
14+
## Baseline Metrics (`src/engine/` reference scan)
15+
- Total matches: `1775`
16+
- Unique files: `790`
17+
18+
By top-level area:
19+
- `samples`: `1506`
20+
- `games`: `143`
21+
- `tools`: `112`
22+
- `src`: `14`
23+
24+
By style:
25+
- `root-absolute` (`/src/engine/...`): `1486`
26+
- `relative-up-path` (`../../src/engine/...` etc.): `215`
27+
- `other-src-engine-ref` (`src/engine/...` non-import/contextual refs): `74`
28+
29+
By extension:
30+
- `.js`: `1465`
31+
- `.html`: `236`
32+
- `.json`: `70`
33+
- `.md`: `4`
34+
35+
## HTML-Specific Baseline
36+
- HTML matches: `236`
37+
- HTML unique files: `231`
38+
- HTML style split:
39+
- `relative-up-path`: `214`
40+
- `root-absolute`: `22`
41+
42+
## Non-HTML Baseline
43+
- Non-HTML matches: `1539`
44+
- Non-HTML unique files: `559`
45+
- Non-HTML style split:
46+
- `root-absolute`: `1464`
47+
- `relative-up-path`: `1`
48+
- `other-src-engine-ref`: `74`
49+
50+
## Observed Pattern
51+
- Runtime/module code is predominantly rooted on `/src/engine/...`.
52+
- Nested HTML entry points predominantly use relative `../..` paths to `src/engine/...` assets.
53+
- `other-src-engine-ref` entries are largely README/config/baseline metadata references rather than active import-style divergence.

‎docs/dev/reports/engine_import_contract_decision.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
# Engine Import Contract Decision
2+
3+
Generated: 2026-04-12
4+
Lane: BUILD_PR_ENGINE_IMPORT_BASELINE_AND_CONTRACT
5+
6+
## Decision
7+
Current import style is an acceptable and stable baseline contract.
8+
9+
## Contract Summary
10+
1. JS/module imports should use rooted engine specifiers where used today:
11+
- `/src/engine/...`
12+
2. HTML asset links may use either:
13+
- rooted `/src/engine/...` for root-served pages, or
14+
- relative `../..` paths for nested pages.
15+
3. Non-runtime string references to `src/engine/...` (docs/config/baselines) do not, by themselves, indicate contract drift.
16+
17+
## Justification
18+
- Baseline evidence shows strong consistency:
19+
- non-HTML rooted usage is dominant (`1464` rooted vs `1` relative-up-path)
20+
- HTML usage follows location-aware linking (`214` relative-up-path, `22` rooted)
21+
- Existing roadmap already records import normalization completion.
22+
- This lane is baseline+contract confirmation only; no rewrite needed.
23+
24+
## Decision Outcome
25+
- Preserve current contract as baseline.
26+
- Defer any import-style unification to a dedicated future rewrite lane (if requested).

‎docs/dev/reports/validation_checklist.txt‎

Lines changed: 18 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,27 +1,32 @@
1-
APPLY_PR_TEMPLATES_ROOT_REMOVE_AFTER_RELOCATION
1+
BUILD_PR_ENGINE_IMPORT_BASELINE_AND_CONTRACT
22
Validation Checklist
33
Generated: 2026-04-12
44

5-
[PASS] tools/templates/vector-native-arcade exists
5+
[PASS] baseline scan completed across required directories
66
Evidence:
7-
- `Test-Path tools/templates/vector-native-arcade` -> `True`
7+
- scanned `src/`, `games/`, `samples/`, `tools/` for `/src/engine/` usage
8+
- included HTML-specific scan under same areas
89

9-
[PASS] tools/templates/starter-project-template exists
10+
[PASS] baseline report created
1011
Evidence:
11-
- `Test-Path tools/templates/starter-project-template` -> `True`
12+
- `docs/dev/reports/engine_import_baseline_report.md`
1213

13-
[PASS] templates root has no active files
14+
[PASS] contract decision created
1415
Evidence:
15-
- `Get-ChildItem -Recurse -File templates | Measure-Object` -> `0`
16+
- `docs/dev/reports/engine_import_contract_decision.md`
1617

17-
[FAIL] no non-doc runtime references to "templates/"
18+
[PASS] BUILD report created
1819
Evidence:
19-
- `rg -n "templates/" --glob "!docs/**"` returned matches
20+
- `docs/dev/reports/BUILD_PR_ENGINE_IMPORT_BASELINE_AND_CONTRACT_report.md`
2021

21-
[SKIP] delete templates/
22+
[PASS] no import rewrites performed
2223
Evidence:
23-
- skipped because validation did not pass
24+
- lane executed as scan+docs-only baseline/decision pass
2425

25-
[PASS] docs/dev/start_of_day untouched
26+
[PASS] no move/delete operations performed
2627
Evidence:
27-
- `git diff --name-only -- docs/dev/start_of_day` -> no entries
28+
- lane executed as docs-only reporting pass
29+
30+
[PASS] protected start_of_day directories untouched
31+
Evidence:
32+
- `git diff --name-only -- docs/dev/start_of_day/chatGPT docs/dev/start_of_day/codex` -> no entries

‎docs/pr/BUILD_PR_ENGINE_IMPORT_BASELINE_AND_CONTRACT.md‎

Lines changed: 107 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,107 @@
1+
# BUILD_PR_ENGINE_IMPORT_BASELINE_AND_CONTRACT
2+
3+
## PR Purpose
4+
Create one execution-ready, low-token lane to baseline current `/src/engine/` usage and convert it into an explicit contract report.
5+
6+
## Scope
7+
This PR is single-purpose:
8+
- inventory current `/src/engine/` imports and stylesheet references
9+
- classify the usage surface by area
10+
- record whether the current import style is already stable enough to treat as the baseline contract
11+
- do not rewrite imports in this PR
12+
- do not move files
13+
- do not touch unrelated cleanup targets
14+
15+
## Why This PR Now
16+
Recent cleanup work reduced noise and removed active template blockers. This makes engine import baselining a good next high-impact lane with low execution risk.
17+
18+
## Exact Target Files
19+
20+
### Must create or overwrite
21+
- `docs/dev/reports/engine_import_baseline_report.md`
22+
- `docs/dev/reports/engine_import_contract_decision.md`
23+
- `docs/dev/reports/BUILD_PR_ENGINE_IMPORT_BASELINE_AND_CONTRACT_report.md`
24+
- `docs/dev/reports/validation_checklist.txt`
25+
26+
### May update only if already present and only to align with this PR
27+
- `docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md`
28+
29+
## Required Work
30+
31+
### 1) Baseline report
32+
Create `docs/dev/reports/engine_import_baseline_report.md`.
33+
34+
This report must:
35+
- summarize current `/src/engine/` usage in active repo surfaces
36+
- separate usage into:
37+
- `src/`
38+
- `games/`
39+
- `samples/`
40+
- `tools/`
41+
- HTML stylesheet references
42+
- metadata/report-only references if found
43+
- identify whether current usage appears consistent, mixed, or transitional
44+
- capture exact validation commands used
45+
46+
### 2) Contract decision
47+
Create `docs/dev/reports/engine_import_contract_decision.md`.
48+
49+
This file must include:
50+
- current contract candidate:
51+
- `absolute-root /src/engine/*`
52+
- whether this should be treated as the current baseline contract
53+
- rationale
54+
- allowed now
55+
- not allowed now
56+
- exact future follow-up needed before any mass rewrite lane
57+
58+
Expected outcome for this PR:
59+
- treat the current `/src/engine/` style as the active baseline unless contradictory evidence is found
60+
61+
### 3) Optional roadmap alignment
62+
Only if exact wording already exists, Codex may apply bracket-only roadmap state updates for:
63+
- `imports normalized after moves`
64+
- `imports pointing to legacy paths reduced`
65+
- `move/refactor validation strategy documented`
66+
67+
Rules:
68+
- no wording edits
69+
- no reorder
70+
- if exact text is not cleanly applicable, record it in the BUILD report under `Unapplied Planned Delta`
71+
72+
### 4) BUILD report
73+
Create `docs/dev/reports/BUILD_PR_ENGINE_IMPORT_BASELINE_AND_CONTRACT_report.md` with:
74+
- bundle type
75+
- exact files created
76+
- exact files changed
77+
- summary of findings
78+
- contract decision
79+
- any roadmap bracket changes actually applied
80+
- unapplied delta if any
81+
- explicit statement that no runtime code, file moves, or import rewrites occurred
82+
83+
### 5) Validation checklist
84+
Create `docs/dev/reports/validation_checklist.txt` with pass/fail for:
85+
- protected start_of_day directories untouched
86+
- no runtime import rewrites performed
87+
- required reports created
88+
- roadmap wording preserved if roadmap changed
89+
- roadmap changes bracket-only if roadmap changed
90+
91+
## Validation Commands Codex Must Run
92+
Run only narrow commands needed for this PR:
93+
1. scan active repo surfaces for `/src/engine/`
94+
2. scan HTML files for `/src/engine/ui/`
95+
3. confirm no changes under protected start_of_day directories
96+
4. if roadmap changed, verify diff is bracket-only
97+
98+
## Non-Goals
99+
- no import rewrites
100+
- no directory moves
101+
- no broad cleanup
102+
- no template/archive work
103+
- no runtime behavior changes
104+
105+
## Expected Output
106+
Package output to:
107+
- `<project folder>/tmp/BUILD_PR_ENGINE_IMPORT_BASELINE_AND_CONTRACT.zip`

0 commit comments

Comments
 (0)