Merge PR_26177_OWNER_009-project-instructions-workflow-testable-tests-alignment

PR_26177_OWNER_009-project-instructions-workflow-testable-tests-alignment

Author: ToolboxAid

docs_build/dev/ProjectInstructions/PROJECT_INSTRUCTIONS.md

@@ -93,7 +93,7 @@ OWNER override wording:
 `OWNER override approved: <reason>`
 
 OWNER follows the same safety rules:
-- One active OWNER branch at a time.
+- One active Team 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.

docs_build/dev/ProjectInstructions/addendums/branch_lock_governance.md

@@ -9,11 +9,12 @@ Keep active work attached to the correct assigned team, branch, and OWNER decisi
 
 ## Active Work Lock
 
-- Work must occur on the assigned team or OWNER branch.
+- Work must occur on the active team branch.
+- This rule applies to all teams: OWNER, Team Alfa, Team Bravo, Team Charlie, Team Delta, and any future team.
 - 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 +26,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, PR branches/commits stay on the active team branch/workstream during the day and do 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 +53,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/codex_artifact_and_reporting_standard.md

@@ -37,7 +37,7 @@ Codex responses must include:
 ## Tool MVP PR Report Requirements
 
 Every tool MVP PR report must include:
-- Creator-testable outcome
+- Product Owner testable outcome
 - What Playwright tests
 - What Mr. Q should manually test
 - Whether the PR is part of a stacked MVP sequence
@@ -50,7 +50,7 @@ The report must answer:
 What can Mr. Q test after applying this ZIP?
 ```
 
-If a tool MVP PR has no Playwright lane, the report must state why and list the manual Creator validation instead.
+If a tool MVP PR has no Playwright lane, the report must state why and list the manual Product Owner validation instead.
 
 ## Code Change Reporting
 

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,10 +11,16 @@ 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.
-- "Mock repository ready" is not a valid Creator-testable completion state.
+- "Mock repository ready" is not a valid Product Owner testable completion state.
 - Page arrays are not product-data sources of truth.
 - JSON source files are not product-data sources of truth.
 - `/tmp` files are not product-data sources of truth.
@@ -32,7 +38,7 @@ If a temporary mock repository exists for transition, it must be documented as t
 - affected files
 - removal PR
 - replacement API/DB path
-- Creator-testable limitation
+- Product Owner testable limitation
 
 Temporary mock repositories do not make a feature complete. They may only document a transition state.
 
@@ -46,4 +52,4 @@ Completion requires Game Configuration data to load through:
 Browser → API → Database
 ```
 
-The Creator-testable completion state must prove that browser-visible Game Configuration data was read back through the API/service contract backed by the database.
+The Product Owner testable completion state must prove that browser-visible Game Configuration data was read back through the API/service contract backed by the database.

docs_build/dev/ProjectInstructions/addendums/pr_workflow.md

@@ -23,9 +23,27 @@ 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
+
+Team-neutral daily workflow:
+
+- SOD starts from the latest synchronized `main`.
+- SOD creates or updates one active team branch/workstream.
+- Work must be committed only to the active team branch.
+- PR branches/commits stay on the active team 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 rule applies to all teams: OWNER, Team Alfa, Team Bravo, Team Charlie, Team Delta, and any future team.
+
+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 +119,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.
@@ -124,14 +143,14 @@ Tool MVP work must follow:
 
 `docs_build/dev/ProjectInstructions/addendums/tool_mvp_stacked_pr_standard.md`
 
-For tool MVPs, use one large Codex command, multiple focused stacked PRs, and one testable Creator outcome per PR.
+For tool MVPs, use one large Codex command, multiple focused stacked PRs, and one Product Owner testable outcome per PR.
 
 Do not create one giant PR.
 
 Do not stop after every small PR unless blocked by branch state, failed validation, missing source files, Project Instructions conflict, or an unresolved dependency from a prior PR.
 
 Each tool MVP PR plan or template must include:
-- Creator-testable outcome
+- Product Owner testable outcome
 - What Playwright tests
 - What Mr. Q should manually test
 - Whether the PR is part of a stacked MVP sequence
