Align Project Instructions workflow and testability governance

Author: ToolboxAid

docs_build/dev/ProjectInstructions/addendums/branch_lock_governance.md

@@ -13,7 +13,7 @@ Keep active work attached to the correct assigned team, branch, and OWNER decisi
 - An assigned work item keeps its owner of record until complete or OWNER reassignment.
 - Work must not move to another team, branch, or PR without OWNER approval.
 - A team with no active assignment, active branch, or active PR is inactive.
-- A team with a previous PR that is not Closed must not begin another PR unless OWNER documented an explicit stacked PR chain.
+- A team with a previous PR that is not Closed must not begin another unrelated PR unless OWNER documented an explicit stacked/sequential workstream.
 - PR Open begins only after the branch and PR identity are named.
 - Plan, Build, validation, reports, ZIP packaging, and closeout stay tied to the same PR identity and source branch.
 - Closed ends only after the final main-return, clean-worktree, local/origin `0/0`, no-untracked-files, required-report, required-ZIP, backlog, applicable tool-state, and branch-disposition gates pass.
@@ -25,7 +25,8 @@ Keep active work attached to the correct assigned team, branch, and OWNER decisi
 - Pull latest `origin/main` before creating a work branch.
 - Do not create a PR branch unless current branch is `main`, worktree is clean, `main...origin/main` is `0 0`, and `HEAD` SHA matches the published EOD SHA.
 - Follow the canonical START / WORK / END lifecycle in `docs_build/dev/ProjectInstructions/addendums/project_instructions_single_source_eod_lock.md`.
-- Keep work on the active branch until the PR is merged, the branch is retired, or OWNER says to return to `main`.
+- Keep work on the active branch until the PR is merged, the branch is retired, EOD closeout begins, or OWNER says to return to `main`.
+- For OWNER-approved stacked/sequential workstreams, sequential PR work stays on the active branch/workstream during the day and does not return to `main` between PRs.
 - Do not commit directly to `main`.
 - HARD STOP before committing if current branch is `main`.
 - HARD STOP if the branch changes unexpectedly during implementation.
@@ -51,7 +52,7 @@ Branch lock governance enforces:
 - START on synchronized `main`.
 - WORK only on the PR branch.
 - END by merging, returning to synchronized `main`, publishing branch, HEAD SHA, and date/time, then stopping all work.
-- Mandatory hard stops before commits on `main`, dirty branch creation, non-`0 0` main sync, baseline SHA mismatch, unvalidated merge, or new PR work before synchronized main return.
+- Mandatory hard stops before commits on `main`, dirty branch creation, non-`0 0` main sync, baseline SHA mismatch, unvalidated merge, or new unrelated workstream before synchronized main return.
 
 ## OWNER Override
 

docs_build/dev/ProjectInstructions/addendums/environment_configuration_standards.md

@@ -92,6 +92,8 @@ One shared API/service contract is required across Local (VS Code), DEV, IST, UA
 
 Rules:
 
+- Browser/UI/runtime code must follow `Browser -> API -> Database` for authoritative product data.
+- `Local API` means the same shared API/service contract running locally, not a separate local-only API implementation.
 - API URLs may differ by `.env` only.
 - Do not split Local API and Public API contracts.
 - Do not create environment-specific API/service contracts.

docs_build/dev/ProjectInstructions/addendums/environment_governance_model.md

@@ -48,7 +48,9 @@ One shared API/service contract is required across all environments.
 
 Rules:
 
+- Browser/UI/runtime product data must flow through `Browser -> API -> Database`.
 - Browser/UI/runtime code must consume the same API/service contract in Local (VS Code), DEV, IST, UAT, and PROD.
+- `Local API` means the shared API/service contract running locally, not a separate API implementation.
 - Environment-specific endpoints, keys, buckets, credentials, and prefixes are configuration values only.
 - Do not create environment-specific API/service contracts.
 - Do not branch API/service behavior by environment name.

docs_build/dev/ProjectInstructions/addendums/no_mock_repository_runtime_source.md

@@ -11,6 +11,12 @@ Browser → API → Database
 
 Runtime product data must flow through the API/service contract backed by the database.
 
+Canonical ASCII wording for this required flow is:
+
+```text
+Browser -> API -> Database
+```
+
 ## Rules
 
 - Mock repositories are 100% technical debt.

docs_build/dev/ProjectInstructions/addendums/pr_workflow.md

@@ -23,9 +23,26 @@ Define the standard pull request workflow for Game Foundry Studio.
 12. Review the PR.
 13. OWNER approves merge.
 14. Merge to main.
-15. Pull latest main before starting the next PR.
+15. Pull latest main before starting the next unrelated workstream, or before a new PR when the work is not an OWNER-approved stacked/sequential workstream.
 16. Verify Main Verified and Closed gates.
 
