Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion dev/build/ProjectInstructions/PROJECT_INSTRUCTIONS.md
Original file line number Diff line number Diff line change
Expand Up @@ -117,7 +117,7 @@ Rules:

## Current Version/Date

- Project Instructions Version: 2026.06.28.002
- Project Instructions Version: 2026.06.28.003
- Date: 2026-06-28
- Owner: OWNER

Expand Down Expand Up @@ -202,6 +202,8 @@ That file owns Start of Day, PLAN_PR, BUILD_PR, APPLY_PR, and invalid command be
- Team ownership: `dev/build/ProjectInstructions/team_assignments/team_ownership.md`
- Team assignments: `dev/build/ProjectInstructions/team_assignments/TEAM_ASSIGNMENTS.md`
- Backlog: `dev/build/ProjectInstructions/backlog/BACKLOG_MASTER.md`
- Team backlog/startup assignment standard: `dev/build/ProjectInstructions/addendums/team_backlog_sod_eod_standard.md`
- Tool Votes/Admin Owner priority signal source: `admin/tool-votes.html`
- Database docs: `dev/build/database/`
- Runtime/API standards: `dev/build/ProjectInstructions/standards/`
- Runtime/API governance: `dev/build/ProjectInstructions/addendums/environment_governance_model.md`
Expand Down
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Project Instructions Version

Current Project Instructions Version: 2026.06.28.002
Current Project Instructions Version: 2026.06.28.003

Last Updated: 2026-06-28

Expand All @@ -10,6 +10,7 @@ Last Updated: 2026-06-28
- Project Instructions versions are repository-owned and increment independently of PR numbers.
- Added dedicated branching policy document.
- Startup validation now verifies the branching policy document was loaded instead of duplicating policy text.
- Added backlog startup assignment policy requiring `BACKLOG_MASTER.md` and Tool Votes/Admin Owner priority signal review during team startup.
- Codex must read this version file and the latest repository copy of `PROJECT_INSTRUCTIONS.md` before performing work.
- Codex must discard previously remembered Project Instructions and treat the repository copy as authoritative.
- Codex must validate canonical report and ZIP paths, branching model, and legacy path avoidance before work proceeds.
17 changes: 17 additions & 0 deletions dev/build/ProjectInstructions/TEAM_START_COMMANDS.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,13 @@ Non-Owner team PRs use Stacked PR workstreams by default. A non-Owner team PR ma

Use `dev/build/ProjectInstructions/` as the only active Project Instructions source.
Read `dev/build/ProjectInstructions/addendums/team_backlog_sod_eod_standard.md` before implementation.
Read `dev/build/ProjectInstructions/backlog/BACKLOG_MASTER.md` during startup.

`BACKLOG_MASTER.md` is the authoritative source for assigned product work. `admin/tool-votes.html` is the Tool Votes/Admin Owner priority signal source for tool demand and Owner/Admin review; it informs backlog priority but does not replace the backlog.

Team startup must display the Team Assignment table defined in `dev/build/ProjectInstructions/addendums/team_backlog_sod_eod_standard.md`.

Codex must not invent work from conversation memory when `BACKLOG_MASTER.md` has a matching product area.

Branch Lifecycle (Canonical):
- Follow `dev/build/ProjectInstructions/addendums/project_instructions_single_source_eod_lock.md` for START / WORK / END lifecycle, branch gates, mandatory hard stops, and EOD main lock.
Expand All @@ -45,10 +52,12 @@ Ready-to-copy command:
OWNER override approved: Start Alfa from the ProjectInstructions release gate.

Read dev/build/ProjectInstructions/PROJECT_INSTRUCTIONS.md first.
Read dev/build/ProjectInstructions/addendums/team_backlog_sod_eod_standard.md.
Read dev/build/ProjectInstructions/backlog/BACKLOG_MASTER.md.
Read dev/build/ProjectInstructions/team_assignments/TEAM_ASSIGNMENTS.md.

Pull one [ ] item for Alfa from BACKLOG_MASTER.md.
Report the Team Assignment table before implementation.
Stop if Alfa already has an active branch.
Stop if Alfa already has an active assignment.
Stop if no [ ] Alfa backlog item is available.
Expand All @@ -67,10 +76,12 @@ Ready-to-copy command:
OWNER override approved: Start Bravo from the ProjectInstructions release gate.

