OWNER 010 document canonical project folders

Author: ToolboxAid

dev/build/ProjectInstructions/TEAM_START_COMMANDS.md

@@ -15,6 +15,14 @@ Read `dev/build/ProjectInstructions/addendums/team_backlog_sod_eod_standard.md`
 Branch Lifecycle (Canonical):
 - Follow `dev/build/ProjectInstructions/addendums/project_instructions_single_source_eod_lock.md` for START / WORK / END lifecycle, branch gates, mandatory hard stops, and EOD main lock.
 
+## Team Migration Note
+
+Team Alfa, Team Bravo, Team Charlie, and historical Team Gamma lanes must update from current `main` before starting work and use the canonical folders documented in `dev/build/ProjectInstructions/addendums/canonical_repository_structure.md`.
+
+Do not create or reuse legacy folders such as `docs_build/`, `tmp/`, `projects/`, `scripts/`, `tests/`, `archive/`, `project-instructions/`, `dev/docs_build/`, `dev/project-instructions/`, `dev/workspace/artifacts/`, or `dev/build/dev/`.
+
+If a proposed file does not clearly belong in a canonical folder, HARD STOP and report the proposed path.
+
 ## Start Team Alfa
 
 Ready-to-copy command:

dev/build/ProjectInstructions/addendums/canonical_repository_structure.md

@@ -6,30 +6,61 @@ Establish the canonical repository structure for future development and reduce t
 
 ## Canonical Structure
 
-Root product sections:
-- docs/
-- games/
-- toolbox/
+Valid top-level folders:
 - account/
 - admin/
-- legal/
 - assets/
+- community/
+- company/
+- deploy/
+- dev/
+- docs/
+- games/
+- learn/
+- legal/
+- marketplace/
+- memberships/
+- owner/
+- src/
+- toolbox/
+
+Root product and repo sections:
+- account/, admin/, community/, company/, learn/, legal/, marketplace/, memberships/, and owner/ are production website sections.
+- assets/ contains production website and tool assets.
+- docs/ is production Docs & Help content.
+- games/ is public game discovery.
+- toolbox/ is the Creator toolbox/workspace.
+- deploy/ contains deployment configuration.
+- dev/ contains the development workspace.
+- src/ contains deployable application/runtime/API source.
 
 Deployable application source:
 - src/web/{feature-name}/
 - src/api-runtime/{feature-name}/
 - src/runtime/{feature-name}/
 
-Development workspace:
+Valid dev workspace folders:
+- dev/archive/
 - dev/build/
+- dev/config/
 - dev/reports/
-- dev/tests/
 - dev/scripts/
-- dev/config/
-- dev/deploy/
-- dev/archive/
+- dev/templates/
+- dev/tests/
+- dev/tools/
 - dev/workspace/
 
+Dev workspace ownership:
+- dev/archive/ owns historical reference material only.
+- dev/build/ owns active Project Instructions, architecture, database DDL/DML/seed docs, standards, backlog, PR planning, and governance.
+- dev/config/ owns development-only runner and tooling configuration.
+- dev/reports/ owns active and historical generated reports.
+- dev/scripts/ owns development-only scripts and runners.
+- dev/templates/ owns reusable development templates.
+- dev/tests/ owns non-deployable test suites.
+- dev/tools/ owns development-only tooling.
+- dev/workspace/ owns generated output: tmp, zips, logs, generated files, and test-results.
+
 Tools:
 - toolbox/{tool-name}/index.html
 
@@ -56,13 +87,38 @@ These legacy transition buckets may remain until explicit migration PRs move the
 
 ## Rules
 
+- Root is production website and standard repository configuration only.
+- src/ is deployable application/runtime/API code.
+- dev/ is development workspace only.
+- deploy/ is deployment configuration.
+- docs/ is production Docs & Help content.
 - Theme first.
 - Tool CSS second.
 - Shared functionality belongs in assets/js/shared/.
 - No new scattered JS folders.
 - No new scattered CSS folders.
+- Do not create new folders unless they fit the documented canonical structure.
+- If a requested or generated path does not clearly fit the canonical structure, Codex must HARD STOP and report the proposed path.
 - New development follows the canonical structure.
 - New deployable `src/` work follows `src/web/`, `src/api-runtime/`, or `src/runtime/`.
 - New non-deployable work belongs under `dev/`.
 - Required reports belong under flat `dev/reports/`.
 - Required ZIPs belong under `dev/workspace/zips/`; generated temporary artifacts belong under `dev/workspace/tmp/`.