+## Daily Branch Workflow
+
+OWNER-approved daily workflow:
+
+- SOD starts from the latest synchronized `main`.
+- SOD creates or updates one active team, OWNER, or scoped workstream branch.
+- All implementation commits go to the active branch, not `main`.
+- Sequential PRs stay on the active branch/workstream during the day when OWNER assigned a stacked or sequential workstream.
+- Do not return to `main` between stacked/sequential PRs in the same active workstream.
+- `main` is only the SOD baseline and the EOD return target, unless OWNER explicitly approves an intermediate merge checkpoint.
+- EOD merges or closes OWNER-approved work, pushes, returns to `main`, and verifies:
+  - current branch is `main`
+  - worktree clean
+  - local/origin sync is `0 0`
+
+This section supersedes older active wording that implies returning to `main` between every PR inside an OWNER-approved stacked/sequential workstream.
+
 ## Branch Lifecycle (Canonical)
 
 Every PR follows exactly three phases:
@@ -101,7 +118,8 @@ Closed gates:
 - Source branches are retained by default after merge and closeout.
 - Do not mix unrelated scopes.
 - Do not start dependent PRs until the required base PR is merged.
-- Always return to main before starting the next PR.
+- Return to `main` before starting an unrelated PR or new workstream.
+- Do not return to `main` between PRs in the same OWNER-approved stacked/sequential workstream unless OWNER approves an EOD or intermediate merge checkpoint.
 - A team must not begin another PR if its previous PR is not Closed.
 - Exception is allowed only for explicitly documented stacked PR chains.
 - If validation fails, stop and report.
@@ -140,6 +158,29 @@ Each tool MVP PR plan or template must include:
 
 Visible acceptance must be Creator-facing first. Architecture can be handled under the covers, but the PR purpose must be user-testable.
 
+## Product Owner Testable Definition
+
+A request to complete a page, tool, or testable MVP means Product Owner testable.
+
+Not acceptable as a completed/testable page or tool:
+
+- shell-only page
+- `Not implemented yet`
+- placeholder-only workspace, inspector, or output sections
+- planned-only tile
+- template-only page
+- route that loads but cannot be used
+
+Required for Product Owner testable completion:
+
+- visible working controls
+- API-backed data where required
+- validation and error states
+- empty states
+- save/load behavior where applicable
+- manual validation steps for Product Owner
+- targeted Playwright coverage where impacted.
+
 ## OWNER Shortcut: PRs
 
 Keyword:

docs_build/dev/ProjectInstructions/addendums/project_instructions_single_source_eod_lock.md

@@ -68,7 +68,7 @@ END
 
 ## START
 
-Every team begins on `main`.
+Every team begins SOD from `main`.
 
 Required:
 