Read dev/build/ProjectInstructions/PROJECT_INSTRUCTIONS.md first.
Read dev/build/ProjectInstructions/addendums/team_backlog_sod_eod_standard.md.
Read dev/build/ProjectInstructions/backlog/BACKLOG_MASTER.md.
Read dev/build/ProjectInstructions/team_assignments/TEAM_ASSIGNMENTS.md.

Pull one [ ] item for Bravo from BACKLOG_MASTER.md.
Report the Team Assignment table before implementation.
Stop if Bravo already has an active branch.
Stop if Bravo already has an active assignment.
Stop if no [ ] Bravo backlog item is available.
Expand All @@ -89,10 +100,12 @@ Ready-to-copy command:
OWNER override approved: Start Charlie from the ProjectInstructions release gate.

Read dev/build/ProjectInstructions/PROJECT_INSTRUCTIONS.md first.
Read dev/build/ProjectInstructions/addendums/team_backlog_sod_eod_standard.md.
Read dev/build/ProjectInstructions/backlog/BACKLOG_MASTER.md.
Read dev/build/ProjectInstructions/team_assignments/TEAM_ASSIGNMENTS.md.

Pull one [ ] item for Charlie from BACKLOG_MASTER.md.
Report the Team Assignment table before implementation.
Stop if Charlie already has an active branch.
Stop if Charlie already has an active assignment.
Stop if no [ ] Charlie backlog item is available.
Expand All @@ -111,11 +124,13 @@ Ready-to-copy command:
OWNER override approved: Start Delta from the ProjectInstructions release gate.

Read dev/build/ProjectInstructions/PROJECT_INSTRUCTIONS.md first.
Read dev/build/ProjectInstructions/addendums/team_backlog_sod_eod_standard.md.
Read dev/build/ProjectInstructions/backlog/BACKLOG_MASTER.md.
Read dev/build/ProjectInstructions/team_assignments/TEAM_ASSIGNMENTS.md.
Read dev/build/ProjectInstructions/team_assignments/team_ownership.md.

Pull one [ ] item for Delta from BACKLOG_MASTER.md.
Report the Team Assignment table before implementation.
Stop if Delta already has an active branch.
Stop if Delta already has an active assignment.
Stop if no [ ] Delta backlog item is available.
Expand All @@ -135,10 +150,12 @@ Ready-to-copy command:
OWNER override approved: Start Golf from the ProjectInstructions release gate.

Read dev/build/ProjectInstructions/PROJECT_INSTRUCTIONS.md first.
Read dev/build/ProjectInstructions/addendums/team_backlog_sod_eod_standard.md.
Read dev/build/ProjectInstructions/backlog/BACKLOG_MASTER.md.
Read dev/build/ProjectInstructions/team_assignments/TEAM_ASSIGNMENTS.md.
Read dev/build/ProjectInstructions/team_assignments/team_ownership.md.

Report the Team Assignment table before implementation.
Stop if Golf already has an active branch.
Stop if Golf already has an active assignment.
Stop if OWNER has not explicitly assigned Golf work.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -26,29 +26,86 @@ Historical snapshots, archived references, and non-team phrases such as `Alfa/Be

## Team Backlog Ownership

Authoritative assigned product work source:

```text
dev/build/ProjectInstructions/backlog/BACKLOG_MASTER.md
```

Tool demand and Owner/Admin priority signal source:

```text
admin/tool-votes.html
```
Comment on lines +35 to +39

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Point the priority source at the data, not the shell page

For a repo-based Start of Day, admin/tool-votes.html does not contain the vote/order/state rows that would prove tool demand or Owner/Admin priority; the table body is empty and the page loads its snapshot through admin/tool-votes.js from /toolbox/votes/snapshot. Agents following this required source can only read the static shell and cannot derive the priority signal, so the instruction should reference the underlying API/data contract or explicitly require running the admin page.

Useful? React with 👍 / 👎.


The Tool Votes/Admin Owner planning surface informs backlog priority, Owner/Admin review, tool demand, and reprioritization. It does not replace `BACKLOG_MASTER.md` as the authoritative assigned-work source.

Every active team owns an active backlog when it has assigned work.

Each backlog item must track:

- name
- description
- product area
- status
- current completion percentage
- active PR, when one exists
- next milestone
- remaining work
- blocking dependencies
- owning team
- source or reference

Completion percentages are updated:

- at SOD
- when work changes status
- after every accepted PR
- at EOD

The backlog is the authoritative source for determining the next logical PRs.

If the backlog and a generated report conflict, the backlog wins unless OWNER explicitly approves a newer governance decision.

Codex must not invent assigned product work from conversation memory when `BACKLOG_MASTER.md` has a matching product area.

Teams must update backlog status and percent complete when work changes status.

Owner must update backlog status, completion percentage, and Tool Votes/Admin Owner status when assigning, reprioritizing, completing, or deferring work.

When the Product Owner provides a completed PR ZIP, ChatGPT must review that ZIP, update the active team backlog and completion percentages, and recommend the next logical PRs needed to keep moving toward a Product Owner testable outcome.

## Team Assignment Startup Review

During startup, each team must:

1. Read `dev/build/ProjectInstructions/backlog/BACKLOG_MASTER.md`.
2. Locate its assigned team section and assigned product areas.
3. Read the Tool Votes/Admin Owner priority signal source at `admin/tool-votes.html` when the work involves tool demand, tool ordering, or Owner/Admin prioritization.
4. Display assignments as a table grouped by Team, then Product Area.
5. Include Team, Product Area, Status, Percent Complete, Active PR, Next Milestone, and Source / Reference for every assignment row.

Required startup output:

```text
Team Assignment
===============

