From 8fad0cd7095df4382aec6f86b56fd12dac8b907f Mon Sep 17 00:00:00 2001 From: "Mr. Q" <97194984+ToolboxAid@users.noreply.github.com> Date: Sun, 21 Jun 2026 14:45:55 -0400 Subject: [PATCH] PR_26172_OWNER_017 project instructions bootstrap install --- .../PROJECT_INSTRUCTIONS.md | 46 + docs_build/dev/ProjectInstructions/README.txt | 28 + .../TEAM_START_COMMANDS.md | 80 ++ .../addendums/build_path_sync.md | 35 + .../addendums/deprecation.md | 32 + .../addendums/multi_team.md | 55 ++ .../addendums/preservation.md | 42 + .../addendums/team_release_readiness.md | 31 + .../addendums/tile_overlay_status.md | 36 + .../dev/ProjectInstructions/archive/README.md | 12 + .../archive/history/.gitkeep | 1 + .../backlog/BACKLOG_MASTER.md | 117 +++ .../ProjectInstructions/deprecation/README.md | 20 + .../team_assignments/TEAM_ASSIGNMENTS.md | 143 +++ ...nstall-instruction-compliance-checklist.md | 17 + ...otstrap-install-manual-validation-notes.md | 12 + ...ct-instructions-bootstrap-install-tree.txt | 21 + ...-project-instructions-bootstrap-install.md | 56 ++ .../dev/reports/codex_changed_files.txt | 22 +- docs_build/dev/reports/codex_review.diff | 860 +++++++++++++++--- 20 files changed, 1544 insertions(+), 122 deletions(-) create mode 100644 docs_build/dev/ProjectInstructions/PROJECT_INSTRUCTIONS.md create mode 100644 docs_build/dev/ProjectInstructions/README.txt create mode 100644 docs_build/dev/ProjectInstructions/TEAM_START_COMMANDS.md create mode 100644 docs_build/dev/ProjectInstructions/addendums/build_path_sync.md create mode 100644 docs_build/dev/ProjectInstructions/addendums/deprecation.md create mode 100644 docs_build/dev/ProjectInstructions/addendums/multi_team.md create mode 100644 docs_build/dev/ProjectInstructions/addendums/preservation.md create mode 100644 docs_build/dev/ProjectInstructions/addendums/team_release_readiness.md create mode 100644 docs_build/dev/ProjectInstructions/addendums/tile_overlay_status.md create mode 100644 docs_build/dev/ProjectInstructions/archive/README.md create mode 100644 docs_build/dev/ProjectInstructions/archive/history/.gitkeep create mode 100644 docs_build/dev/ProjectInstructions/backlog/BACKLOG_MASTER.md create mode 100644 docs_build/dev/ProjectInstructions/deprecation/README.md create mode 100644 docs_build/dev/ProjectInstructions/team_assignments/TEAM_ASSIGNMENTS.md create mode 100644 docs_build/dev/reports/PR_26172_OWNER_017-project-instructions-bootstrap-install-instruction-compliance-checklist.md create mode 100644 docs_build/dev/reports/PR_26172_OWNER_017-project-instructions-bootstrap-install-manual-validation-notes.md create mode 100644 docs_build/dev/reports/PR_26172_OWNER_017-project-instructions-bootstrap-install-tree.txt create mode 100644 docs_build/dev/reports/PR_26172_OWNER_017-project-instructions-bootstrap-install.md diff --git a/docs_build/dev/ProjectInstructions/PROJECT_INSTRUCTIONS.md b/docs_build/dev/ProjectInstructions/PROJECT_INSTRUCTIONS.md new file mode 100644 index 000000000..40db33c44 --- /dev/null +++ b/docs_build/dev/ProjectInstructions/PROJECT_INSTRUCTIONS.md @@ -0,0 +1,46 @@ +# Project Instructions Operating System + +Read `README.txt` first. + +This file is the root index for the append-first Project Instructions operating system under `docs_build/dev/ProjectInstructions/`. + +## Purpose + +The Project Instructions operating system provides additive governance for: + +- backlog ownership +- team assignments +- multi-team branch and scope rules +- Build Path status synchronization +- tile overlay status behavior +- deprecation workflow +- archive and history preservation + +## Preservation + +Existing Project Instructions remain preserved in their current locations. This operating system adds structure without deleting or rewriting existing documentation. + +## Folders + +- `addendums/` contains additive governance rules. +- `backlog/` contains the central backlog file, `BACKLOG_MASTER.md`. +- `team_assignments/` contains current team assignment records. +- `deprecation/` contains deprecation workflow documentation. +- `archive/` contains retained reference material. +- `archive/history/` contains timestamped history snapshots. + +## Merge Control + +No PR in this operating system is merged without explicit owner approval. + +## OWNER Governance + +OWNER override wording: + +`OWNER override approved: ` + +OWNER follows the same safety rules: +- One active OWNER branch at a time. +- One active OWNER assignment at a time. +- OWNER may override team locks, but may not silently delete, rewrite, or remove protected instructions. +- OWNER override must be explicitly documented. diff --git a/docs_build/dev/ProjectInstructions/README.txt b/docs_build/dev/ProjectInstructions/README.txt new file mode 100644 index 000000000..27495ad8f --- /dev/null +++ b/docs_build/dev/ProjectInstructions/README.txt @@ -0,0 +1,28 @@ +Read this file first. + +Folder purpose: +This folder is the append-first Project Instructions operating system for Game Foundry Studio. It organizes active governance, backlog, team assignment, deprecation, and history material without deleting or rewriting the existing Project Instructions files elsewhere in the repository. + +Preservation rules: +Preserve all existing documentation. Add new files or append explicit references unless the owner explicitly approves deletion or rewrite. When a conflict appears, stop, explain the conflict, and request owner approval before changing existing instruction text. + +Backlog workflow: +Backlog work is tracked under backlog/. BACKLOG_MASTER.md is the planned source for backlog item status, notes, and references. Backlog item text is treated as immutable once created; status and notes may change under the governance addendums. + +Team assignment workflow: +Team assignments are tracked under team_assignments/. A team pulls work from BACKLOG_MASTER.md, marks the item building when assigned, and records the active assignment under the owning team. Teams work only on assigned items unless an OWNER override explicitly changes the assignment. + +No direct commits to main: +Do not commit directly to main unless the owner explicitly instructs that exception. Normal work must use PR branches, draft PRs, validation evidence, and owner-controlled merge approval. + +OWNER override rule: +An OWNER override must use this wording: +OWNER override approved: + +The override must explain why normal team, branch, assignment, or backlog routing is being changed. + +History snapshot rule: +When a governance or instruction state needs a history snapshot, add a new file under archive/history/ using: +CCYYMMDD_HHMMSS.md + +Do not rewrite history snapshots after creation unless the owner explicitly approves. diff --git a/docs_build/dev/ProjectInstructions/TEAM_START_COMMANDS.md b/docs_build/dev/ProjectInstructions/TEAM_START_COMMANDS.md new file mode 100644 index 000000000..3490df216 --- /dev/null +++ b/docs_build/dev/ProjectInstructions/TEAM_START_COMMANDS.md @@ -0,0 +1,80 @@ +# TEAM_START_COMMANDS + +## Start Team Alpha + +Ready-to-copy command: + +```text +OWNER override approved: Start Team Alpha from the ProjectInstructions release gate. + +Read docs_build/dev/ProjectInstructions/README.txt first. +Read docs_build/dev/ProjectInstructions/backlog/BACKLOG_MASTER.md. +Read docs_build/dev/ProjectInstructions/team_assignments/TEAM_ASSIGNMENTS.md. + +Pull one [ ] item for Team Alpha from BACKLOG_MASTER.md. +Stop if Team Alpha already has an active branch. +Stop if Team Alpha already has an active assignment. +Stop if no [ ] Team Alpha backlog item is available. + +Change the selected backlog item from [ ] to [.]. +Add the selected assignment under Team Alpha in TEAM_ASSIGNMENTS.md. +Create one Team Alpha branch for the selected assignment. +Work only that assignment. +``` + +## Start Team Beta + +Ready-to-copy command: + +```text +OWNER override approved: Start Team Beta from the ProjectInstructions release gate. + +Read docs_build/dev/ProjectInstructions/README.txt first. +Read docs_build/dev/ProjectInstructions/backlog/BACKLOG_MASTER.md. +Read docs_build/dev/ProjectInstructions/team_assignments/TEAM_ASSIGNMENTS.md. + +Pull one [ ] item for Team Beta from BACKLOG_MASTER.md. +Stop if Team Beta already has an active branch. +Stop if Team Beta already has an active assignment. +Stop if no [ ] Team Beta backlog item is available. + +Change the selected backlog item from [ ] to [.]. +Add the selected assignment under Team Beta in TEAM_ASSIGNMENTS.md. +Create one Team Beta branch for the selected assignment. +Work only that assignment. +``` + +## Start Team Gamma + +Ready-to-copy command: + +```text +OWNER override approved: Start Team Gamma from the ProjectInstructions release gate. + +Read docs_build/dev/ProjectInstructions/README.txt first. +Read docs_build/dev/ProjectInstructions/backlog/BACKLOG_MASTER.md. +Read docs_build/dev/ProjectInstructions/team_assignments/TEAM_ASSIGNMENTS.md. + +Pull one [ ] item for Team Gamma from BACKLOG_MASTER.md. +Stop if Team Gamma already has an active branch. +Stop if Team Gamma already has an active assignment. +Stop if no [ ] Team Gamma backlog item is available. + +Change the selected backlog item from [ ] to [.]. +Add the selected assignment under Team Gamma in TEAM_ASSIGNMENTS.md. +Create one Team Gamma branch for the selected assignment. +Work only that assignment. +``` + +## Day Work / EOD Merge Reminder + +Ready-to-copy reminder: + +```text +Commit/push during the day is allowed only on assigned team/OWNER/PR branches. + +Merge to main is EOD-only and owner-approved, unless the owner explicitly says: +"Merge this PR now." + +Do not treat sequential PR completion as merge approval. +``` diff --git a/docs_build/dev/ProjectInstructions/addendums/build_path_sync.md b/docs_build/dev/ProjectInstructions/addendums/build_path_sync.md new file mode 100644 index 000000000..ad7195d1c --- /dev/null +++ b/docs_build/dev/ProjectInstructions/addendums/build_path_sync.md @@ -0,0 +1,35 @@ +# Build Path Status Sync Governance + +## Purpose + +This addendum keeps the central backlog and Toolbox Build Path aligned. + +## Source Of Truth + +`docs_build/dev/ProjectInstructions/backlog/BACKLOG_MASTER.md` is the source of truth for tool status. + +## Build Path Sync + +`toolbox/index.html` Build Path tiles must match tool status from `BACKLOG_MASTER.md`. + +When a central backlog tool status changes, update the matching Build Path tile. + +Status and Build Path changes should be in the same PR when practical. + +## Phase Percentages + +Phase percentages are calculated from tools in each phase. + +Rules: +- completed tools count as complete +- planned, wireframe, building, and blocked tools remain in the denominator +- deprecated tools are excluded from the denominator +- phase percentage must be recalculated when a tool status changes + +## Validation + +PRs that change backlog status or Build Path status must document: +- backlog item changed +- matching Build Path tile changed +- phase percentage before and after +- skipped sync, if any, with reason diff --git a/docs_build/dev/ProjectInstructions/addendums/deprecation.md b/docs_build/dev/ProjectInstructions/addendums/deprecation.md new file mode 100644 index 000000000..2268b30bc --- /dev/null +++ b/docs_build/dev/ProjectInstructions/addendums/deprecation.md @@ -0,0 +1,32 @@ +# Deprecation Governance + +## Purpose + +This addendum defines how Project Instructions backlog and Build Path items become deprecated while staying traceable. + +## Deprecation Group + +Deprecation is its own group and must not be hidden inside normal completion work. + +## Traceability + +Deprecated items must preserve: +- original item text +- deprecated status +- owner approval reference +- replacement path, if any +- archive/removal decision, if any + +## Owner Approval + +Owner approval is required before archive or removal. + +No team may remove a deprecated item solely because it is deprecated. + +## Build Path Display + +Deprecated Build Path items use red overlay if visible. + +Deprecated items do not count against current MVP completion. + +If a deprecated item remains visible, it must communicate Deprecated status to creators without relying on color alone. diff --git a/docs_build/dev/ProjectInstructions/addendums/multi_team.md b/docs_build/dev/ProjectInstructions/addendums/multi_team.md new file mode 100644 index 000000000..373a51ed0 --- /dev/null +++ b/docs_build/dev/ProjectInstructions/addendums/multi_team.md @@ -0,0 +1,55 @@ +# Multi-Team Codex Execution Governance + +## All-Team Preferred Codex Execution Method + +Preferred execution model: +Single Codex session with multiple sequential PRs. + +Applies to: +- Team Alfa through Team Zulu +- Team OWNER + +Purpose: +Reduce back-and-forth between owner and Codex while keeping PRs reviewable and scoped. + +Rules: +- One Codex session may execute multiple sequential PRs. +- Each PR must still have one clear purpose. +- Each PR must create or use its own approved branch. +- Each PR may be committed and pushed during active work. +- Each PR may be opened as a draft PR during active work. +- Do not commit directly to main. +- Do not merge to main during active work unless the owner explicitly says: "Merge this PR now." +- If later PRs depend on earlier unmerged PRs, Codex must either: + - stack the dependent PRs, or + - stop and request owner approval for the dependency model. +- Codex should reduce chit-chat by planning the full sequence before starting. +- Codex must still hard-stop for conflicts, dirty worktree, scope mismatch, missing assignment, or protected instruction deletion. + +## Day Work / EOD Merge Rule + +During active work: +- Work happens on assigned team branches, OWNER branches, or scoped PR branches. +- Commits are allowed only on assigned non-main branches. +- Pushes are allowed and expected. +- Draft PRs are allowed and expected. +- Direct commits to main are prohibited. +- Merges to main are prohibited unless explicitly approved by the owner. + +At end of day: +- Owner reviews ready PRs. +- Owner explicitly approves which PRs merge. +- Only owner-approved PRs may merge to main. +- After merge, return to main and pull latest main. +- Do not treat sequential PR completion as merge approval. + +Commit/push during the day is allowed only on assigned team/OWNER/PR branches. + +Merge to main is EOD-only and owner-approved, unless the owner explicitly says: +"Merge this PR now." + +## Conflict Note + +Existing ProjectInstructions wording that appears to require immediate or automatic merge remains preserved for traceability. + +This addendum clarifies that merge to `main` remains owner-controlled. If a workflow rule appears to conflict with this addendum, stop and request explicit owner approval before merging. diff --git a/docs_build/dev/ProjectInstructions/addendums/preservation.md b/docs_build/dev/ProjectInstructions/addendums/preservation.md new file mode 100644 index 000000000..9344992c0 --- /dev/null +++ b/docs_build/dev/ProjectInstructions/addendums/preservation.md @@ -0,0 +1,42 @@ +# Preservation And Archive Governance + +## Purpose + +This addendum protects Project Instructions material from accidental deletion, rewrite, or drift. + +## Append-First Documentation + +Project Instructions documentation is append-first. + +Allowed default actions: +- add new files +- append dated notes +- append references +- add new governance addendums +- add archive snapshots + +## Owner Approval Required + +Do not delete Project Instructions material unless the owner explicitly approves deletion. + +Do not rewrite Project Instructions material unless the owner explicitly approves rewrite. + +If a requested change conflicts with existing Project Instructions, stop before editing. Explain: +- the conflicting files +- the conflicting rule text +- the requested change +- the recommended action + +Then request owner approval. + +## Archive Instead Of Delete + +When material is no longer active, archive it instead of deleting it. Archive entries must preserve enough context to explain why the material moved out of active use. + +## History Snapshots + +History snapshots go to: + +`docs_build/dev/ProjectInstructions/archive/history/CCYYMMDD_HHMMSS.md` + +Use 24-hour local time for `HHMMSS` unless the owner specifies another time basis. diff --git a/docs_build/dev/ProjectInstructions/addendums/team_release_readiness.md b/docs_build/dev/ProjectInstructions/addendums/team_release_readiness.md new file mode 100644 index 000000000..f492806d8 --- /dev/null +++ b/docs_build/dev/ProjectInstructions/addendums/team_release_readiness.md @@ -0,0 +1,31 @@ +# Team Release Readiness Gate + +## Purpose + +This gate prevents Team Alpha, Team Beta, Team Gamma, or Team OWNER from starting regular assigned work before the ProjectInstructions operating system is ready. + +## Release Rule + +Teams may start only when all of the following are true: + +- `docs_build/dev/ProjectInstructions/backlog/BACKLOG_MASTER.md` exists and is populated. +- `docs_build/dev/ProjectInstructions/team_assignments/TEAM_ASSIGNMENTS.md` exists. +- OWNER governance exists. +- One-active-branch-per-team rule exists. +- No-direct-main rule exists. +- Out-of-scope stop rule exists. +- Build Path sync rule exists. + +## Gate Outcome + +If every requirement is true, team start commands may be issued. + +If any requirement is missing, stop and report: +- missing requirement +- expected file or rule +- current branch +- recommended owner action + +## No Silent Starts + +Teams must not infer readiness from an incomplete stack. Readiness must be documented before team work begins. diff --git a/docs_build/dev/ProjectInstructions/addendums/tile_overlay_status.md b/docs_build/dev/ProjectInstructions/addendums/tile_overlay_status.md new file mode 100644 index 000000000..a1a1b75e0 --- /dev/null +++ b/docs_build/dev/ProjectInstructions/addendums/tile_overlay_status.md @@ -0,0 +1,36 @@ +# Build Path Tile Overlay Status Governance + +## Purpose + +This addendum defines visual overlay status rules for Build Path tiles. + +## Overlay Mapping + +| Backlog Status | Meaning | Tile Overlay | +| --- | --- | --- | +| `[ ]` Planned | Planned | black overlay 70% | +| `[?]` Wireframe | Wireframe | black overlay 80% | +| `[.]` Building | Building | black overlay 90% | +| `[x]` Complete | Complete | 100% transparent / no visible overlay | +| `[!]` Blocked | Blocked | yellow overlay 80% | +| `[-]` Deprecated | Deprecated | red overlay 80% | + +## Completion Denominator + +Blocked items remain in the completion denominator. + +Deprecated items are excluded from the completion denominator. + +## Badge Text + +Blocked and Deprecated tiles must show badge text. + +Badge text must be visible enough for a creator to understand why the tile is blocked or deprecated without relying on color alone. + +## Validation + +PRs that change tile overlay behavior must document: +- status mapping affected +- badge text affected +- phase percentage denominator effect +- skipped UI validation, if any, with reason diff --git a/docs_build/dev/ProjectInstructions/archive/README.md b/docs_build/dev/ProjectInstructions/archive/README.md new file mode 100644 index 000000000..dbc07a1d2 --- /dev/null +++ b/docs_build/dev/ProjectInstructions/archive/README.md @@ -0,0 +1,12 @@ +# Project Instructions Archive + +This archive retains Project Instructions reference material that is no longer active but must remain traceable. + +## Rules + +- Archive instead of delete. +- Keep archived material readable. +- Preserve original meaning and context. +- Do not rewrite archive entries unless the owner explicitly approves. +- Use `history/CCYYMMDD_HHMMSS.md` for history snapshots. +- If archive placement is unclear, stop and request owner approval. diff --git a/docs_build/dev/ProjectInstructions/archive/history/.gitkeep b/docs_build/dev/ProjectInstructions/archive/history/.gitkeep new file mode 100644 index 000000000..351adb8ef --- /dev/null +++ b/docs_build/dev/ProjectInstructions/archive/history/.gitkeep @@ -0,0 +1 @@ +Tracked placeholder for Project Instructions history snapshots. diff --git a/docs_build/dev/ProjectInstructions/backlog/BACKLOG_MASTER.md b/docs_build/dev/ProjectInstructions/backlog/BACKLOG_MASTER.md new file mode 100644 index 000000000..6ecd9bac8 --- /dev/null +++ b/docs_build/dev/ProjectInstructions/backlog/BACKLOG_MASTER.md @@ -0,0 +1,117 @@ +# BACKLOG_MASTER + +## Game Journey MVP + +### Idea + +0% Complete — Dream, brainstorm, and explore early game concepts + +- [ ] Alpha - Idea Board +- [ ] Alpha - Game Concept Notes +- [ ] Alpha - Creator Learning + +### Design + +0% Complete — Shape the game's story, structure, and systems + +- [ ] Alpha - Game Hub +- [ ] Alpha - Game Design +- [ ] Alpha - Game Configuration +- [ ] Alpha - Game Crew +- [ ] Alpha - Tags +- [ ] Beta - Messages + +### Graphics + +0% Complete — Create the visual look of your game + +- [ ] Beta - Asset Studio V2 +- [ ] Beta - Sprite Studio V2 +- [ ] Beta - Animation Studio V2 +- [ ] Beta - Palette Manager +- [ ] Beta - Video Studio + +### Audio + +0% Complete — Build sounds, music, and voices + +- [ ] Beta - Audio Studio V2 +- [ ] Beta - Audio Effects +- [ ] Beta - MIDI Studio V2 +- [ ] Beta - Messages +- [ ] Beta - Text To Speech +- [ ] Beta - Voice Profiles + +### Objects + +0% Complete — Create the things players interact with + +- [ ] Alpha - Objects +- [ ] Alpha - Characters +- [ ] Alpha - Object Behaviors + +### Worlds + +0% Complete — Build levels, maps, and places to explore + +- [ ] Alpha - Worlds +- [ ] Alpha - Environment Settings +- [ ] Alpha - Level Layouts + +### Interface + +0% Complete — Design menus, HUDs, and player screens + +- [ ] Alpha - Interface Layouts +- [ ] Alpha - Fonts +- [ ] Alpha - Languages + +### Controls + +0% Complete — Define how players interact with your game + +- [ ] Alpha - Controls +- [ ] Alpha - Input Mapping +- [ ] Alpha - Hitboxes + +### Rules + +0% Complete — Create gameplay behavior and events + +- [ ] Alpha - Events +- [ ] Alpha - Rules +- [ ] Alpha - Custom Extensions + +### Progression + +0% Complete — Build rewards, unlocks, and advancement + +- [ ] Alpha - Game Journey +- [ ] Alpha - Achievements +- [ ] Alpha - Saved Data + +### Play Test + +0% Complete — Test, debug, and improve your game + +- [ ] Alpha - Game Testing +- [ ] Alpha - Debug +- [ ] Alpha - Performance + +### Publish + +0% Complete — Prepare and release your game + +- [ ] Beta - Publish +- [ ] Beta - Build Game +- [ ] Beta - Platform Settings +- [ ] Beta - Game Migration + +### Share + +0% Complete — Grow your audience and community + +- [ ] Beta - Marketplace +- [ ] Beta - Community +- [ ] Beta - Ratings +- [ ] Beta - Cloud diff --git a/docs_build/dev/ProjectInstructions/deprecation/README.md b/docs_build/dev/ProjectInstructions/deprecation/README.md new file mode 100644 index 000000000..55c1637da --- /dev/null +++ b/docs_build/dev/ProjectInstructions/deprecation/README.md @@ -0,0 +1,20 @@ +# Deprecation Workflow + +Deprecation is its own governance group. + +Deprecated items remain traceable from backlog status through any visible Build Path representation and any later archive/removal decision. + +## Rules + +- Deprecation uses status `[-]`. +- Deprecated items are traceable. +- Owner approval is required before archive or removal. +- Deprecated Build Path items use red overlay if visible. +- Deprecated items do not count against current MVP completion. +- Deprecated items should include a note explaining replacement path, retention reason, or removal blocker. + +## Archive And Removal + +Do not archive or remove deprecated material until the owner explicitly approves. + +When approved, archive before removal whenever traceability is needed. diff --git a/docs_build/dev/ProjectInstructions/team_assignments/TEAM_ASSIGNMENTS.md b/docs_build/dev/ProjectInstructions/team_assignments/TEAM_ASSIGNMENTS.md new file mode 100644 index 000000000..0b63c376f --- /dev/null +++ b/docs_build/dev/ProjectInstructions/team_assignments/TEAM_ASSIGNMENTS.md @@ -0,0 +1,143 @@ +# TEAM_ASSIGNMENTS + +## Assignment Status Legend + +- Available: team may pull one `[ ]` backlog item when explicitly instructed. +- Active: team has one assignment in progress. +- Blocked: team cannot pull work until blocker is cleared. + +## Team Alpha + +Status: Available + +Active assignment: none. + +Active branch: none. + +## Team Beta + +Status: Available + +Active assignment: none. + +Active branch: none. + +## Team Gamma + +Status: Available + +Active assignment: none. + +Active branch: none. + +## Team OWNER + +Status: Available + +Active assignment: none. + +Active branch: none. + +## Team Name Registry + +- Team Alfa +- Team Bravo +- Team Charlie +- Team Delta +- Team Echo +- Team Foxtrot +- Team Golf +- Team Hotel +- Team India +- Team Juliett +- Team Kilo +- Team Lima +- Team Mike +- Team November +- Team Oscar +- Team Papa +- Team Quebec +- Team Romeo +- Team Sierra +- Team Tango +- Team Uniform +- Team Victor +- Team Whiskey +- Team X-ray +- Team Yankee +- Team Zulu +- Team OWNER + +## Preferred Codex Execution Method + +Preferred execution model: +Single Codex session with multiple sequential PRs. + +Purpose: +Reduce back-and-forth between owner and Codex while keeping PRs reviewable and scoped. + +Rules: +- One Codex session may execute multiple sequential PRs. +- Each PR must still have one clear purpose. +- Each PR must create its own branch. +- Each PR must be committed, pushed, and opened as a draft PR. +- Do not commit directly to main. +- Do not merge without explicit owner approval. +- If later PRs depend on earlier unmerged PRs, Codex must either: + - stack the dependent PRs, or + - stop and request owner approval for the dependency model. +- Codex should reduce chit-chat by planning the full sequence before starting. +- Codex must still hard-stop for conflicts, dirty worktree, scope mismatch, missing assignment, or protected instruction deletion. + +### All-Team Codex Execution Clarification + +Preferred execution model: +Single Codex session with multiple sequential PRs. + +Applies to: +- Team Alfa through Team Zulu +- Team OWNER + +Purpose: +Reduce back-and-forth between owner and Codex while keeping PRs reviewable and scoped. + +Rules: +- One Codex session may execute multiple sequential PRs. +- Each PR must still have one clear purpose. +- Each PR must create or use its own approved branch. +- Each PR may be committed and pushed during active work. +- Each PR may be opened as a draft PR during active work. +- Do not commit directly to main. +- Do not merge to main during active work unless the owner explicitly says: "Merge this PR now." +- If later PRs depend on earlier unmerged PRs, Codex must either: + - stack the dependent PRs, or + - stop and request owner approval for the dependency model. +- Codex should reduce chit-chat by planning the full sequence before starting. +- Codex must still hard-stop for conflicts, dirty worktree, scope mismatch, missing assignment, or protected instruction deletion. + +Conflict note: +- Older wording that says each PR must create its own branch remains preserved. +- This all-team clarification allows an approved existing team, OWNER, or scoped PR branch when the owner assigns that dependency model. +- If a branch model is unclear, owner approval is required before continuing. + +## Day Work / EOD Merge Rule + +During active work: +- Work happens on assigned team branches, OWNER branches, or scoped PR branches. +- Commits are allowed only on assigned non-main branches. +- Pushes are allowed and expected. +- Draft PRs are allowed and expected. +- Direct commits to main are prohibited. +- Merges to main are prohibited unless explicitly approved by the owner. + +At end of day: +- Owner reviews ready PRs. +- Owner explicitly approves which PRs merge. +- Only owner-approved PRs may merge to main. +- After merge, return to main and pull latest main. +- Do not treat sequential PR completion as merge approval. + +Commit/push during the day is allowed only on assigned team/OWNER/PR branches. + +Merge to main is EOD-only and owner-approved, unless the owner explicitly says: +"Merge this PR now." diff --git a/docs_build/dev/reports/PR_26172_OWNER_017-project-instructions-bootstrap-install-instruction-compliance-checklist.md b/docs_build/dev/reports/PR_26172_OWNER_017-project-instructions-bootstrap-install-instruction-compliance-checklist.md new file mode 100644 index 000000000..af8e94480 --- /dev/null +++ b/docs_build/dev/reports/PR_26172_OWNER_017-project-instructions-bootstrap-install-instruction-compliance-checklist.md @@ -0,0 +1,17 @@ +# PR_26172_OWNER_017 Instruction Compliance Checklist + +- [x] Read `docs_build/dev/PROJECT_INSTRUCTIONS.md`. +- [x] Read `docs_build/dev/PROJECT_MULTI_PC.txt`. +- [x] OWNER override documented by user. +- [x] Started from latest `main`. +- [x] Created branch `pr/26172-OWNER-017-project-instructions-bootstrap-install`. +- [x] Installed ProjectInstructions physical structure. +- [x] Created required anchor files. +- [x] Populated files with approved governance from OWNER PRs 001-016. +- [x] Did not redesign governance. +- [x] Did not create unrelated new governance. +- [x] Did not delete existing documentation. +- [x] Did not commit directly to `main`. +- [x] Did not merge any PR. +- [x] Ran docs/static validation. +- [x] Created repo-structured delta ZIP. diff --git a/docs_build/dev/reports/PR_26172_OWNER_017-project-instructions-bootstrap-install-manual-validation-notes.md b/docs_build/dev/reports/PR_26172_OWNER_017-project-instructions-bootstrap-install-manual-validation-notes.md new file mode 100644 index 000000000..4e7f24dd2 --- /dev/null +++ b/docs_build/dev/reports/PR_26172_OWNER_017-project-instructions-bootstrap-install-manual-validation-notes.md @@ -0,0 +1,12 @@ +# PR_26172_OWNER_017 Manual Validation Notes + +- Verified branch was created from latest `main`. +- Verified `docs_build/dev/ProjectInstructions/` did not exist on `main` before installation. +- Verified required physical structure exists. +- Verified required anchor files exist. +- Verified installed files preserve approved ProjectInstructions governance content. +- Verified active override wording uses OWNER. +- Verified `BACKLOG_MASTER.md` filename remains preserved. +- Verified no existing documentation was deleted. +- Verified no runtime, UI, Playwright, or sample files changed. +- Verified no merge to `main` was performed. diff --git a/docs_build/dev/reports/PR_26172_OWNER_017-project-instructions-bootstrap-install-tree.txt b/docs_build/dev/reports/PR_26172_OWNER_017-project-instructions-bootstrap-install-tree.txt new file mode 100644 index 000000000..81c6d761b --- /dev/null +++ b/docs_build/dev/reports/PR_26172_OWNER_017-project-instructions-bootstrap-install-tree.txt @@ -0,0 +1,21 @@ +docs_build/dev/ProjectInstructions/ +|-- PROJECT_INSTRUCTIONS.md +|-- README.txt +|-- TEAM_START_COMMANDS.md +|-- addendums/ +| |-- build_path_sync.md +| |-- deprecation.md +| |-- multi_team.md +| |-- preservation.md +| |-- team_release_readiness.md +| `-- tile_overlay_status.md +|-- archive/ +| |-- README.md +| `-- history/ +| `-- .gitkeep +|-- backlog/ +| `-- BACKLOG_MASTER.md +|-- deprecation/ +| `-- README.md +`-- team_assignments/ + `-- TEAM_ASSIGNMENTS.md diff --git a/docs_build/dev/reports/PR_26172_OWNER_017-project-instructions-bootstrap-install.md b/docs_build/dev/reports/PR_26172_OWNER_017-project-instructions-bootstrap-install.md new file mode 100644 index 000000000..8ecbc95af --- /dev/null +++ b/docs_build/dev/reports/PR_26172_OWNER_017-project-instructions-bootstrap-install.md @@ -0,0 +1,56 @@ +# PR_26172_OWNER_017-project-instructions-bootstrap-install + +## Purpose + +Install the missing ProjectInstructions operating system into the repository. + +This is an installation PR, not a governance-design PR. + +## Source + +The installed files use governance already approved across OWNER/Master-to-OWNER ProjectInstructions PRs 001-016: + +- ProjectInstructions root and README bootstrap +- preservation and archive governance +- backlog governance and Game Journey MVP population +- team assignments and team registry +- release readiness gate +- team start commands +- all-team Codex execution method +- Day Work / EOD Merge rule +- Build Path sync and tile overlay status governance +- deprecation workflow +- OWNER override and OWNER safety rules + +## Files Installed + +- `docs_build/dev/ProjectInstructions/README.txt` +- `docs_build/dev/ProjectInstructions/PROJECT_INSTRUCTIONS.md` +- `docs_build/dev/ProjectInstructions/TEAM_START_COMMANDS.md` +- `docs_build/dev/ProjectInstructions/addendums/build_path_sync.md` +- `docs_build/dev/ProjectInstructions/addendums/deprecation.md` +- `docs_build/dev/ProjectInstructions/addendums/multi_team.md` +- `docs_build/dev/ProjectInstructions/addendums/preservation.md` +- `docs_build/dev/ProjectInstructions/addendums/team_release_readiness.md` +- `docs_build/dev/ProjectInstructions/addendums/tile_overlay_status.md` +- `docs_build/dev/ProjectInstructions/archive/README.md` +- `docs_build/dev/ProjectInstructions/archive/history/.gitkeep` +- `docs_build/dev/ProjectInstructions/backlog/BACKLOG_MASTER.md` +- `docs_build/dev/ProjectInstructions/deprecation/README.md` +- `docs_build/dev/ProjectInstructions/team_assignments/TEAM_ASSIGNMENTS.md` + +## Validation + +- `git diff --check` +- `git diff --cached --check` +- Physical tree verification for `docs_build/dev/ProjectInstructions/` +- Targeted text verification for OWNER override, OWNER safety rules, team registry, EOD merge rule, and required anchor files + +## Skipped Lanes + +- Playwright skipped: documentation-only installation. +- Samples skipped: documentation-only installation. + +## Package + +- `tmp/PR_26172_OWNER_017-project-instructions-bootstrap-install_delta.zip` diff --git a/docs_build/dev/reports/codex_changed_files.txt b/docs_build/dev/reports/codex_changed_files.txt index 5ebd4f6a7..b0b99997b 100644 --- a/docs_build/dev/reports/codex_changed_files.txt +++ b/docs_build/dev/reports/codex_changed_files.txt @@ -1,6 +1,20 @@ -docs_build/dev/reports/PR_26171_GAMMA_027-sqlite-doc-reference-cleanup-instruction-compliance-checklist.md -docs_build/dev/reports/PR_26171_GAMMA_027-sqlite-doc-reference-cleanup-manual-validation-notes.md -docs_build/dev/reports/PR_26171_GAMMA_027-sqlite-doc-reference-cleanup.md +docs_build/dev/ProjectInstructions/PROJECT_INSTRUCTIONS.md +docs_build/dev/ProjectInstructions/README.txt +docs_build/dev/ProjectInstructions/TEAM_START_COMMANDS.md +docs_build/dev/ProjectInstructions/addendums/build_path_sync.md +docs_build/dev/ProjectInstructions/addendums/deprecation.md +docs_build/dev/ProjectInstructions/addendums/multi_team.md +docs_build/dev/ProjectInstructions/addendums/preservation.md +docs_build/dev/ProjectInstructions/addendums/team_release_readiness.md +docs_build/dev/ProjectInstructions/addendums/tile_overlay_status.md +docs_build/dev/ProjectInstructions/archive/README.md +docs_build/dev/ProjectInstructions/archive/history/.gitkeep +docs_build/dev/ProjectInstructions/backlog/BACKLOG_MASTER.md +docs_build/dev/ProjectInstructions/deprecation/README.md +docs_build/dev/ProjectInstructions/team_assignments/TEAM_ASSIGNMENTS.md +docs_build/dev/reports/PR_26172_OWNER_017-project-instructions-bootstrap-install-instruction-compliance-checklist.md +docs_build/dev/reports/PR_26172_OWNER_017-project-instructions-bootstrap-install-manual-validation-notes.md +docs_build/dev/reports/PR_26172_OWNER_017-project-instructions-bootstrap-install-tree.txt +docs_build/dev/reports/PR_26172_OWNER_017-project-instructions-bootstrap-install.md docs_build/dev/reports/codex_changed_files.txt docs_build/dev/reports/codex_review.diff -src/dev-runtime/persistence/mock-db-store.js diff --git a/docs_build/dev/reports/codex_review.diff b/docs_build/dev/reports/codex_review.diff index 88d1a78eb..5c138a708 100644 --- a/docs_build/dev/reports/codex_review.diff +++ b/docs_build/dev/reports/codex_review.diff @@ -1,138 +1,762 @@ -diff --git a/docs_build/dev/reports/PR_26171_GAMMA_027-sqlite-doc-reference-cleanup-instruction-compliance-checklist.md b/docs_build/dev/reports/PR_26171_GAMMA_027-sqlite-doc-reference-cleanup-instruction-compliance-checklist.md +diff --git a/docs_build/dev/ProjectInstructions/PROJECT_INSTRUCTIONS.md b/docs_build/dev/ProjectInstructions/PROJECT_INSTRUCTIONS.md new file mode 100644 -index 000000000..a07705200 +index 000000000..40db33c44 --- /dev/null -+++ b/docs_build/dev/reports/PR_26171_GAMMA_027-sqlite-doc-reference-cleanup-instruction-compliance-checklist.md ++++ b/docs_build/dev/ProjectInstructions/PROJECT_INSTRUCTIONS.md +@@ -0,0 +1,46 @@ ++# Project Instructions Operating System ++ ++Read `README.txt` first. ++ ++This file is the root index for the append-first Project Instructions operating system under `docs_build/dev/ProjectInstructions/`. ++ ++## Purpose ++ ++The Project Instructions operating system provides additive governance for: ++ ++- backlog ownership ++- team assignments ++- multi-team branch and scope rules ++- Build Path status synchronization ++- tile overlay status behavior ++- deprecation workflow ++- archive and history preservation ++ ++## Preservation ++ ++Existing Project Instructions remain preserved in their current locations. This operating system adds structure without deleting or rewriting existing documentation. ++ ++## Folders ++ ++- `addendums/` contains additive governance rules. ++- `backlog/` contains the central backlog file, `BACKLOG_MASTER.md`. ++- `team_assignments/` contains current team assignment records. ++- `deprecation/` contains deprecation workflow documentation. ++- `archive/` contains retained reference material. ++- `archive/history/` contains timestamped history snapshots. ++ ++## Merge Control ++ ++No PR in this operating system is merged without explicit owner approval. ++ ++## OWNER Governance ++ ++OWNER override wording: ++ ++`OWNER override approved: ` ++ ++OWNER follows the same safety rules: ++- One active OWNER branch at a time. ++- One active OWNER assignment at a time. ++- OWNER may override team locks, but may not silently delete, rewrite, or remove protected instructions. ++- OWNER override must be explicitly documented. +diff --git a/docs_build/dev/ProjectInstructions/README.txt b/docs_build/dev/ProjectInstructions/README.txt +new file mode 100644 +index 000000000..27495ad8f +--- /dev/null ++++ b/docs_build/dev/ProjectInstructions/README.txt @@ -0,0 +1,28 @@ -+# PR_26171_GAMMA_027 Instruction Compliance Checklist -+ -+## Start Gate -+ -+- PASS: Read `docs_build/dev/PROJECT_INSTRUCTIONS.md`. -+- PASS: Read `docs_build/dev/PROJECT_MULTI_PC.txt`. -+- PASS: PR name includes TEAM token `GAMMA`. -+- PASS: Branch name mirrors TEAM token: `pr/26171-GAMMA-027-sqlite-doc-reference-cleanup`. -+- PASS: Scope is diagnostics/cleanup and belongs to Team Gamma. -+- PASS: Started from fresh `main` after PR 026 merged. -+- PASS: Repository was clean before branch creation. -+ -+## Scope Guard -+ -+- PASS: One PR purpose only. -+- PASS: Cleaned active docs/seed wording only. -+- PASS: Preserved `PROJECT_INSTRUCTIONS.md` SQLite deprecation rules. -+- PASS: Did not rewrite historical PR/report archives. -+- PASS: Did not run samples. -+ -+## Completion Gate -+ -+- PASS: PR-specific report exists. -+- PASS: Manual validation notes exist. -+- PASS: Instruction compliance checklist exists. -+- PASS: `docs_build/dev/reports/codex_review.diff` exists. -+- PASS: `docs_build/dev/reports/codex_changed_files.txt` exists. -+- PASS: Repo-structured ZIP path is documented: `tmp/PR_26171_GAMMA_027-sqlite-doc-reference-cleanup_delta.zip`. -diff --git a/docs_build/dev/reports/PR_26171_GAMMA_027-sqlite-doc-reference-cleanup-manual-validation-notes.md b/docs_build/dev/reports/PR_26171_GAMMA_027-sqlite-doc-reference-cleanup-manual-validation-notes.md ++Read this file first. ++ ++Folder purpose: ++This folder is the append-first Project Instructions operating system for Game Foundry Studio. It organizes active governance, backlog, team assignment, deprecation, and history material without deleting or rewriting the existing Project Instructions files elsewhere in the repository. ++ ++Preservation rules: ++Preserve all existing documentation. Add new files or append explicit references unless the owner explicitly approves deletion or rewrite. When a conflict appears, stop, explain the conflict, and request owner approval before changing existing instruction text. ++ ++Backlog workflow: ++Backlog work is tracked under backlog/. BACKLOG_MASTER.md is the planned source for backlog item status, notes, and references. Backlog item text is treated as immutable once created; status and notes may change under the governance addendums. ++ ++Team assignment workflow: ++Team assignments are tracked under team_assignments/. A team pulls work from BACKLOG_MASTER.md, marks the item building when assigned, and records the active assignment under the owning team. Teams work only on assigned items unless an OWNER override explicitly changes the assignment. ++ ++No direct commits to main: ++Do not commit directly to main unless the owner explicitly instructs that exception. Normal work must use PR branches, draft PRs, validation evidence, and owner-controlled merge approval. ++ ++OWNER override rule: ++An OWNER override must use this wording: ++OWNER override approved: ++ ++The override must explain why normal team, branch, assignment, or backlog routing is being changed. ++ ++History snapshot rule: ++When a governance or instruction state needs a history snapshot, add a new file under archive/history/ using: ++CCYYMMDD_HHMMSS.md ++ ++Do not rewrite history snapshots after creation unless the owner explicitly approves. +diff --git a/docs_build/dev/ProjectInstructions/TEAM_START_COMMANDS.md b/docs_build/dev/ProjectInstructions/TEAM_START_COMMANDS.md +new file mode 100644 +index 000000000..3490df216 +--- /dev/null ++++ b/docs_build/dev/ProjectInstructions/TEAM_START_COMMANDS.md +@@ -0,0 +1,80 @@ ++# TEAM_START_COMMANDS ++ ++## Start Team Alpha ++ ++Ready-to-copy command: ++ ++```text ++OWNER override approved: Start Team Alpha from the ProjectInstructions release gate. ++ ++Read docs_build/dev/ProjectInstructions/README.txt first. ++Read docs_build/dev/ProjectInstructions/backlog/BACKLOG_MASTER.md. ++Read docs_build/dev/ProjectInstructions/team_assignments/TEAM_ASSIGNMENTS.md. ++ ++Pull one [ ] item for Team Alpha from BACKLOG_MASTER.md. ++Stop if Team Alpha already has an active branch. ++Stop if Team Alpha already has an active assignment. ++Stop if no [ ] Team Alpha backlog item is available. ++ ++Change the selected backlog item from [ ] to [.]. ++Add the selected assignment under Team Alpha in TEAM_ASSIGNMENTS.md. ++Create one Team Alpha branch for the selected assignment. ++Work only that assignment. ++``` ++ ++## Start Team Beta ++ ++Ready-to-copy command: ++ ++```text ++OWNER override approved: Start Team Beta from the ProjectInstructions release gate. ++ ++Read docs_build/dev/ProjectInstructions/README.txt first. ++Read docs_build/dev/ProjectInstructions/backlog/BACKLOG_MASTER.md. ++Read docs_build/dev/ProjectInstructions/team_assignments/TEAM_ASSIGNMENTS.md. ++ ++Pull one [ ] item for Team Beta from BACKLOG_MASTER.md. ++Stop if Team Beta already has an active branch. ++Stop if Team Beta already has an active assignment. ++Stop if no [ ] Team Beta backlog item is available. ++ ++Change the selected backlog item from [ ] to [.]. ++Add the selected assignment under Team Beta in TEAM_ASSIGNMENTS.md. ++Create one Team Beta branch for the selected assignment. ++Work only that assignment. ++``` ++ ++## Start Team Gamma ++ ++Ready-to-copy command: ++ ++```text ++OWNER override approved: Start Team Gamma from the ProjectInstructions release gate. ++ ++Read docs_build/dev/ProjectInstructions/README.txt first. ++Read docs_build/dev/ProjectInstructions/backlog/BACKLOG_MASTER.md. ++Read docs_build/dev/ProjectInstructions/team_assignments/TEAM_ASSIGNMENTS.md. ++ ++Pull one [ ] item for Team Gamma from BACKLOG_MASTER.md. ++Stop if Team Gamma already has an active branch. ++Stop if Team Gamma already has an active assignment. ++Stop if no [ ] Team Gamma backlog item is available. ++ ++Change the selected backlog item from [ ] to [.]. ++Add the selected assignment under Team Gamma in TEAM_ASSIGNMENTS.md. ++Create one Team Gamma branch for the selected assignment. ++Work only that assignment. ++``` ++ ++## Day Work / EOD Merge Reminder ++ ++Ready-to-copy reminder: ++ ++```text ++Commit/push during the day is allowed only on assigned team/OWNER/PR branches. ++ ++Merge to main is EOD-only and owner-approved, unless the owner explicitly says: ++"Merge this PR now." ++ ++Do not treat sequential PR completion as merge approval. ++``` +diff --git a/docs_build/dev/ProjectInstructions/addendums/build_path_sync.md b/docs_build/dev/ProjectInstructions/addendums/build_path_sync.md +new file mode 100644 +index 000000000..ad7195d1c +--- /dev/null ++++ b/docs_build/dev/ProjectInstructions/addendums/build_path_sync.md +@@ -0,0 +1,35 @@ ++# Build Path Status Sync Governance ++ ++## Purpose ++ ++This addendum keeps the central backlog and Toolbox Build Path aligned. ++ ++## Source Of Truth ++ ++`docs_build/dev/ProjectInstructions/backlog/BACKLOG_MASTER.md` is the source of truth for tool status. ++ ++## Build Path Sync ++ ++`toolbox/index.html` Build Path tiles must match tool status from `BACKLOG_MASTER.md`. ++ ++When a central backlog tool status changes, update the matching Build Path tile. ++ ++Status and Build Path changes should be in the same PR when practical. ++ ++## Phase Percentages ++ ++Phase percentages are calculated from tools in each phase. ++ ++Rules: ++- completed tools count as complete ++- planned, wireframe, building, and blocked tools remain in the denominator ++- deprecated tools are excluded from the denominator ++- phase percentage must be recalculated when a tool status changes ++ ++## Validation ++ ++PRs that change backlog status or Build Path status must document: ++- backlog item changed ++- matching Build Path tile changed ++- phase percentage before and after ++- skipped sync, if any, with reason +diff --git a/docs_build/dev/ProjectInstructions/addendums/deprecation.md b/docs_build/dev/ProjectInstructions/addendums/deprecation.md +new file mode 100644 +index 000000000..2268b30bc +--- /dev/null ++++ b/docs_build/dev/ProjectInstructions/addendums/deprecation.md +@@ -0,0 +1,32 @@ ++# Deprecation Governance ++ ++## Purpose ++ ++This addendum defines how Project Instructions backlog and Build Path items become deprecated while staying traceable. ++ ++## Deprecation Group ++ ++Deprecation is its own group and must not be hidden inside normal completion work. ++ ++## Traceability ++ ++Deprecated items must preserve: ++- original item text ++- deprecated status ++- owner approval reference ++- replacement path, if any ++- archive/removal decision, if any ++ ++## Owner Approval ++ ++Owner approval is required before archive or removal. ++ ++No team may remove a deprecated item solely because it is deprecated. ++ ++## Build Path Display ++ ++Deprecated Build Path items use red overlay if visible. ++ ++Deprecated items do not count against current MVP completion. ++ ++If a deprecated item remains visible, it must communicate Deprecated status to creators without relying on color alone. +diff --git a/docs_build/dev/ProjectInstructions/addendums/multi_team.md b/docs_build/dev/ProjectInstructions/addendums/multi_team.md +new file mode 100644 +index 000000000..373a51ed0 +--- /dev/null ++++ b/docs_build/dev/ProjectInstructions/addendums/multi_team.md +@@ -0,0 +1,55 @@ ++# Multi-Team Codex Execution Governance ++ ++## All-Team Preferred Codex Execution Method ++ ++Preferred execution model: ++Single Codex session with multiple sequential PRs. ++ ++Applies to: ++- Team Alfa through Team Zulu ++- Team OWNER ++ ++Purpose: ++Reduce back-and-forth between owner and Codex while keeping PRs reviewable and scoped. ++ ++Rules: ++- One Codex session may execute multiple sequential PRs. ++- Each PR must still have one clear purpose. ++- Each PR must create or use its own approved branch. ++- Each PR may be committed and pushed during active work. ++- Each PR may be opened as a draft PR during active work. ++- Do not commit directly to main. ++- Do not merge to main during active work unless the owner explicitly says: "Merge this PR now." ++- If later PRs depend on earlier unmerged PRs, Codex must either: ++ - stack the dependent PRs, or ++ - stop and request owner approval for the dependency model. ++- Codex should reduce chit-chat by planning the full sequence before starting. ++- Codex must still hard-stop for conflicts, dirty worktree, scope mismatch, missing assignment, or protected instruction deletion. ++ ++## Day Work / EOD Merge Rule ++ ++During active work: ++- Work happens on assigned team branches, OWNER branches, or scoped PR branches. ++- Commits are allowed only on assigned non-main branches. ++- Pushes are allowed and expected. ++- Draft PRs are allowed and expected. ++- Direct commits to main are prohibited. ++- Merges to main are prohibited unless explicitly approved by the owner. ++ ++At end of day: ++- Owner reviews ready PRs. ++- Owner explicitly approves which PRs merge. ++- Only owner-approved PRs may merge to main. ++- After merge, return to main and pull latest main. ++- Do not treat sequential PR completion as merge approval. ++ ++Commit/push during the day is allowed only on assigned team/OWNER/PR branches. ++ ++Merge to main is EOD-only and owner-approved, unless the owner explicitly says: ++"Merge this PR now." ++ ++## Conflict Note ++ ++Existing ProjectInstructions wording that appears to require immediate or automatic merge remains preserved for traceability. ++ ++This addendum clarifies that merge to `main` remains owner-controlled. If a workflow rule appears to conflict with this addendum, stop and request explicit owner approval before merging. +diff --git a/docs_build/dev/ProjectInstructions/addendums/preservation.md b/docs_build/dev/ProjectInstructions/addendums/preservation.md +new file mode 100644 +index 000000000..9344992c0 +--- /dev/null ++++ b/docs_build/dev/ProjectInstructions/addendums/preservation.md +@@ -0,0 +1,42 @@ ++# Preservation And Archive Governance ++ ++## Purpose ++ ++This addendum protects Project Instructions material from accidental deletion, rewrite, or drift. ++ ++## Append-First Documentation ++ ++Project Instructions documentation is append-first. ++ ++Allowed default actions: ++- add new files ++- append dated notes ++- append references ++- add new governance addendums ++- add archive snapshots ++ ++## Owner Approval Required ++ ++Do not delete Project Instructions material unless the owner explicitly approves deletion. ++ ++Do not rewrite Project Instructions material unless the owner explicitly approves rewrite. ++ ++If a requested change conflicts with existing Project Instructions, stop before editing. Explain: ++- the conflicting files ++- the conflicting rule text ++- the requested change ++- the recommended action ++ ++Then request owner approval. ++ ++## Archive Instead Of Delete ++ ++When material is no longer active, archive it instead of deleting it. Archive entries must preserve enough context to explain why the material moved out of active use. ++ ++## History Snapshots ++ ++History snapshots go to: ++ ++`docs_build/dev/ProjectInstructions/archive/history/CCYYMMDD_HHMMSS.md` ++ ++Use 24-hour local time for `HHMMSS` unless the owner specifies another time basis. +diff --git a/docs_build/dev/ProjectInstructions/addendums/team_release_readiness.md b/docs_build/dev/ProjectInstructions/addendums/team_release_readiness.md new file mode 100644 -index 000000000..415d83d27 +index 000000000..f492806d8 --- /dev/null -+++ b/docs_build/dev/reports/PR_26171_GAMMA_027-sqlite-doc-reference-cleanup-manual-validation-notes.md -@@ -0,0 +1,17 @@ -+# PR_26171_GAMMA_027 Manual Validation Notes ++++ b/docs_build/dev/ProjectInstructions/addendums/team_release_readiness.md +@@ -0,0 +1,31 @@ ++# Team Release Readiness Gate ++ ++## Purpose ++ ++This gate prevents Team Alpha, Team Beta, Team Gamma, or Team OWNER from starting regular assigned work before the ProjectInstructions operating system is ready. + -+Manual validation focused on active docs/seed wording. ++## Release Rule + -+## Notes ++Teams may start only when all of the following are true: + -+- Confirmed PR 027 branch was created from fresh `main` after PR 026 merged. -+- Confirmed `PROJECT_INSTRUCTIONS.md` deprecation rules were preserved. -+- Confirmed historical report and PR docs were not modified. -+- Confirmed the only active seed wording change was the Local DB session-mode description. -+- Confirmed remaining SQLite references in active paths are governance, validation guards, negative tests, or legacy data-preservation guard text. ++- `docs_build/dev/ProjectInstructions/backlog/BACKLOG_MASTER.md` exists and is populated. ++- `docs_build/dev/ProjectInstructions/team_assignments/TEAM_ASSIGNMENTS.md` exists. ++- OWNER governance exists. ++- One-active-branch-per-team rule exists. ++- No-direct-main rule exists. ++- Out-of-scope stop rule exists. ++- Build Path sync rule exists. + -+## Skipped ++## Gate Outcome + -+- Playwright was skipped because no UI behavior changed. -+- Samples were skipped by request. -+- Broad tests were skipped because this is a wording-only cleanup. -diff --git a/docs_build/dev/reports/PR_26171_GAMMA_027-sqlite-doc-reference-cleanup.md b/docs_build/dev/reports/PR_26171_GAMMA_027-sqlite-doc-reference-cleanup.md ++If every requirement is true, team start commands may be issued. ++ ++If any requirement is missing, stop and report: ++- missing requirement ++- expected file or rule ++- current branch ++- recommended owner action ++ ++## No Silent Starts ++ ++Teams must not infer readiness from an incomplete stack. Readiness must be documented before team work begins. +diff --git a/docs_build/dev/ProjectInstructions/addendums/tile_overlay_status.md b/docs_build/dev/ProjectInstructions/addendums/tile_overlay_status.md new file mode 100644 -index 000000000..ecb1a233d +index 000000000..a1a1b75e0 --- /dev/null -+++ b/docs_build/dev/reports/PR_26171_GAMMA_027-sqlite-doc-reference-cleanup.md -@@ -0,0 +1,43 @@ -+# PR_26171_GAMMA_027-sqlite-doc-reference-cleanup ++++ b/docs_build/dev/ProjectInstructions/addendums/tile_overlay_status.md +@@ -0,0 +1,36 @@ ++# Build Path Tile Overlay Status Governance ++ ++## Purpose ++ ++This addendum defines visual overlay status rules for Build Path tiles. ++ ++## Overlay Mapping ++ ++| Backlog Status | Meaning | Tile Overlay | ++| --- | --- | --- | ++| `[ ]` Planned | Planned | black overlay 70% | ++| `[?]` Wireframe | Wireframe | black overlay 80% | ++| `[.]` Building | Building | black overlay 90% | ++| `[x]` Complete | Complete | 100% transparent / no visible overlay | ++| `[!]` Blocked | Blocked | yellow overlay 80% | ++| `[-]` Deprecated | Deprecated | red overlay 80% | + -+TEAM ownership: GAMMA. ++## Completion Denominator + -+## Scope ++Blocked items remain in the completion denominator. + -+Clean active docs/seed wording that implied SQLite is still an active persistence target. ++Deprecated items are excluded from the completion denominator. + -+## Changes ++## Badge Text + -+- Updated `src/dev-runtime/persistence/mock-db-store.js` session-mode description from SQLite-backed wording to neutral Local DB adapter wording. -+- Preserved `PROJECT_INSTRUCTIONS.md` SQLite deprecation rules. -+- Did not rewrite historical PR/report archives. -+- Did not remove governance, validation guard, negative test, or legacy data-preservation references. ++Blocked and Deprecated tiles must show badge text. ++ ++Badge text must be visible enough for a creator to understand why the tile is blocked or deprecated without relying on color alone. + +## Validation + -+Passed: -+- `git diff --check` -+- `node --check src/dev-runtime/persistence/mock-db-store.js` -+- Targeted text check confirmed no active docs/seed wording still says `SQLite-backed`, `SQLite persistence`, `SQLite service`, or `backed by server SQLite storage`. -+- Scoped active-source search confirmed remaining non-archive SQLite references are limited to: -+ - governance rules in `PROJECT_INSTRUCTIONS.md` -+ - validation guard patterns in `scripts/validate-browser-env-agnostic.mjs` -+ - negative test assertions that SQLite is not exposed -+ - Game Journey legacy SQLite data-preservation guard -+ -+Skipped: -+- Playwright: no UI/runtime behavior changed. -+- Samples: skipped by request. -+- Historical reports and PR docs: explicitly out of scope. -+ -+## Reports -+ -+- `docs_build/dev/reports/codex_review.diff` -+- `docs_build/dev/reports/codex_changed_files.txt` -+- `docs_build/dev/reports/PR_26171_GAMMA_027-sqlite-doc-reference-cleanup.md` -+- `docs_build/dev/reports/PR_26171_GAMMA_027-sqlite-doc-reference-cleanup-manual-validation-notes.md` -+- `docs_build/dev/reports/PR_26171_GAMMA_027-sqlite-doc-reference-cleanup-instruction-compliance-checklist.md` -+ -+## ZIP -+ -+`tmp/PR_26171_GAMMA_027-sqlite-doc-reference-cleanup_delta.zip` -diff --git a/docs_build/dev/reports/codex_changed_files.txt b/docs_build/dev/reports/codex_changed_files.txt -index 4e23ae82e..5ebd4f6a7 100644 ---- a/docs_build/dev/reports/codex_changed_files.txt -+++ b/docs_build/dev/reports/codex_changed_files.txt -@@ -1,10 +1,6 @@ --docs_build/dev/reports/PR_26171_GAMMA_026-sqlite-test-reference-cleanup-instruction-compliance-checklist.md --docs_build/dev/reports/PR_26171_GAMMA_026-sqlite-test-reference-cleanup-manual-validation-notes.md --docs_build/dev/reports/PR_26171_GAMMA_026-sqlite-test-reference-cleanup.md -+docs_build/dev/reports/PR_26171_GAMMA_027-sqlite-doc-reference-cleanup-instruction-compliance-checklist.md -+docs_build/dev/reports/PR_26171_GAMMA_027-sqlite-doc-reference-cleanup-manual-validation-notes.md -+docs_build/dev/reports/PR_26171_GAMMA_027-sqlite-doc-reference-cleanup.md - docs_build/dev/reports/codex_changed_files.txt - docs_build/dev/reports/codex_review.diff --tests/dev-runtime/DbSeedIntegrity.test.mjs --tests/playwright/tools/AdminDbViewer.spec.mjs --tests/playwright/tools/BrowserApiUrlConfig.spec.mjs --tests/playwright/tools/GameJourneyTool.spec.mjs --tests/playwright/tools/LoginSessionMode.spec.mjs -+src/dev-runtime/persistence/mock-db-store.js -diff --git a/src/dev-runtime/persistence/mock-db-store.js b/src/dev-runtime/persistence/mock-db-store.js -index 2305910bc..c98c915b5 100644 ---- a/src/dev-runtime/persistence/mock-db-store.js -+++ b/src/dev-runtime/persistence/mock-db-store.js -@@ -23,7 +23,7 @@ export const MOCK_DB_SESSION_MODES = Object.freeze([ - adapterId: "local-db", - adapterName: "LocalDbAdapter", - configured: true, -- description: "Uses LocalDbAdapter backed by server SQLite storage.", -+ description: "Uses the Local DB adapter behind the server API boundary.", - environment: "Local DB", - id: "local-db", - label: "Local DB", ++PRs that change tile overlay behavior must document: ++- status mapping affected ++- badge text affected ++- phase percentage denominator effect ++- skipped UI validation, if any, with reason +diff --git a/docs_build/dev/ProjectInstructions/archive/README.md b/docs_build/dev/ProjectInstructions/archive/README.md +new file mode 100644 +index 000000000..dbc07a1d2 +--- /dev/null ++++ b/docs_build/dev/ProjectInstructions/archive/README.md +@@ -0,0 +1,12 @@ ++# Project Instructions Archive ++ ++This archive retains Project Instructions reference material that is no longer active but must remain traceable. ++ ++## Rules ++ ++- Archive instead of delete. ++- Keep archived material readable. ++- Preserve original meaning and context. ++- Do not rewrite archive entries unless the owner explicitly approves. ++- Use `history/CCYYMMDD_HHMMSS.md` for history snapshots. ++- If archive placement is unclear, stop and request owner approval. +diff --git a/docs_build/dev/ProjectInstructions/archive/history/.gitkeep b/docs_build/dev/ProjectInstructions/archive/history/.gitkeep +new file mode 100644 +index 000000000..351adb8ef +--- /dev/null ++++ b/docs_build/dev/ProjectInstructions/archive/history/.gitkeep +@@ -0,0 +1 @@ ++Tracked placeholder for Project Instructions history snapshots. +diff --git a/docs_build/dev/ProjectInstructions/backlog/BACKLOG_MASTER.md b/docs_build/dev/ProjectInstructions/backlog/BACKLOG_MASTER.md +new file mode 100644 +index 000000000..6ecd9bac8 +--- /dev/null ++++ b/docs_build/dev/ProjectInstructions/backlog/BACKLOG_MASTER.md +@@ -0,0 +1,117 @@ ++# BACKLOG_MASTER ++ ++## Game Journey MVP ++ ++### Idea ++ ++0% Complete — Dream, brainstorm, and explore early game concepts ++ ++- [ ] Alpha - Idea Board ++- [ ] Alpha - Game Concept Notes ++- [ ] Alpha - Creator Learning ++ ++### Design ++ ++0% Complete — Shape the game's story, structure, and systems ++ ++- [ ] Alpha - Game Hub ++- [ ] Alpha - Game Design ++- [ ] Alpha - Game Configuration ++- [ ] Alpha - Game Crew ++- [ ] Alpha - Tags ++- [ ] Beta - Messages ++ ++### Graphics ++ ++0% Complete — Create the visual look of your game ++ ++- [ ] Beta - Asset Studio V2 ++- [ ] Beta - Sprite Studio V2 ++- [ ] Beta - Animation Studio V2 ++- [ ] Beta - Palette Manager ++- [ ] Beta - Video Studio ++ ++### Audio ++ ++0% Complete — Build sounds, music, and voices ++ ++- [ ] Beta - Audio Studio V2 ++- [ ] Beta - Audio Effects ++- [ ] Beta - MIDI Studio V2 ++- [ ] Beta - Messages ++- [ ] Beta - Text To Speech ++- [ ] Beta - Voice Profiles ++ ++### Objects ++ ++0% Complete — Create the things players interact with ++ ++- [ ] Alpha - Objects ++- [ ] Alpha - Characters ++- [ ] Alpha - Object Behaviors ++ ++### Worlds ++ ++0% Complete — Build levels, maps, and places to explore ++ ++- [ ] Alpha - Worlds ++- [ ] Alpha - Environment Settings ++- [ ] Alpha - Level Layouts ++ ++### Interface ++ ++0% Complete — Design menus, HUDs, and player screens ++ ++- [ ] Alpha - Interface Layouts ++- [ ] Alpha - Fonts ++- [ ] Alpha - Languages ++ ++### Controls ++ ++0% Complete — Define how players interact with your game ++ ++- [ ] Alpha - Controls ++- [ ] Alpha - Input Mapping ++- [ ] Alpha - Hitboxes ++ ++### Rules ++ ++0% Complete — Create gameplay behavior and events ++ ++- [ ] Alpha - Events ++- [ ] Alpha - Rules ++- [ ] Alpha - Custom Extensions ++ ++### Progression ++ ++0% Complete — Build rewards, unlocks, and advancement ++ ++- [ ] Alpha - Game Journey ++- [ ] Alpha - Achievements ++- [ ] Alpha - Saved Data ++ ++### Play Test ++ ++0% Complete — Test, debug, and improve your game ++ ++- [ ] Alpha - Game Testing ++- [ ] Alpha - Debug ++- [ ] Alpha - Performance ++ ++### Publish ++ ++0% Complete — Prepare and release your game ++ ++- [ ] Beta - Publish ++- [ ] Beta - Build Game ++- [ ] Beta - Platform Settings ++- [ ] Beta - Game Migration ++ ++### Share ++ ++0% Complete — Grow your audience and community ++ ++- [ ] Beta - Marketplace ++- [ ] Beta - Community ++- [ ] Beta - Ratings ++- [ ] Beta - Cloud +diff --git a/docs_build/dev/ProjectInstructions/deprecation/README.md b/docs_build/dev/ProjectInstructions/deprecation/README.md +new file mode 100644 +index 000000000..55c1637da +--- /dev/null ++++ b/docs_build/dev/ProjectInstructions/deprecation/README.md +@@ -0,0 +1,20 @@ ++# Deprecation Workflow ++ ++Deprecation is its own governance group. ++ ++Deprecated items remain traceable from backlog status through any visible Build Path representation and any later archive/removal decision. ++ ++## Rules ++ ++- Deprecation uses status `[-]`. ++- Deprecated items are traceable. ++- Owner approval is required before archive or removal. ++- Deprecated Build Path items use red overlay if visible. ++- Deprecated items do not count against current MVP completion. ++- Deprecated items should include a note explaining replacement path, retention reason, or removal blocker. ++ ++## Archive And Removal ++ ++Do not archive or remove deprecated material until the owner explicitly approves. ++ ++When approved, archive before removal whenever traceability is needed. +diff --git a/docs_build/dev/ProjectInstructions/team_assignments/TEAM_ASSIGNMENTS.md b/docs_build/dev/ProjectInstructions/team_assignments/TEAM_ASSIGNMENTS.md +new file mode 100644 +index 000000000..0b63c376f +--- /dev/null ++++ b/docs_build/dev/ProjectInstructions/team_assignments/TEAM_ASSIGNMENTS.md +@@ -0,0 +1,143 @@ ++# TEAM_ASSIGNMENTS ++ ++## Assignment Status Legend ++ ++- Available: team may pull one `[ ]` backlog item when explicitly instructed. ++- Active: team has one assignment in progress. ++- Blocked: team cannot pull work until blocker is cleared. ++ ++## Team Alpha ++ ++Status: Available ++ ++Active assignment: none. ++ ++Active branch: none. ++ ++## Team Beta ++ ++Status: Available ++ ++Active assignment: none. ++ ++Active branch: none. ++ ++## Team Gamma ++ ++Status: Available ++ ++Active assignment: none. ++ ++Active branch: none. ++ ++## Team OWNER ++ ++Status: Available ++ ++Active assignment: none. ++ ++Active branch: none. ++ ++## Team Name Registry ++ ++- Team Alfa ++- Team Bravo ++- Team Charlie ++- Team Delta ++- Team Echo ++- Team Foxtrot ++- Team Golf ++- Team Hotel ++- Team India ++- Team Juliett ++- Team Kilo ++- Team Lima ++- Team Mike ++- Team November ++- Team Oscar ++- Team Papa ++- Team Quebec ++- Team Romeo ++- Team Sierra ++- Team Tango ++- Team Uniform ++- Team Victor ++- Team Whiskey ++- Team X-ray ++- Team Yankee ++- Team Zulu ++- Team OWNER ++ ++## Preferred Codex Execution Method ++ ++Preferred execution model: ++Single Codex session with multiple sequential PRs. ++ ++Purpose: ++Reduce back-and-forth between owner and Codex while keeping PRs reviewable and scoped. ++ ++Rules: ++- One Codex session may execute multiple sequential PRs. ++- Each PR must still have one clear purpose. ++- Each PR must create its own branch. ++- Each PR must be committed, pushed, and opened as a draft PR. ++- Do not commit directly to main. ++- Do not merge without explicit owner approval. ++- If later PRs depend on earlier unmerged PRs, Codex must either: ++ - stack the dependent PRs, or ++ - stop and request owner approval for the dependency model. ++- Codex should reduce chit-chat by planning the full sequence before starting. ++- Codex must still hard-stop for conflicts, dirty worktree, scope mismatch, missing assignment, or protected instruction deletion. ++ ++### All-Team Codex Execution Clarification ++ ++Preferred execution model: ++Single Codex session with multiple sequential PRs. ++ ++Applies to: ++- Team Alfa through Team Zulu ++- Team OWNER ++ ++Purpose: ++Reduce back-and-forth between owner and Codex while keeping PRs reviewable and scoped. ++ ++Rules: ++- One Codex session may execute multiple sequential PRs. ++- Each PR must still have one clear purpose. ++- Each PR must create or use its own approved branch. ++- Each PR may be committed and pushed during active work. ++- Each PR may be opened as a draft PR during active work. ++- Do not commit directly to main. ++- Do not merge to main during active work unless the owner explicitly says: "Merge this PR now." ++- If later PRs depend on earlier unmerged PRs, Codex must either: ++ - stack the dependent PRs, or ++ - stop and request owner approval for the dependency model. ++- Codex should reduce chit-chat by planning the full sequence before starting. ++- Codex must still hard-stop for conflicts, dirty worktree, scope mismatch, missing assignment, or protected instruction deletion. ++ ++Conflict note: ++- Older wording that says each PR must create its own branch remains preserved. ++- This all-team clarification allows an approved existing team, OWNER, or scoped PR branch when the owner assigns that dependency model. ++- If a branch model is unclear, owner approval is required before continuing. ++ ++## Day Work / EOD Merge Rule ++ ++During active work: ++- Work happens on assigned team branches, OWNER branches, or scoped PR branches. ++- Commits are allowed only on assigned non-main branches. ++- Pushes are allowed and expected. ++- Draft PRs are allowed and expected. ++- Direct commits to main are prohibited. ++- Merges to main are prohibited unless explicitly approved by the owner. ++ ++At end of day: ++- Owner reviews ready PRs. ++- Owner explicitly approves which PRs merge. ++- Only owner-approved PRs may merge to main. ++- After merge, return to main and pull latest main. ++- Do not treat sequential PR completion as merge approval. ++ ++Commit/push during the day is allowed only on assigned team/OWNER/PR branches. ++ ++Merge to main is EOD-only and owner-approved, unless the owner explicitly says: ++"Merge this PR now."