Skip to content

Commit b8a09a1

Browse files
ToolboxAidToolboxAid
authored
Merge pull request #257 from ToolboxAid/PR_26179_OWNER_012-project-instructions-startup-validation
PR_26179_OWNER_012-project-instructions-startup-validation
2 parents eb36313 + 913ee75 commit b8a09a1

9 files changed

Lines changed: 320 additions & 300 deletions

‎dev/build/ProjectInstructions/PROJECT_INSTRUCTIONS.md‎

Lines changed: 87 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,77 @@
1+
# Startup Contract
2+
3+
Before performing ANY task, Codex must:
4+
5+
- Read `dev/build/ProjectInstructions/PROJECT_INSTRUCTIONS_VERSION.md`.
6+
- Read the latest `dev/build/ProjectInstructions/PROJECT_INSTRUCTIONS.md` from the repository.
7+
- Treat repository Project Instructions as the only authoritative source.
8+
- Discard previously remembered Project Instructions before every Codex task.
9+
- Never allow conversation memory to override repository instructions.
10+
- Load all referenced instruction documents required by this file and the task.
11+
- Validate canonical paths.
12+
- Validate branching model.
13+
- Validate ZIP and report locations.
14+
15+
Every Codex response must begin with:
16+
17+
```text
18+
Startup Validation
19+
==================
20+
21+
Reading latest (v<version>) Project Instructions... PASS
22+
23+
Instruction Source
24+
------------------
25+
Repository ........ PASS
26+
Cached Memory ..... DISCARDED
27+
28+
Canonical paths
29+
---------------
30+
Reports .......... dev/reports
31+
ZIPs ............. dev/workspace/zips
32+
33+
Branching model
34+
---------------
35+
Owner ............ Independent PRs allowed
36+
Teams ............ Stacked PRs by default
37+
38+
Legacy path check
39+
-----------------
40+
tmp/ ............. PASS (not used)
41+
docs_build/ ...... PASS (not used)
42+
43+
Project Instructions loaded successfully.
44+
```
45+
46+
If Codex cannot determine the current version or cannot validate canonical paths, it must STOP before performing any work.
47+
48+
Failure response example:
49+
50+
```text
51+
Startup Validation
52+
==================
53+
54+
Unable to determine Project Instructions version.
55+
56+
STOP
57+
58+
Project Instructions were not successfully loaded.
59+
```
60+
61+
This startup validation applies to every Codex task and outcome:
62+
63+
- PLAN
64+
- BUILD
65+
- APPLY
66+
- Review
67+
- Audit
68+
- Governance
69+
- Validation
70+
- Read-only
71+
- Hard stop
72+
- No-op
73+
- Partial completion
74+
175
# Project Instructions
276

377
## Purpose
@@ -41,23 +115,25 @@ Rules:
41115

42116
## Current Version/Date
43117

44-
- Project Instructions Version: 2026-06-28.PR_26172_OWNER_034
118+
- Project Instructions Version: 2026.06.28.001
45119
- Date: 2026-06-28
46120
- Owner: OWNER
47121

48122
## Required Read Order
49123

50-
1. Always read `dev/build/ProjectInstructions/PROJECT_INSTRUCTIONS.md`.
51-
2. Always read `dev/build/ProjectInstructions/PROJECT_STATE.md`.
52-
3. Always read `dev/build/ProjectInstructions/repository/canonical_repository_structure.md`.
53-
4. For Codex workflow command interpretation, read `dev/build/ProjectInstructions/standards/CODEX_WORKFLOW_COMMANDS.md`.
54-
5. For Start of Day, read `dev/build/ProjectInstructions/bootstrap/codex_start_of_day_bootstrap.md`.
55-
6. Load team, backlog, database, runtime, theme, or other specialist documents only when the current task requires them.
124+
1. Always read `dev/build/ProjectInstructions/PROJECT_INSTRUCTIONS_VERSION.md`.
125+
2. Always read `dev/build/ProjectInstructions/PROJECT_INSTRUCTIONS.md`.
126+
3. Always read `dev/build/ProjectInstructions/PROJECT_STATE.md`.
127+
4. Always read `dev/build/ProjectInstructions/repository/canonical_repository_structure.md`.
128+
5. For Codex workflow command interpretation, read `dev/build/ProjectInstructions/standards/CODEX_WORKFLOW_COMMANDS.md`.
129+
6. For Start of Day, read `dev/build/ProjectInstructions/bootstrap/codex_start_of_day_bootstrap.md`.
130+
7. Load team, backlog, database, runtime, theme, or other specialist documents only when the current task requires them.
56131