@@ -91,7 +91,7 @@ main...origin/main
 HEAD equals published EOD SHA
 ```
 
-Only after ALL four pass may a branch be created.
+Only after ALL four pass may a branch be created or the active OWNER-approved workstream branch be updated.
 
 Create the PR branch:
 
@@ -115,6 +115,8 @@ From branch creation until merge:
 - Push only the PR branch.
 - Execute validation from the PR branch.
 - Open/update the PR from the PR branch.
+- For OWNER-approved stacked/sequential workstreams, remain on the active workstream branch between sequential PRs during the day.
+- Do not return to `main` between sequential PRs in the same active workstream unless OWNER explicitly approves an EOD or intermediate merge checkpoint.
 
 Hard Stops:
 
@@ -192,7 +194,8 @@ STOP if:
 - `main...origin/main` is not `0 0` before creating PR branch
 - `HEAD` SHA differs from published baseline
 - merge attempted without successful validation
-- new PR started before returning to synchronized `main`
+- new unrelated PR or workstream started before returning to synchronized `main`
+- sequential work continues without an OWNER-approved stacked/sequential workstream model
 
 ## Start Of Day Boundary
 

docs_build/dev/ProjectInstructions/addendums/test_structure_standardization.md

@@ -6,6 +6,9 @@ Standardize testing locations and ensure independent tool validation.
 
 ## Canonical Test Structure
 
+Page-level Playwright tests:
+- tests/playwright/{runtime-page-path}/index.spec.mjs
+
 Tool tests:
 - tests/toolbox/{tool-name}/
 
@@ -31,3 +34,36 @@ Regression tests:
 - Tool tests validate tool functionality.
 - Regression tests validate platform behavior.
 - New tests follow the canonical structure.
+- Every user-accessible page must have at least one page-level Playwright test.
+- Runtime page path determines the page-level Playwright test path.
+- Primary page-level Playwright test file should be `index.spec.mjs`.
+- Do not organize new page-level Playwright tests only by feature nickname or technology bucket when a page path exists.
+- Legacy broad tests may remain while migration is planned; document migration/deprecation instead of moving broad legacy tests unless the PR scope requires it.
+
+## Page-Level Playwright Examples
+
+- `/admin/index.html` -> `tests/playwright/admin/index/index.spec.mjs`
+- `/toolbox/sprites/index.html` -> `tests/playwright/toolbox/sprites/index.spec.mjs`
+- `/toolbox/game-hub/index.html` -> `tests/playwright/toolbox/game-hub/index.spec.mjs`
+- `/toolbox/messages/index.html` -> `tests/playwright/toolbox/messages/index.spec.mjs`
+- `/toolbox/game-configuration/index.html` -> `tests/playwright/toolbox/game-configuration/index.spec.mjs`
+
+## Minimum Page-Level Playwright Coverage
+
+Minimum page-level test:
+
+- route loads
+- page renders
+- navigation works
+- no visible placeholder-only state for completed/testable pages
+- no runtime console errors when feasible
+
+Additional scenario files may use:
+
+- `create.spec.mjs`
+- `edit.spec.mjs`
+- `delete.spec.mjs`
+- `archive.spec.mjs`
+- `navigation.spec.mjs`
+- `permissions.spec.mjs`
+- `validation.spec.mjs`

docs_build/dev/ProjectInstructions/addendums/tool_mvp_stacked_pr_standard.md

@@ -40,6 +40,27 @@ For tool MVP PR planning, visible acceptance must be Creator-facing first.
 
 Architecture can be handled under the covers, but PR purpose must be user-testable.
 
+A request to complete a page, tool, or testable MVP means Product Owner testable.
+
+Not acceptable as complete/testable:
+
+- shell-only page
+- `Not implemented yet`
+- placeholder-only workspace, inspector, or output sections
+- planned-only tile
+- template-only page
+- route that loads but cannot be used
+
+Required for Product Owner testable completion:
+
+- visible working controls
+- API-backed data where required
+- validation and error states
+- empty states
+- save/load behavior where applicable
+- manual validation steps for Product Owner
+- targeted Playwright coverage where impacted.
+
 Each tool MVP PR must state:
 - Creator-testable outcome
 - What Playwright tests
@@ -81,4 +102,6 @@ Each PR in the stack still follows the canonical START / WORK / END lifecycle an
 
 When OWNER gives one large Codex command for a tool MVP stack, Codex may continue from one completed PR to the next without stopping for a conversational checkpoint, unless a blocker listed in this standard occurs.
 
-The final PR in the stack must perform normal closeout and stop all work after returning to synchronized main.
+During an OWNER-approved day workstream, sequential PRs stay on the active workstream branch and do not return to `main` between PRs.
+
+The final PR in the stack must perform normal EOD closeout or OWNER-approved merge-checkpoint closeout and stop all work after returning to synchronized main.

docs_build/dev/ProjectInstructions/backlog/BACKLOG_MASTER.md

@@ -26,7 +26,10 @@
 0% Complete — Create the visual look of your game
 
 - [ ] Bravo - Asset Studio V2
-- [ ] Bravo - Sprite Studio V2
+- [ ] Charlie - Sprites canvas editor MVP
+  - Sprites is a creator tool, not only an asset metadata library.
+  - MVP requires canvas/grid editor behavior, width/height controls, Palette/Colors-only reusable colors, color selection from Palette/Colors, pixel painting, save/load sprite grid data through the API/database, and Product Owner manual validation.
+  - Category is removed from Sprites MVP planning.
 - [ ] Bravo - Animation Studio V2
 - [ ] Bravo - Palette Manager
 - [ ] Bravo - Video Studio

docs_build/dev/ProjectInstructions/team_assignments/TEAM_ASSIGNMENTS.md

@@ -48,15 +48,11 @@ Current OWNER clarification:
 
 ## Team Alfa
 
-Status: Active
-
-Active assignment: PR_26177_DELTA_056-shared-validation-assertions.
-
-Active branch: PR_26177_DELTA_056-shared-validation-assertions.
+Status: Available
 
-Active PR: PR_26177_DELTA_056-shared-validation-assertions.
+Active assignment: none.
 
-OWNER override approved: Continue Team Delta random utility stack with PR_26177_DELTA_056-shared-validation-assertions.
+Active branch: none.
 
 ## Team Bravo
 
@@ -76,11 +72,15 @@ Active branch: none.
 
 ## Team Delta
 
-Status: Available
+Status: Active
 
-Active assignment: none.
+Active assignment: PR_26177_DELTA_056-shared-validation-assertions.
 
-Active branch: none.
+Active branch: PR_26177_DELTA_056-shared-validation-assertions.
+
+Active PR: PR_26177_DELTA_056-shared-validation-assertions.
+
+OWNER override approved: Continue Team Delta random utility stack with PR_26177_DELTA_056-shared-validation-assertions.
 
 ## Team Golf