Source ............ dev/build/ProjectInstructions/backlog/BACKLOG_MASTER.md
Priority Source ... admin/tool-votes.html
Team .............. <team>
Status ............ PASS

Assignments
-----------

| Team | Product Area | Status | Complete | Active PR | Next Milestone | Source |
|------|--------------|--------|----------|-----------|----------------|--------|
| Alfa | Objects Manager | Active | 45% | PR_26179_ALFA_011 | Properties | BACKLOG_MASTER.md |

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Replace the stale sample assignment row

This required startup block hard-codes Alfa | Objects Manager | Active | 45% | PR_26179_ALFA_011, but the backlog/ownership docs list Objects under Charlie and there is no Alfa Objects Manager assignment in BACKLOG_MASTER.md. Agents copying the required output can report a nonexistent active Alfa assignment/PR; make this a placeholder row or generate it from the actual backlog instead of shipping a stale example.

Useful? React with 👍 / 👎.

```

If the task is not represented in `BACKLOG_MASTER.md` or the Tool Votes/Admin Owner planning source, Codex must flag the missing representation and ask OWNER whether to add or update the backlog before continuing.

## Start Of Day Team Briefing

When a team is assigned, ChatGPT/Codex must provide this briefing before implementation begins:
Expand All @@ -65,6 +122,18 @@ When a team is assigned, ChatGPT/Codex must provide this briefing before impleme

This briefing is required before implementation begins.

The briefing must include the Team Assignment startup output defined above.

## Startup Hard Stops

STOP before implementation when:

- `dev/build/ProjectInstructions/backlog/BACKLOG_MASTER.md` cannot be found.
- the assigned team cannot be found in the backlog, unless OWNER explicitly provided a one-off task.
- the requested product-area task is not represented in the backlog or Tool Votes/Admin Owner planning source, until OWNER confirms whether to update the backlog.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Don’t require Tool Votes for backlog-only work

As written, this hard stop fires whenever a requested product-area task is absent from either source, so any valid BACKLOG_MASTER.md item that is not also a Toolbox/Admin vote row will stop startup, even though the same standard says Tool Votes only applies when tool demand/Owner prioritization is relevant and does not replace the backlog. This blocks backlog-only assignments such as non-tool Alfa/Delta work; scope the Tool Votes check to tool-demand tasks or require a stop only when the task is missing from both applicable sources.

Useful? React with 👍 / 👎.


If `admin/tool-votes.html` cannot be found, document the missing priority signal source and recommend `admin/tool-votes.html` as the canonical path instead of inventing a replacement.

## End Of Day Team Summary

At EOD, ChatGPT/Codex must provide:
Expand Down
28 changes: 16 additions & 12 deletions dev/build/ProjectInstructions/addendums/team_start_and_release.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,11 +19,13 @@ Before a team starts, validate:
- `main...origin/main` is `0 0`
- `HEAD` SHA matches published EOD SHA
- active assignment is selected or confirmed by OWNER
- `dev/build/ProjectInstructions/backlog/BACKLOG_MASTER.md` is loaded as the authoritative assigned-work source
- `admin/tool-votes.html` is located as the Tool Votes/Admin Owner priority signal source
- assigned team uses the canonical Owner plus military team-name set
- work remains with the assigned team until complete or OWNER reassignment
- the team's previous PR is Closed, unless OWNER documented an explicit stacked PR chain

Before implementation begins, ChatGPT/Codex must provide the SOD briefing defined in `dev/build/ProjectInstructions/addendums/team_backlog_sod_eod_standard.md`.
Before implementation begins, ChatGPT/Codex must provide the SOD briefing and Team Assignment table defined in `dev/build/ProjectInstructions/addendums/team_backlog_sod_eod_standard.md`.

## Current Four-Team Start Set

Expand Down Expand Up @@ -63,17 +65,19 @@ Clarification:
For backlog-driven work:

1. Read `dev/build/ProjectInstructions/backlog/BACKLOG_MASTER.md`.
2. Select only the OWNER-approved backlog item.
3. Use the approved status model from `status_model.md`.
4. Confirm the previous PR for the team is Closed, unless this is an explicitly documented stacked PR chain.
5. Follow the canonical START phase in `project_instructions_single_source_eod_lock.md`.
6. Create or use the approved team branch and PR identity only after START passes.
7. Mark lifecycle state as PR Open.
8. Plan on the same PR branch.
9. Build on the same PR branch.
10. Record active work in the active team registry when required.
11. Open or update a draft PR during active WORK.
12. Merge only through OWNER-approved PR workflow and canonical END.
2. Locate the assigned team section and product areas.
3. Locate `admin/tool-votes.html` as the Tool Votes/Admin Owner priority signal source when tool demand or Owner/Admin prioritization is relevant.
4. Select only the OWNER-approved backlog item.
5. Use the approved status model from `status_model.md`.
6. Confirm the previous PR for the team is Closed, unless this is an explicitly documented stacked PR chain.
7. Follow the canonical START phase in `project_instructions_single_source_eod_lock.md`.
8. Create or use the approved team branch and PR identity only after START passes.
9. Mark lifecycle state as PR Open.
10. Plan on the same PR branch.
11. Build on the same PR branch.
12. Record active work in the active team registry when required.
13. Open or update a draft PR during active WORK.
14. Merge only through OWNER-approved PR workflow and canonical END.

## Team Command Examples

Expand Down
39 changes: 37 additions & 2 deletions dev/build/ProjectInstructions/backlog/BACKLOG_MASTER.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,16 +4,29 @@

Canonical backlog tracking owner: `dev/build/ProjectInstructions/addendums/team_backlog_sod_eod_standard.md`.

This file is the authoritative source for assigned product work.

This document is updated as work status changes, including Owner assignment, reprioritization, completion, deferral, accepted PRs, SOD review, and EOD review.

`BACKLOG_MASTER.md` is now the canonical team/product-area assignment and status source. Future backlog changes must update this structure directly.

Each product area must include status and percent complete.

Every active team owns an active backlog when it has assigned work.

Backlog entries in this file follow the canonical field list, including:

- Name
- Description
- Product area
- Status
- Current completion percentage
- Active PR, when one exists
- Next milestone
Comment on lines +21 to +25

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Populate the fields made mandatory

These newly mandatory fields are not actually populated for most existing backlog rows below (for example, entries like - [ ] Alfa - Game Concept Notes only have a checkbox/team/name under a journey heading). With the same PR declaring the current BACKLOG_MASTER.md structure canonical and requiring Start of Day to report Status, Active PR, and Next Milestone from it, teams either have to fabricate values or stop on missing evidence; migrate the rows to the required structure or relax the mandatory fields.

Useful? React with 👍 / 👎.

- Remaining work
- Blocking dependencies
- Owning team
- Source or reference

Completion percentages are updated at SOD, after every accepted PR, and at EOD.

Expand Down Expand Up @@ -181,6 +194,29 @@ The backlog is the authoritative source for determining the next logical PRs.
- OWNER merge approval and EOD merge governance verified.
- Team ownership governance verified through the authoritative ownership map.

- [x] Alfa - Team-aware local dev bootstrap runtime complete

Notes:
- Completion reference: PR #250 / `PR_26171_ALFA_009-team-aware-bootstrap`.
- `npm run dev:bootstrap` is the primary team-aware local bootstrap command.
- `npm run dev:local-api` remains as the legacy API alias.
- `npm run dev:api` supports API-only startup.
- `npm run dev:web` supports web-only startup.
- `dev/bootstrap/start-dev.mjs` owns bootstrap orchestration.
- `dev/bootstrap/team-port-config.mjs` owns team port resolution.
Comment on lines +205 to +206

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Point bootstrap ownership at existing scripts

These ownership pointers use dev/bootstrap/..., but the repository and package.json scripts point to dev/scripts/start-dev.mjs and dev/scripts/team-port-config.mjs; there is no dev/bootstrap copy. When future startup or port-resolution work follows this authoritative backlog note, it will inspect or edit nonexistent paths instead of the real bootstrap scripts, so the completed-item record should use the actual dev/scripts paths.

Useful? React with 👍 / 👎.

- Team-aware `--team` runtime support is implemented.
- Bootstrap orchestration, browser launch reporting, and port resolution are implemented.
- Verified command: `npm run dev:bootstrap -- --team bravo`.
- Observed verified output includes:
- `GameFoundry team-aware dev bootstrap`
- `Mode: bootstrap`
- `Team: bravo`
- `Web URL: http://127.0.0.1:5520`
- `API URL: http://127.0.0.1:5521/api`
- `Browser launch: http://127.0.0.1:5520/index.html`
- `Supported teams: owner, alfa, bravo, charlie, delta, echo, foxtrot, golf, hotel`
- Do not assign team-aware dev bootstrap, `dev:bootstrap`, team-port config, browser launch, bootstrap orchestration, or port resolution as remaining backlog work unless OWNER opens a new enhancement request.