@@ -140,6 +159,47 @@ 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, MVP, or testable experience means Product Owner testable by default. Codex must deliver a working Product Owner testable feature, not a shell or foundation page, unless the Product Owner explicitly requests a shell/foundation PR.
+
+A Product Owner testable outcome means the Product Owner can:
+
+- open the page/tool
+- perform the primary workflow
+- save/load data where applicable
+- observe expected results
+- validate success and failure states
+- follow manual validation steps from the PR report
+
+Not acceptable as a completed/testable page or tool:
+
+- shell-only page
+- route-only page
+- navigation-only PR
+- template-only page
+- placeholder controls
+- static table with no workflow
+- `Not implemented yet`
+- `coming soon`
+- placeholder-only workspace, inspector, or output sections
+- planned-only tile
+- 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.
+
+## No-Shell Completion Rule
+
+A PR requested to complete a page, tool, MVP, or testable experience must not stop after route creation, shell creation, placeholder UI, static mock layout, or navigation activation unless the Product Owner explicitly requested a shell/foundation PR.
+
 ## 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 team branch/workstream be updated.
 
 Create the PR branch:
 
@@ -112,9 +112,13 @@ From branch creation until merge:
 - Remain on the PR branch.
 - Never checkout `main`.
 - Commit only on the PR branch.
+- Work must be committed only to the active team branch.
 - 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, PR branches/commits stay on the active team branch/workstream 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.
+- This rule applies to all teams: OWNER, Team Alfa, Team Bravo, Team Charlie, Team Delta, and any future team.
 
 Hard Stops:
 
@@ -192,7 +196,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,38 @@ 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 matching page-level Playwright test before it can be considered complete.
+- 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
+- primary workflow is covered where the PR claims Product Owner testable completion
+- save/load and validation are covered where applicable
+- 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

@@ -12,15 +12,15 @@ Define how Codex plans and executes Creator-facing tool MVP work without creatin
 For tool MVPs, use:
 
 ```text
-One large Codex command -> multiple focused stacked PRs -> each PR has a testable Creator outcome.
+One large Codex command -> multiple focused stacked PRs -> each PR has a Product Owner testable outcome.
 ```
 
 ## Rules
 
 - Do not create one giant PR.
 - Do not stop after every small PR unless blocked.
 - Each PR must be independently scoped.
-- Each PR must produce a Creator-testable outcome.
+- Each PR must produce a Product Owner testable outcome.
 - Each PR must answer:
 
 ```text
@@ -40,8 +40,43 @@ 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, MVP, or testable experience means Product Owner testable by default. Codex must deliver a working Product Owner testable feature, not a shell or foundation page, unless the Product Owner explicitly requests a shell/foundation PR.
+
+A Product Owner testable outcome means the Product Owner can:
+
+- open the page/tool
+- perform the primary workflow
+- save/load data where applicable
+- observe expected results
+- validate success and failure states
+- follow manual validation steps from the PR report
+
+Not acceptable as complete/testable:
+
+- shell-only page
+- route-only page
+- navigation-only PR
+- template-only page
+- placeholder controls
+- static table with no workflow
+- `Not implemented yet`
+- `coming soon`
+- placeholder-only workspace, inspector, or output sections
+- planned-only tile
+- 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
+- Product Owner testable outcome
 - What Playwright tests
 - What Mr. Q should manually test
 - Whether the PR is part of a stacked MVP sequence
@@ -50,6 +85,8 @@ Each tool MVP PR must state:
 
 ## Runtime Data Completion Boundary
 
+A PR requested to complete a page, tool, MVP, or testable experience must not stop after route creation, shell creation, placeholder UI, static mock layout, or navigation activation unless the Product Owner explicitly requested a shell/foundation PR.
+
 A PR outcome must not be described as complete if the visible data is coming from:
 
 - mock repositories
@@ -81,4 +118,8 @@ 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, PR branches/commits stay on the active team branch/workstream and do not return to `main` between PRs.
+
+This rule applies to all teams: OWNER, Team Alfa, Team Bravo, Team Charlie, Team Delta, and any future team.
+
+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.