Skip to content

Commit 56cdd88

Browse files
ToolboxAidToolboxAid
committed
Add Project Instructions startup validation
1 parent 154f027 commit 56cdd88

9 files changed

Lines changed: 380 additions & 227 deletions

‎dev/build/ProjectInstructions/PROJECT_INSTRUCTIONS.md‎

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

371
## Purpose
@@ -41,23 +109,25 @@ Rules:
41109

42110
## Current Version/Date
43111

44-
- Project Instructions Version: 2026-06-28.PR_26172_OWNER_034
112+
- Project Instructions Version: 2026-06-28.PR_26179_OWNER_012
45113
- Date: 2026-06-28
46114
- Owner: OWNER
47115

48116
## Required Read Order
49117

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.
118+
1. Always read `dev/build/ProjectInstructions/PROJECT_INSTRUCTIONS_VERSION.md`.
119+
2. Always read `dev/build/ProjectInstructions/PROJECT_INSTRUCTIONS.md`.
120+
3. Always read `dev/build/ProjectInstructions/PROJECT_STATE.md`.
121+
4. Always read `dev/build/ProjectInstructions/repository/canonical_repository_structure.md`.
122+
5. For Codex workflow command interpretation, read `dev/build/ProjectInstructions/standards/CODEX_WORKFLOW_COMMANDS.md`.
123+
6. For Start of Day, read `dev/build/ProjectInstructions/bootstrap/codex_start_of_day_bootstrap.md`.
124+
7. Load team, backlog, database, runtime, theme, or other specialist documents only when the current task requires them.
56125

57126
## Load Graph
58127

59128
```text
60129
PROJECT_INSTRUCTIONS.md
130+
|-- PROJECT_INSTRUCTIONS_VERSION.md
61131
|-- PROJECT_STATE.md
62132
|-- repository/canonical_repository_structure.md
63133
|-- standards/CODEX_WORKFLOW_COMMANDS.md
@@ -76,6 +146,7 @@ PROJECT_INSTRUCTIONS.md
76146

77147
## When-To-Load Rules
78148

149+
- `PROJECT_INSTRUCTIONS_VERSION.md`: always.
79150
- `PROJECT_INSTRUCTIONS.md`: always.
80151
- `PROJECT_STATE.md`: always.
81152
- `repository/canonical_repository_structure.md`: always.
@@ -109,6 +180,7 @@ That file owns Start of Day, PLAN_PR, BUILD_PR, APPLY_PR, and invalid command be
109180

110181
## Referenced Documents
111182

183+
- Project Instructions version: `dev/build/ProjectInstructions/PROJECT_INSTRUCTIONS_VERSION.md`
112184
- Project state: `dev/build/ProjectInstructions/PROJECT_STATE.md`
113185
- Repository folder placement SSoT: `dev/build/ProjectInstructions/repository/canonical_repository_structure.md`
114186
- Codex workflow commands: `dev/build/ProjectInstructions/standards/CODEX_WORKFLOW_COMMANDS.md`
@@ -130,7 +202,8 @@ That file owns Start of Day, PLAN_PR, BUILD_PR, APPLY_PR, and invalid command be
130202

131203
## Single Source Of Truth Decisions
132204

133-
- `PROJECT_INSTRUCTIONS.md` owns the manual entry point, required read order, load graph, stop gates, execution modes, and pointers.
205+
- `PROJECT_INSTRUCTIONS_VERSION.md` owns the current Project Instructions version and startup version proof.
206+
- `PROJECT_INSTRUCTIONS.md` owns the manual entry point, startup contract, required read order, load graph, stop gates, execution modes, and pointers.
134207
- `PROJECT_STATE.md` owns machine-friendly project state metadata.
135208
- `repository/canonical_repository_structure.md` owns all folder placement and file-placement rules.
136209
- `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: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
# Project Instructions Version
2+
3+
Current Project Instructions Version: 2026-06-28.PR_26179_OWNER_012
4+
5+
Last Updated: 2026-06-28
6+
7+
## Breaking Changes Summary
8+
9+
- Codex startup validation is mandatory before every task outcome.
10+
- Codex must read this version file and the latest repository copy of `PROJECT_INSTRUCTIONS.md` before performing work.
11+
- Codex must discard previously remembered Project Instructions and treat the repository copy as authoritative.
12+
- 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: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
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 the startup response block uses `dev/reports` and `dev/workspace/zips`.
8+
- Confirmed the legacy path check calls out `tmp/` and `docs_build/` as not used.
9+
- Confirmed no runtime or product files were modified.

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

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
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+
- Added a mandatory Startup Contract at the top of `PROJECT_INSTRUCTIONS.md`.
18+
- Required Codex to read the version file and latest repository Project Instructions before every task.
19+
- Required Codex to discard remembered Project Instructions in favor of the repository copy.
20+
- Required startup validation for canonical paths, branching model, ZIP/report locations, and legacy path avoidance.
21+
- Added failure behavior when the version or canonical paths cannot be determined.
22+
- Documented that the startup validation applies to PLAN, BUILD, APPLY, Review, Audit, Governance, Validation, Read-only, Hard stop, No-op, and Partial completion outcomes.
23+
24+
## Runtime Impact
25+
26+
None. This PR changes documentation/governance only.
27+
28+
## ZIP
29+
30+
- `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: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
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.PR_26179_OWNER_012`. |
7+
| Version file contains last updated | PASS | `2026-06-28`. |
8+
| Version file contains breaking changes summary | PASS | Added concise startup validation summary. |
9+
| Add mandatory Startup Contract at top of `PROJECT_INSTRUCTIONS.md` | PASS | Added before the main Project Instructions heading. |
10+
| Require reading version file and latest Project Instructions | PASS | Included in Startup Contract. |
11+
| Require repository copy as authoritative and discard memory | PASS | Included in Startup Contract. |
12+
| Require loading referenced instruction documents | PASS | Included in Startup Contract. |
13+
| Require canonical path, branching model, ZIP/report validation | PASS | Included in Startup Contract. |
14+
| Add mandatory response block | PASS | Added exact startup validation response format. |
15+
| Add failure behavior | PASS | Added STOP example and pre-work stop rule. |
16+
| Apply to every Codex task type | PASS | Listed all requested task/outcome types. |
17+
| Do not modify implementation code | PASS | Documentation/governance only. |

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

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
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+
9+
## Playwright
10+
11+
Not impacted. No runtime, UI, API, database, or product page files changed.

‎dev/reports/codex_changed_files.txt‎

Lines changed: 12 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,18 @@
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+
A dev/build/ProjectInstructions/PROJECT_INSTRUCTIONS_VERSION.md
4+
A dev/reports/PR_26179_OWNER_012-project-instructions-startup-validation_branch-validation.md
5+
A dev/reports/PR_26179_OWNER_012-project-instructions-startup-validation_manual-validation-notes.md
6+
A dev/reports/PR_26179_OWNER_012-project-instructions-startup-validation_report.md
7+
A dev/reports/PR_26179_OWNER_012-project-instructions-startup-validation_requirement-checklist.md
8+
A dev/reports/PR_26179_OWNER_012-project-instructions-startup-validation_validation-report.md
9+
M dev/reports/codex_changed_files.txt
10+
M dev/reports/codex_review.diff
1411

1512
# git ls-files --others --exclude-standard
1613
(no output)
1714

1815
# git diff --stat
19-
(no output)
16+
dev/reports/codex_changed_files.txt | 19 +-
17+
dev/reports/codex_review.diff | 399 +++++++++++++++++-------------------
18+
2 files changed, 200 insertions(+), 218 deletions(-)

0 commit comments

Comments
 (0)