- [x] OWNER - Repository hygiene governance complete

Notes:
Expand All @@ -195,11 +231,10 @@ The backlog is the authoritative source for determining the next logical PRs.
Status: CANCELLED / NOT DOING

Items removed from backlog:
- Multi-port workspace framework
- Alfa/Beta/User isolation framework
- Runtime port management initiative

Replacement governance:
- Multi-port workspace framework and runtime port management are no longer cancelled/not doing; they are implemented by the team-aware local dev bootstrap runtime item above.
- System Health remains one page per deployed environment.
- Each deployment actively checks only itself.
- Environment Summary, Database Health, Storage Health, Runtime Health, and Health Check History are Charlie System Health ownership.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,8 @@ The bootstrap loads:
- Canonical Repository Structure
- Team instructions
- Team backlog
- `dev/build/ProjectInstructions/backlog/BACKLOG_MASTER.md` assignment source
- `admin/tool-votes.html` Tool Votes/Admin Owner priority signal source
- Current team status
- Current branch
- Worktree status
Expand Down Expand Up @@ -148,6 +150,31 @@ Additional Documents Loaded:
Next Recommended PR:
```

Start-of-Day bootstrap must also include the Team Assignment section defined by:

```text
dev/build/ProjectInstructions/addendums/team_backlog_sod_eod_standard.md
```

Required assignment output:

```text
Team Assignment
===============