+
+## Invalid Legacy Paths
+
+These paths are not active repository ownership locations:
+
+- docs_build/
+- tmp/
+- projects/
+- scripts/
+- tests/
+- archive/
+- project-instructions/
+- dev/docs_build/
+- dev/project-instructions/
+- dev/workspace/artifacts/
+- dev/build/dev/
+
+References to invalid legacy paths are allowed only as historical/reference notes, explicit migration notes, ignore rules, or audit evidence. Active commands, active templates, Project Instructions, validation scripts, and new Codex output must use the canonical folders above.

dev/build/ProjectInstructions/addendums/repository_directory_standard.md

@@ -14,10 +14,30 @@ This document is governance only. It does not move runtime, UI, API, tests, or p
 - Repository root contains production/public product sections and standard repository configuration only.
 - `src/` contains deployable application code.
 - `dev/` contains non-deployable build, test, bootstrap, governance, report, and local workspace items.
+- `deploy/` contains deployment configuration.
 - `docs/` remains at root because it is production Docs & Help.
 - `games/` remains at root because it is public game discovery.
 - `toolbox/` remains at root because it is the Creator toolbox/workspace.
-- Other public product roots such as `account/`, `admin/`, `legal/`, and `assets/` remain root-level product sections when present.
+- Other public product roots such as `account/`, `admin/`, `assets/`, `community/`, `company/`, `learn/`, `legal/`, `marketplace/`, `memberships/`, and `owner/` remain root-level product sections when present.
+
+Valid top-level folders are:
+
+- account/
+- admin/
+- assets/
+- community/
+- company/
+- deploy/
+- dev/
+- docs/
+- games/
+- learn/
+- legal/
+- marketplace/
+- memberships/
+- owner/
+- src/
+- toolbox/
 
 ## Final Src Layer Standard
 
@@ -35,21 +55,38 @@ Transition rule:
 
 ## Development Workspace Paths
 
+- `dev/archive/` owns historical development reference material that is not active governance.
 - `dev/build/` owns active development governance, Project Instructions, and PR workflow material.
+- `dev/build/` also owns architecture, database DDL/DML/seed docs, standards, backlog, PR planning, and governance.
+- `dev/config/` owns development-only runner and tooling configuration.
 - `dev/reports/` owns generated reports using flat filenames.
-- `dev/tests/` owns non-deployable test suites.
 - `dev/scripts/` owns development-only scripts and runners.
-- `dev/config/` owns development-only runner and tooling configuration.
-- `dev/deploy/` owns development-only deployment assets and local deployment configuration.
+- `dev/templates/` owns reusable development templates.
+- `dev/tests/` owns non-deployable test suites.
+- `dev/tools/` owns development-only tooling.
 - `dev/workspace/` owns generated non-report artifacts and ignored local temporary workspace output.
-- `dev/archive/` owns historical development reference material that is not active governance.
+- `dev/workspace/` generated output includes tmp, zips, logs, generated files, and test-results.
 - `dev/build/ProjectInstructions/` is the only active Project Instructions source.