57132
## Load Graph
58133

59134
```text
60135
PROJECT_INSTRUCTIONS.md
136+
|-- PROJECT_INSTRUCTIONS_VERSION.md
61137
|-- PROJECT_STATE.md
62138
|-- repository/canonical_repository_structure.md
63139
|-- standards/CODEX_WORKFLOW_COMMANDS.md
@@ -76,6 +152,7 @@ PROJECT_INSTRUCTIONS.md
76152

77153
## When-To-Load Rules
78154

155+
- `PROJECT_INSTRUCTIONS_VERSION.md`: always.
79156
- `PROJECT_INSTRUCTIONS.md`: always.
80157
- `PROJECT_STATE.md`: always.
81158
- `repository/canonical_repository_structure.md`: always.
@@ -109,6 +186,7 @@ That file owns Start of Day, PLAN_PR, BUILD_PR, APPLY_PR, and invalid command be
109186

110187
## Referenced Documents
111188

189+
- Project Instructions version: `dev/build/ProjectInstructions/PROJECT_INSTRUCTIONS_VERSION.md`
112190
- Project state: `dev/build/ProjectInstructions/PROJECT_STATE.md`
113191
- Repository folder placement SSoT: `dev/build/ProjectInstructions/repository/canonical_repository_structure.md`
114192
- Codex workflow commands: `dev/build/ProjectInstructions/standards/CODEX_WORKFLOW_COMMANDS.md`
@@ -130,7 +208,8 @@ That file owns Start of Day, PLAN_PR, BUILD_PR, APPLY_PR, and invalid command be
130208

131209
## Single Source Of Truth Decisions
132210

133-
- `PROJECT_INSTRUCTIONS.md` owns the manual entry point, required read order, load graph, stop gates, execution modes, and pointers.
211+
- `PROJECT_INSTRUCTIONS_VERSION.md` owns the current Project Instructions version and startup version proof.
212+
- `PROJECT_INSTRUCTIONS.md` owns the manual entry point, startup contract, required read order, load graph, stop gates, execution modes, and pointers.
134213
- `PROJECT_STATE.md` owns machine-friendly project state metadata.
135214
- `repository/canonical_repository_structure.md` owns all folder placement and file-placement rules.
136215
- `standards/CODEX_WORKFLOW_COMMANDS.md` owns Start of Day, PLAN_PR, BUILD_PR, APPLY_PR, and invalid command behavior.

‎dev/build/ProjectInstructions/PROJECT_INSTRUCTIONS_VERSION.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
# Project Instructions Version
2+
3+
Current Project Instructions Version: 2026.06.28.001
4+
5+
Last Updated: 2026-06-28
6+
7+
## Breaking Changes Summary
8+
9+
- Codex startup validation is mandatory before every task outcome.
10+
- Project Instructions versions are repository-owned and increment independently of PR numbers.
11+
- Codex must read this version file and the latest repository copy of `PROJECT_INSTRUCTIONS.md` before performing work.
12+
- Codex must discard previously remembered Project Instructions and treat the repository copy as authoritative.
13+
- Codex must validate canonical report and ZIP paths, branching model, and legacy path avoidance before work proceeds.

‎dev/reports/PR_26179_OWNER_012-project-instructions-startup-validation_branch-validation.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
# PR_26179_OWNER_012-project-instructions-startup-validation Branch Validation
2+
3+
## Result
4+
5+
PASS
6+
7+
## Checks
8+
9+
| Check | Result | Notes |
10+
| --- | --- | --- |
11+
| Stacked PR model identified | PASS | This PR depends on PR #256. |
12+
| Started from documented previous PR branch | PASS | Started from `PR_26179_OWNER_011-team-stacked-pr-policy`. |
13+
| Worktree clean before branch creation | PASS | Verified before branch creation. |
14+
| PR branch created | PASS | `PR_26179_OWNER_012-project-instructions-startup-validation`. |
15+
| Work stayed on PR branch | PASS | No direct commit to `main`. |
16+
| Documentation/governance scope | PASS | Only Project Instructions and reports changed. |

‎dev/reports/PR_26179_OWNER_012-project-instructions-startup-validation_manual-validation-notes.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
# PR_26179_OWNER_012-project-instructions-startup-validation Manual Validation Notes
2+
3+
## Notes
4+
5+
- Confirmed the Startup Contract is the first section in `PROJECT_INSTRUCTIONS.md`.
6+
- Confirmed `PROJECT_INSTRUCTIONS_VERSION.md` exists in the active Project Instructions folder.
7+
- Confirmed Project Instructions version uses repository-owned `2026.06.28.001` format rather than PR-number format.
8+
- Confirmed the startup response block includes `Instruction Source`, `Repository ........ PASS`, and `Cached Memory ..... DISCARDED`.
9+
- Confirmed the Startup Contract says conversation memory must never override repository instructions.
10+
- Confirmed the startup response block uses `dev/reports` and `dev/workspace/zips`.
11+
- Confirmed the legacy path check calls out `tmp/` and `docs_build/` as not used.
12+
- Confirmed no runtime or product files were modified.

‎dev/reports/PR_26179_OWNER_012-project-instructions-startup-validation_report.md‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
# PR_26179_OWNER_012-project-instructions-startup-validation Report
2+
3+
## Purpose
4+
5+
Strengthen the Project Instructions startup contract so every Codex task proves it loaded the latest Project Instructions before performing work.
6+
7+
## Branching Model
8+
9+
- Model: Stacked PR
10+
- Previous PR dependency: `PR_26179_OWNER_011-team-stacked-pr-policy` / PR #256
11+
- Starting branch: `PR_26179_OWNER_011-team-stacked-pr-policy`
12+
- Merge order: PR #255, then PR #256, then this PR
13+
14+
## Governance Outcome
15+
16+
- Added `dev/build/ProjectInstructions/PROJECT_INSTRUCTIONS_VERSION.md`.
17+
- Replaced PR-shaped Project Instructions versioning with repository-owned version `2026.06.28.001`.
18+
- Added a mandatory Startup Contract at the top of `PROJECT_INSTRUCTIONS.md`.
19+
- Required Codex to read the version file and latest repository Project Instructions before every task.
20+
- Required Codex to discard remembered Project Instructions in favor of the repository copy.
21+
- Added explicit startup output for `Instruction Source`, proving repository instructions are used and cached memory is discarded.
22+
- Documented that conversation memory must never override repository instructions.
23+
- Required startup validation for canonical paths, branching model, ZIP/report locations, and legacy path avoidance.
24+
- Added failure behavior when the version or canonical paths cannot be determined.
25+
- Documented that the startup validation applies to PLAN, BUILD, APPLY, Review, Audit, Governance, Validation, Read-only, Hard stop, No-op, and Partial completion outcomes.
26+
27+
## Runtime Impact
28+
29+
None. This PR changes documentation/governance only.
30+
31+
## ZIP
32+
33+
- `dev/workspace/zips/PR_26179_OWNER_012-project-instructions-startup-validation_delta.zip`

‎dev/reports/PR_26179_OWNER_012-project-instructions-startup-validation_requirement-checklist.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# PR_26179_OWNER_012-project-instructions-startup-validation Requirement Checklist
2+
3+
| Requirement | Result | Notes |
4+
| --- | --- | --- |
5+
| Create `PROJECT_INSTRUCTIONS_VERSION.md` | PASS | Added under `dev/build/ProjectInstructions/`. |
6+
| Version file contains current version | PASS | `2026.06.28.001`. |
7+
| Version format is repository-owned, not PR-owned | PASS | Version increments independently of PR numbers. |
8+
| Version file contains last updated | PASS | `2026-06-28`. |
9+
| Version file contains breaking changes summary | PASS | Added concise startup validation summary. |
10+
| Add mandatory Startup Contract at top of `PROJECT_INSTRUCTIONS.md` | PASS | Added before the main Project Instructions heading. |
11+
| Require reading version file and latest Project Instructions | PASS | Included in Startup Contract. |
12+
| Require repository copy as authoritative and discard memory | PASS | Included in Startup Contract. |
13+
| Conversation memory must never override repository instructions | PASS | Included in Startup Contract. |
14+
| Require loading referenced instruction documents | PASS | Included in Startup Contract. |
15+
| Require canonical path, branching model, ZIP/report validation | PASS | Included in Startup Contract. |
16+
| Add mandatory response block | PASS | Added exact startup validation response format with Instruction Source section. |
17+
| Add failure behavior | PASS | Added STOP example and pre-work stop rule. |
18+
| Apply to every Codex task type | PASS | Listed all requested task/outcome types. |
19+
| Do not modify implementation code | PASS | Documentation/governance only. |

‎dev/reports/PR_26179_OWNER_012-project-instructions-startup-validation_validation-report.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
# PR_26179_OWNER_012-project-instructions-startup-validation Validation Report
2+
3+
## Validation
4+
5+
- `git diff --check`: PASS
6+
- `npm run validate:canonical-structure`: PASS
7+
- Project Instructions grep for startup validation contract: PASS
8+
- Project Instructions grep for repository-owned version format and Instruction Source output: PASS
9+
10+
## Playwright
11+
12+
Not impacted. No runtime, UI, API, database, or product page files changed.

‎dev/reports/codex_changed_files.txt‎

Lines changed: 6 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,10 @@
11
# git status --short
2-
M dev/build/ProjectInstructions/TEAM_START_COMMANDS.md
3-
M dev/build/ProjectInstructions/addendums/branch_context_governance.md
4-
M dev/build/ProjectInstructions/addendums/branch_lock_governance.md
5-
M dev/build/ProjectInstructions/addendums/codex_artifact_and_reporting_standard.md
6-
M dev/build/ProjectInstructions/addendums/pr_workflow.md
7-
M dev/build/ProjectInstructions/addendums/project_instructions_single_source_eod_lock.md
8-
M dev/build/ProjectInstructions/standards/CODEX_WORKFLOW_COMMANDS.md
9-
A dev/reports/PR_26179_OWNER_011-team-stacked-pr-policy_branch-validation.md
10-
A dev/reports/PR_26179_OWNER_011-team-stacked-pr-policy_manual-validation-notes.md
11-
A dev/reports/PR_26179_OWNER_011-team-stacked-pr-policy_report.md
12-
A dev/reports/PR_26179_OWNER_011-team-stacked-pr-policy_requirement-checklist.md
13-
A dev/reports/PR_26179_OWNER_011-team-stacked-pr-policy_validation-report.md
2+
M dev/build/ProjectInstructions/PROJECT_INSTRUCTIONS.md
3+
M dev/build/ProjectInstructions/PROJECT_INSTRUCTIONS_VERSION.md
4+
M dev/reports/PR_26179_OWNER_012-project-instructions-startup-validation_manual-validation-notes.md
5+
M dev/reports/PR_26179_OWNER_012-project-instructions-startup-validation_report.md
6+
M dev/reports/PR_26179_OWNER_012-project-instructions-startup-validation_requirement-checklist.md
7+
M dev/reports/PR_26179_OWNER_012-project-instructions-startup-validation_validation-report.md
148

159
# git ls-files --others --exclude-standard
1610
(no output)

0 commit comments

Comments
 (0)