Source ............ dev/build/ProjectInstructions/backlog/BACKLOG_MASTER.md
Priority Source ... admin/tool-votes.html
Team .............. <team>
Status ............ PASS

Assignments
-----------

| Team | Product Area | Status | Complete | Active PR | Next Milestone | Source |
|------|--------------|--------|----------|-----------|----------------|--------|
| Alfa | Objects Manager | Active | 45% | PR_26179_ALFA_011 | Properties | BACKLOG_MASTER.md |
```

## Loading Rules

Only `PROJECT_INSTRUCTIONS.md` is requested directly.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -61,10 +61,19 @@ Start of Day reports:
- current branch
- worktree status
- latest main status
- backlog assignment source
- Tool Votes/Admin Owner priority signal source
- Team Assignment table grouped by Team, then Product Area
- active PR, if any
- recommended next action
- blockers

The Team Assignment table and backlog hard stops are defined in:

```text
dev/build/ProjectInstructions/addendums/team_backlog_sod_eod_standard.md
```

Start of Day may recommend the next execution phase, but it must not execute that phase.

Start of Day must satisfy the Codex Completion Contract in `dev/build/ProjectInstructions/addendums/codex_artifact_and_reporting_standard.md`. Because Start of Day is read-only discovery, its ZIP outcome is review-only unless another outcome is explicitly documented.
Expand Down
Loading
Loading