-- Root `docs_build/`, root `tests/`, root `archive/`, root `tmp/`, and root `project-instructions/` are not active workspace locations after the restructure.
+- 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.
 - 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/`.
 
 ## Legacy Reference Exceptions
 
-Path references to old root `docs_build/`, `tests/`, `archive/`, or `tmp/` locations are allowed only when they are:
+Invalid legacy paths:
+
+- docs_build/
+- tmp/
+- projects/
+- scripts/
+- tests/
+- archive/
+- project-instructions/
+- dev/docs_build/
+- dev/project-instructions/
+- dev/workspace/artifacts/
+- dev/build/dev/
+
+Path references to invalid legacy locations are allowed only when they are:
 
 - historical/reference content under `dev/archive/` or `dev/build/pr/reference/`
 - explicit legacy exception notes in active governance
@@ -58,6 +95,12 @@ Path references to old root `docs_build/`, `tests/`, `archive/`, or `tmp/` locat
 
 Active commands, templates, and Project Instructions must use the final `dev/`, `dev/reports/`, and `dev/workspace/` paths.
 
+## Codex Folder Creation Rule
+
+Codex must not create new folders unless they fit the documented canonical structure.
+
+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.
+
 ## Creator Data Boundary
 
 - Creator data must not write to repository folders.

dev/reports/PR_26179_OWNER_010-canonical-project-folder-instructions.md

@@ -0,0 +1,73 @@
+# PR_26179_OWNER_010-canonical-project-folder-instructions
+
+Updated: 2026-06-28T01:03:53Z
+Team: OWNER
+Branch: PR_26179_OWNER_010-canonical-project-folder-instructions
+Scope: Documentation/governance only. No files moved. No runtime behavior or production page changes.
+
+## Summary
+- Updated canonical repository structure governance under dev/build/ProjectInstructions/.
+- Added the valid top-level folder list and valid dev workspace folder list.
+- Documented ownership rules for root, src/, dev/, deploy/, docs/, dev/build/, and dev/workspace/.
+- Added invalid legacy path list and Codex HARD STOP rule for unclear new folders.
+- Added team migration note for Team Alfa, Team Bravo, Team Charlie, and historical Team Gamma lanes.
+
+## Changed Files
+```
+M	dev/build/ProjectInstructions/TEAM_START_COMMANDS.md
+M	dev/build/ProjectInstructions/addendums/canonical_repository_structure.md
+M	dev/build/ProjectInstructions/addendums/repository_directory_standard.md
+```
+
+## Intentional Old Path Mentions
+The grep lane intentionally finds legacy paths in active Project Instructions where the content marks those paths invalid, deprecated, historical, generated-output locations, or non-active reference material. These are intentional documentation mentions, not active placement instructions.
+
+```
+dev/build/ProjectInstructions\TEAM_START_COMMANDS.md:22:Do not create or reuse legacy folders such as `docs_build/`, `tmp/`, `projects/`, `scripts/`, `tests/`, `archive/`, `project-instructions/`, `dev/docs_build/`, `dev/project-instructions/`, `dev/workspace/artifacts/`, or `dev/build/dev/`.
+dev/build/ProjectInstructions\README.txt:7:Preserve historical Project Instructions material as deprecated reference only. Do not treat root-level copies in `dev/build/dev/`, `dev/archive/`, or archived snapshots as active instruction sources. When a conflict appears, `dev/build/ProjectInstructions/` wins unless OWNER explicitly approves a newer governance change.
+dev/build/ProjectInstructions\PROJECT_INSTRUCTIONS.md:42:- Retained reference material belongs under the repository root `dev/archive/` tree, not under `dev/build/dev/`.
+dev/build/ProjectInstructions\addendums\canonical_repository_structure.md:106:- Required ZIPs belong under `dev/workspace/zips/`; generated temporary artifacts belong under `dev/workspace/tmp/`.
+dev/build/ProjectInstructions\addendums\canonical_repository_structure.md:112:- docs_build/
+dev/build/ProjectInstructions\addendums\canonical_repository_structure.md:113:- tmp/
+dev/build/ProjectInstructions\addendums\canonical_repository_structure.md:114:- projects/
+dev/build/ProjectInstructions\addendums\canonical_repository_structure.md:115:- scripts/
+dev/build/ProjectInstructions\addendums\canonical_repository_structure.md:116:- tests/
+dev/build/ProjectInstructions\addendums\canonical_repository_structure.md:117:- archive/
+dev/build/ProjectInstructions\addendums\canonical_repository_structure.md:118:- project-instructions/
+dev/build/ProjectInstructions\addendums\canonical_repository_structure.md:119:- dev/docs_build/
+dev/build/ProjectInstructions\addendums\canonical_repository_structure.md:120:- dev/project-instructions/
+dev/build/ProjectInstructions\addendums\canonical_repository_structure.md:121:- dev/workspace/artifacts/
+dev/build/ProjectInstructions\addendums\canonical_repository_structure.md:122:- dev/build/dev/
+dev/build/ProjectInstructions\addendums\documentation_ownership.md:52:- `dev/workspace/tmp/` contains temporary generated files.
+dev/build/ProjectInstructions\addendums\environment_governance_model.md:90:- Local project assets: `/local/projects/`
+dev/build/ProjectInstructions\addendums\environment_governance_model.md:91:- DEV project assets: `/dev/projects/`
+dev/build/ProjectInstructions\addendums\environment_governance_model.md:92:- IST project assets: `/ist/projects/`
+dev/build/ProjectInstructions\addendums\environment_governance_model.md:93:- UAT project assets: `/uat/projects/`
+dev/build/ProjectInstructions\addendums\environment_governance_model.md:94:- PROD project assets: `/prod/projects/`
+dev/build/ProjectInstructions\addendums\koti_layout_contract.md:9:- `dev/workspace/tmp/uat_exports/king_of_the_iceberg_layout_snapshot.json`
+dev/build/ProjectInstructions\addendums\koti_layout_contract.md:10:- `dev/workspace/tmp/uat_tool_layout_workflow_results.json`
+dev/build/ProjectInstructions\addendums\project_instructions_single_source_eod_lock.md:11:- root-level copies in `dev/build/dev/`
+dev/build/ProjectInstructions\standards\PROJECT_CONTRACT.md:28:- Fixture file: `dev/tests/fixtures/projects/project-scenarios.json`
+dev/build/ProjectInstructions\addendums\repository_directory_standard.md: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.
+dev/build/ProjectInstructions\addendums\repository_directory_standard.md: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/`.
+dev/build/ProjectInstructions\addendums\repository_directory_standard.md:77:- docs_build/
+dev/build/ProjectInstructions\addendums\repository_directory_standard.md:78:- tmp/
+dev/build/ProjectInstructions\addendums\repository_directory_standard.md:79:- projects/
+dev/build/ProjectInstructions\addendums\repository_directory_standard.md:80:- scripts/
+dev/build/ProjectInstructions\addendums\repository_directory_standard.md:81:- tests/
+dev/build/ProjectInstructions\addendums\repository_directory_standard.md:82:- archive/
+dev/build/ProjectInstructions\addendums\repository_directory_standard.md:83:- project-instructions/
+dev/build/ProjectInstructions\addendums\repository_directory_standard.md:84:- dev/docs_build/
+dev/build/ProjectInstructions\addendums\repository_directory_standard.md:85:- dev/project-instructions/
+dev/build/ProjectInstructions\addendums\repository_directory_standard.md:86:- dev/workspace/artifacts/
+dev/build/ProjectInstructions\addendums\repository_directory_standard.md:87:- dev/build/dev/
+```
+
+## Validation
+- npm run validate:canonical-structure: PASS
+- git diff --check: PASS
+- node ./dev/scripts/run-platform-validation-suite.mjs: PASS, 8/8 scenarios
+- Project Instructions invalid-path grep: PASS, intentional historical/invalid-path mentions documented above
+
+## Blockers
+None.

