|
1 | 1 | # Repository Directory Standard |
2 | 2 |
|
3 | | -Status: Approved |
4 | | -Owner: OWNER |
| 3 | +Status: Superseded |
5 | 4 |
|
6 | | -## Purpose |
| 5 | +SSoT: `dev/build/ProjectInstructions/addendums/canonical_repository_structure.md` |
7 | 6 |
|
8 | | -Define the target repository directory ownership model for the post-restructure repository. |
9 | | - |
10 | | -This document is governance only. It does not move runtime, UI, API, tests, or production files by itself. |
11 | | - |
12 | | -## Directory Ownership |
13 | | - |
14 | | -- Repository root contains production/public product sections and standard repository configuration only. |
15 | | -- `src/` contains deployable application code. |
16 | | -- `dev/` contains non-deployable build, test, bootstrap, governance, report, and local workspace items. |
17 | | -- `deploy/` contains deployment configuration. |
18 | | -- `docs/` remains at root because it is production Docs & Help. |
19 | | -- `games/` remains at root because it is public game discovery. |
20 | | -- `toolbox/` remains at root because it is the Creator toolbox/workspace. |
21 | | -- Other public product roots such as `account/`, `admin/`, `assets/`, `community/`, `company/`, `learn/`, `legal/`, `marketplace/`, `memberships/`, and `owner/` remain root-level product sections when present. |
22 | | - |
23 | | -Valid top-level folders are: |
24 | | - |
25 | | -- account/ |
26 | | -- admin/ |
27 | | -- assets/ |
28 | | -- community/ |
29 | | -- company/ |
30 | | -- deploy/ |
31 | | -- dev/ |
32 | | -- docs/ |
33 | | -- games/ |
34 | | -- learn/ |
35 | | -- legal/ |
36 | | -- marketplace/ |
37 | | -- memberships/ |
38 | | -- owner/ |
39 | | -- src/ |
40 | | -- toolbox/ |
41 | | - |
42 | | -## Final Src Layer Standard |
43 | | - |
44 | | -The final `src/` ownership model is: |
45 | | - |
46 | | -- `src/web/` for browser-facing deployable application modules used by public pages, account/admin surfaces, and Creator tools. |
47 | | -- `src/api-runtime/` for deployable API/runtime service modules that back the shared Browser -> API -> Postgres/R2 contract. |
48 | | -- `src/runtime/` for deployable game, tool, engine, and shared runtime capabilities. |
49 | | - |
50 | | -Transition rule: |
51 | | - |
52 | | -- Existing top-level `src/advanced/`, `src/api/`, `src/dev-runtime/`, `src/engine/`, `src/shared/`, and `src/tools/` directories are legacy transition buckets until explicit migration PRs move them. |
53 | | -- Do not add new top-level `src/` layer names outside `src/web/`, `src/api-runtime/`, or `src/runtime/` without OWNER approval. |
54 | | -- Do not use team names in runtime source filenames. |
55 | | - |
56 | | -## Development Workspace Paths |
57 | | - |
58 | | -- `dev/archive/` owns historical development reference material that is not active governance. |
59 | | -- `dev/build/` owns active development governance, Project Instructions, and PR workflow material. |
60 | | -- `dev/build/` also owns architecture, database DDL/DML/seed docs, standards, backlog, PR planning, and governance. |
61 | | -- `dev/config/` owns development-only runner and tooling configuration. |
62 | | -- `dev/reports/` owns generated reports using flat filenames. |
63 | | -- `dev/scripts/` owns development-only scripts and runners. |
64 | | -- `dev/templates/` owns reusable development templates. |
65 | | -- `dev/tests/` owns non-deployable test suites. |
66 | | -- `dev/tools/` owns development-only tooling. |
67 | | -- `dev/workspace/` owns generated non-report artifacts and ignored local temporary workspace output. |
68 | | -- `dev/workspace/` generated output includes tmp, zips, logs, generated files, and test-results. |
69 | | -- `dev/build/ProjectInstructions/` is the only active Project Instructions source. |
70 | | -- Root `docs_build/`, root `tests/`, root `archive/`, root `tmp/`, root `projects/`, root `scripts/`, and root `project-instructions/` are not active workspace locations after the restructure. |
71 | | -- Root `tmp/` may remain ignored as legacy local scratch only; required Codex ZIPs belong under `dev/workspace/zips/`, and generated temporary artifacts belong under `dev/workspace/tmp/`. |
72 | | - |
73 | | -## Legacy Reference Exceptions |
74 | | - |
75 | | -Invalid legacy paths: |
76 | | - |
77 | | -- docs_build/ |
78 | | -- tmp/ |
79 | | -- projects/ |
80 | | -- scripts/ |
81 | | -- tests/ |
82 | | -- archive/ |
83 | | -- project-instructions/ |
84 | | -- dev/docs_build/ |
85 | | -- dev/project-instructions/ |
86 | | -- dev/workspace/artifacts/ |
87 | | -- dev/build/dev/ |
88 | | - |
89 | | -Path references to invalid legacy locations are allowed only when they are: |
90 | | - |
91 | | -- historical/reference content under `dev/archive/` or `dev/build/pr/reference/` |
92 | | -- explicit legacy exception notes in active governance |
93 | | -- ignore rules that keep obsolete local scratch from entering commits |
94 | | -- migration reports documenting the old path and its replacement |
95 | | - |
96 | | -Active commands, templates, and Project Instructions must use the final `dev/`, `dev/reports/`, and `dev/workspace/` paths. |
97 | | - |
98 | | -## Codex Folder Creation Rule |
99 | | - |
100 | | -Codex must not create new folders unless they fit the documented canonical structure. |
101 | | - |
102 | | -If a requested or generated path does not clearly fit the canonical structure, Codex must HARD STOP and report the proposed path before writing files. |
103 | | - |
104 | | -## Creator Data Boundary |
105 | | - |
106 | | -- Creator data must not write to repository folders. |
107 | | -- Creator metadata must go through the API to Postgres. |
108 | | -- Creator assets must go through the API to Cloudflare R2. |
109 | | -- Repo folders may contain fixtures, templates, governance, and development artifacts only when they are not Creator-owned production data. |
110 | | - |
111 | | -## Environment And Runtime Rules |
112 | | - |
113 | | -- Postgres is the only active runtime database. |
114 | | -- The same application code path must run across LOCAL, DEV, IST, UAT, and PROD. |
115 | | -- Environment differences must come from `.env` values or environment-managed secrets. |
116 | | -- Runtime source filenames must not use team names. |
117 | | - |
118 | | -## PR Chain Boundary |
119 | | - |
120 | | -The development workspace restructure must proceed through sequential scoped PRs. A PR may only move or update the paths named in its purpose. |
121 | | - |
122 | | -Final path-governance PRs may document target paths and legacy exceptions, but they must not move deployable application code unless explicitly scoped. |
| 7 | +Do not duplicate folder rules here. |
0 commit comments