dev/reports/PR_26179_OWNER_010-canonical-project-folder-instructions_requirement-checklist.md

@@ -0,0 +1,15 @@
+# PR_26179_OWNER_010-canonical-project-folder-instructions Requirement Checklist
+
+- [x] Documentation/governance only.
+- [x] No files moved.
+- [x] No runtime behavior changed.
+- [x] No production pages changed.
+- [x] Canonical repository structure documented under dev/build/ProjectInstructions/.
+- [x] Valid top-level folders documented.
+- [x] Valid dev folders documented.
+- [x] Root/src/dev/deploy/docs/dev-build/dev-workspace ownership documented.
+- [x] Invalid legacy paths explicitly marked.
+- [x] Codex folder-creation HARD STOP rule added.
+- [x] Existing Project Instructions old-path references reviewed and intentional mentions documented.
+- [x] Team migration note added for Alfa, Bravo, Charlie, and historical Gamma lanes.
+- [x] Required validation passed.

dev/reports/PR_26179_OWNER_010-canonical-project-folder-instructions_validation-report.md

@@ -0,0 +1,10 @@
+# PR_26179_OWNER_010-canonical-project-folder-instructions Validation Report
+
+Updated: 2026-06-28T01:03:53Z
+
+- npm run validate:canonical-structure: PASS
+- git diff --check: PASS
+- node ./dev/scripts/run-platform-validation-suite.mjs: PASS, 8/8 scenarios
+- grep Project Instructions for old invalid paths: PASS, intentional mentions documented in PR report
+- Runtime/product files changed: NO
+- Production pages changed: NO