Skip to content

Commit 3144357

Browse files
ToolboxAidToolboxAid
committed
Add project instruction reference files governance
1 parent 99c53e3 commit 3144357

17 files changed

Lines changed: 774 additions & 176 deletions

‎docs_build/dev/PROJECT_INSTRUCTIONS.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2288,6 +2288,17 @@ OWNER follows the same safety rules:
22882288
- OWNER may override team locks, but may not silently delete, rewrite, or remove protected instructions.
22892289
- OWNER override must be explicitly documented.
22902290

2291+
## PROJECT INSTRUCTION REFERENCE FILE RECOGNITION
2292+
2293+
`docs_build/dev/ProjectInstructions/addendums/project_reference_files.md` defines additional valid project instruction/reference files.
2294+
2295+
Future Project Instructions reviews must include these files when present in `ProjectInstructions.zip`, the active project instruction directory, or `docs_build/dev/admin-notes/`:
2296+
2297+
- `Installs required.txt`
2298+
- `Table layout.txt`
2299+
2300+
Treat these files the same as existing instruction documents for read-set, review, preservation, and reporting purposes.
2301+
22912302
## CODEX INSTRUCTION ENFORCEMENT START GATE
22922303

22932304
Codex must run this gate before every PR execution and before any file changes.

‎docs_build/dev/ProjectInstructions/PROJECT_INSTRUCTIONS.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@ The Project Instructions operating system provides additive governance for:
1515
- tile overlay status behavior
1616
- deprecation workflow
1717
- archive and history preservation
18+
- recognized project instruction/reference files
1819

1920
## Preservation
2021

@@ -29,6 +30,10 @@ Existing Project Instructions remain preserved in their current locations. This
2930
- `archive/` contains retained reference material.
3031
- `archive/history/` contains timestamped history snapshots.
3132

33+
## Recognized Project Reference Files
34+
35+
`docs_build/dev/ProjectInstructions/addendums/project_reference_files.md` defines additional valid project instruction/reference files that must be included in future Project Instructions reviews when present in `ProjectInstructions.zip`, the active project instruction directory, or `docs_build/dev/admin-notes/`.
36+
3237
## Merge Control
3338

3439
No PR in this operating system is merged without explicit owner approval.

‎docs_build/dev/ProjectInstructions/README.txt‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -48,3 +48,4 @@ Addendum index:
4848
- Assistant Execution Modes: project-instructions/addendums/assistant-execution-modes.md
4949
- Codex Artifact and Reporting Standard: project-instructions/addendums/codex-artifact-and-reporting-standard.md
5050
- Codex Project Instructions Startup: project-instructions/addendums/codex-project-instructions-startup.md
51+
- Project Reference Files Governance: docs_build/dev/ProjectInstructions/addendums/project_reference_files.md

‎docs_build/dev/ProjectInstructions/addendums/project_reference_files.md‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
# Project Reference Files Governance
2+
3+
Status: Approved
4+
Owner: OWNER
5+
6+
## Purpose
7+
8+
Define recognized project instruction and reference documents that may live outside the active `docs_build/dev/ProjectInstructions/` addendum tree but still belong in Project Instructions reviews.
9+
10+
## Recognized Files
11+
12+
The following files are valid project instruction/reference documents when present in `ProjectInstructions.zip`, `docs_build/dev/ProjectInstructions/`, or the project instruction/admin-notes directory:
13+
14+
- `Installs required.txt`
15+
- `Table layout.txt`
16+
17+
Canonical repository locations:
18+
19+
- `docs_build/dev/admin-notes/Installs required.txt`
20+
- `docs_build/dev/admin-notes/Table layout.txt`
21+
22+
## Review Rule
23+
24+
Future Project Instructions reviews must include these files automatically when they are present in either:
25+
26+
- an extracted `ProjectInstructions.zip` bundle
27+
- the active project instruction directory
28+
- `docs_build/dev/admin-notes/`
29+
30+
Treat these files the same as existing instruction documents for read-set, review, preservation, and reporting purposes.
31+
32+
Missing files are not a release-gate failure unless a PR explicitly scopes those files or claims they are present.
33+
34+
## Scope Boundary
35+
36+
This governance addendum does not introduce runtime behavior, UI behavior, application loading, or ZIP-generation changes.

‎docs_build/dev/ProjectInstructions/addendums/release_gate.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -36,7 +36,10 @@ The release gate should confirm these files when relevant to the PR:
3636
- `docs_build/dev/ProjectInstructions/backlog/BACKLOG_MASTER.md`
3737
- `docs_build/dev/ProjectInstructions/addendums/governance_phase1_complete.md`
3838
- `docs_build/dev/ProjectInstructions/addendums/pr_workflow.md`
39+
- `docs_build/dev/ProjectInstructions/addendums/project_reference_files.md`
3940
- `docs_build/dev/ProjectInstructions/team_assignments/team_ownership.md`
41+
- `docs_build/dev/admin-notes/Installs required.txt` when present
42+
- `docs_build/dev/admin-notes/Table layout.txt` when present
4043

4144
## Validation Result
4245

‎docs_build/dev/admin-notes/Installs required.txt‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
VS Code required tools
2+
3+
Power Shell
4+
winget install --id GitHub.cli
5+
gh --version
6+
gh auth login
7+
8+
Terminal
9+
Install-Script -Name winget-install -RequiredVersion 2.1.0 -Scope CurrentUser

‎docs_build/dev/admin-notes/Table layout.txt‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
2+
DB base
3+
Creator Table 1
4+
Parent Table *-1 user
5+
Child Table -- *-1 Parent
6+
7+
8+
No selected Items
9+
┌──────────────────────────────────────────────────────────────────────────────────────────────────────┐
10+
│ Idea Board │
11+
├───────────────┬─────────────────────────────────────────┬───────────┬────────────┬─────────┬─────────┤
12+
│ Idea │ Pitch │ Status │ Updated │ Notes │ Actions │
13+
├───────────────┼─────────────────────────────────────────┼───────────┼────────────┼─────────┼─────────┤
14+
│ Top Thougts │ Smartest person wins... │ Exploring │ 2026-06-20 │ 3 Notes │ Edit Del│
15+
├───────────────┬─────────────────────────────────────────┬───────────┬────────────┬─────────┬─────────┤
16+
│ Sky Orchard │ Grow floating islands... │ Exploring │ 2026-06-20 │ 3 Notes │ Edit Del│
17+
├───────────────┴─────────────────────────────────────────┴───────────┴────────────┴─────────┴─────────┤
18+
│ Clockwork... │ Deliver messages through looping city...│ New │ 2026-06-20 │ 0 Notes │ Edit Del│
19+
├───────────────┴─────────────────────────────────────────┴───────────┴────────────┴─────────┴─────────┤
20+
│ [ Add Idea ] │
21+
└──────────────────────────────────────────────────────────────────────────────────────────────────────┘
22+
23+
24+
Clicking {Sky Orchard {chevron down arrow}] Expands/Acording the Note(s) for that Idea
25+
┌────────────────────────────────────────────────────────────────────────────────────────────────────┐
26+
│ Idea Board │
27+
├───────────────┬─────────────────────────────────────────┬───────────┬────────────┬─────────┬─────────┤
28+
│ Idea │ Pitch │ Status │ Updated │ Notes │ Actions │
29+
├───────────────┼─────────────────────────────────────────┼───────────┼────────────┼─────────┼─────────┤
30+
│ Top Thougts │ Smartest person wins... │ Exploring │ 2026-06-20 │ 3 Notes │ Edit Del│
31+
├───────────────┬─────────────────────────────────────────┬───────────┬────────────┬─────────┬─────────┤
32+
│ Sky Orchard[^}│ Grow floating islands... │ Exploring │ 2026-06-20 │ 3 Notes │ Edit Del│
33+
├───────────────┴─────────────────────────────────────────┴───────────┴────────────┴─────────┴─────────┤
34+
│ Notes │
35+
│ --------------------------------------------------------------------------------------------------- │
36+
│ note 1 [Edit] [Delete] │
37+
│ System seed note: compare early ideas before project creation. [Edit] │
38+
│ Ask whether the core loop is planning, defense, or both. [Edit] [Delete] │
39+
│ │
40+
│ [ Add Note ] │
41+
├───────────────┬─────────────────────────────────────────┬───────────┬────────────┬─────────┬─────────┤
42+
│ Clockwork... │ Deliver messages through looping city...│ New │ 2026-06-20 │ 0 Notes │ Edit Del│
43+
├───────────────┴─────────────────────────────────────────┴───────────┴────────────┴─────────┴─────────┤
44+
│ [ Add Idea ] │
45+
└──────────────────────────────────────────────────────────────────────────────────────────────────────┘
46+
47+
Clickin Add Idea
48+
┌────────────────────────────────────────────────────────────────────────────────────────────────────┐
49+
│ Idea Board │
50+
├───────────────┬─────────────────────────────────────────┬───────────┬────────────┬─────────┬─────────┤
51+
│ Idea │ Pitch │ Status │ Updated │ Notes │ Actions │
52+
├───────────────┼─────────────────────────────────────────┼───────────┼────────────┼─────────┼─────────┤
53+
│ Top Thougts │ Smartest person wins... │ Exploring │ 2026-06-20 │ 3 Notes │ Edit Del│
54+
├───────────────┬─────────────────────────────────────────┬───────────┬────────────┬─────────┬─────────┤
55+
│ Sky Orchard │ Grow floating islands... │ Exploring │ 2026-06-20 │ 3 Notes │ Edit Del│
56+
├───────────────┴─────────────────────────────────────────┴───────────┴────────────┴─────────┴─────────┤
57+
│ Clockwork... │ Deliver messages through looping city...│ New │ 2026-06-20 │ 0 Notes │ Edit Del│
58+
├───────────────┴─────────────────────────────────────────┴───────────┴────────────┴─────────┴─────────┤
59+
│ [input.....] │ [input.....] │ [Dropdown]│ [autofile] │ 0 Notes │ Save Can│
60+
└──────────────────────────────────────────────────────────────────────────────────────────────────────┘

‎docs_build/dev/admin-notes/index.txt‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,8 @@ Owned paths:
3030
- `docs_build/dev/admin-notes/other/index.txt` is the simple subnote fixture.
3131
- `docs_build/dev/admin-notes/quick-reference.txt` is a linked text-note fixture.
3232
- `docs_build/dev/admin-notes/sample.txt` is a root-relative link example note.
33+
- `docs_build/dev/admin-notes/Installs required.txt` is a recognized Project Instructions reference file.
34+
- `docs_build/dev/admin-notes/Table layout.txt` is a recognized Project Instructions reference file.
3335
- `docs_build/dev/admin-notes/notes/index.txt` is retained historical admin-note content.
3436

3537
Runtime boundary:
@@ -48,4 +50,3 @@ Runtime boundary:
4850
- name is up for discuttion (this is my ideas, things I want to fix, undecided question)
4951
[ ] Correction Notes update
5052
[subnote] should be /[subnote]/note.txt
51-

‎docs_build/dev/reports/PR_26175_OWNER_050-project-instructions-add-valid-reference-files.md‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
# PR_26175_OWNER_050-project-instructions-add-valid-reference-files
2+
3+
Date: 2026-06-24
4+
Team: OWNER
5+
Scope: Documentation/governance only
6+
Status: PASS
7+
8+
## Summary
9+
10+
- Added Project Reference Files Governance for recognized project instruction/reference documents.
11+
- Recognized `Installs required.txt` and `Table layout.txt` when present in `ProjectInstructions.zip`, the active project instruction directory, or `docs_build/dev/admin-notes/`.
12+
- Indexed the new addendum from the active Project Instructions README and operating-system root.
13+
- Updated the release gate, legacy startup guidance, root enforcement instructions, and admin-note ownership list so future reviews include these files automatically.
14+
- Added the two canonical admin-note reference files.
15+
- No runtime code changes and no UI changes were made.
16+
17+
## Branch Validation
18+
19+
PASS. Current branch is `codex/pr-26175-owner-050-project-instructions-add-valid-reference-files`, created from clean synchronized `main` at `99c53e368`.
20+
21+
## Instruction Compliance
22+
23+
- PASS: PR name includes OWNER team token.
24+
- PASS: Team OWNER owns governance/instruction-routing work.
25+
- PASS: Scope is documentation/governance only.
26+
- PASS: No runtime, UI, engine, backlog, or roadmap changes.
27+
- PASS: Required reports and ZIP artifact are produced for the BUILD.
28+
29+
## Changed Files
30+
31+
- `docs_build/dev/PROJECT_INSTRUCTIONS.md`
32+
- `docs_build/dev/ProjectInstructions/PROJECT_INSTRUCTIONS.md`
33+
- `docs_build/dev/ProjectInstructions/README.txt`
34+
- `docs_build/dev/ProjectInstructions/addendums/project_reference_files.md`
35+
- `docs_build/dev/ProjectInstructions/addendums/release_gate.md`
36+
- `docs_build/dev/admin-notes/index.txt`
37+
- `docs_build/dev/admin-notes/Installs required.txt`
38+
- `docs_build/dev/admin-notes/Table layout.txt`
39+
- `project-instructions/addendums/codex-project-instructions-startup.md`
40+
- `docs_build/pr/PLAN_PR_26175_OWNER_050-project-instructions-add-valid-reference-files.md`
41+
- `docs_build/dev/reports/PR_26175_OWNER_050-project-instructions-add-valid-reference-files.md`
42+
- `docs_build/dev/reports/PR_26175_OWNER_050-project-instructions-add-valid-reference-files_branch-validation.md`
43+
- `docs_build/dev/reports/PR_26175_OWNER_050-project-instructions-add-valid-reference-files_requirement-checklist.md`
44+
- `docs_build/dev/reports/PR_26175_OWNER_050-project-instructions-add-valid-reference-files_validation-lane.md`
45+
- `docs_build/dev/reports/PR_26175_OWNER_050-project-instructions-add-valid-reference-files_manual-validation-notes.md`
46+
- `docs_build/dev/reports/codex_changed_files.txt`
47+
- `docs_build/dev/reports/codex_review.diff`
48+
49+
## Required Reports
50+
51+
- `docs_build/dev/reports/codex_review.diff`
52+
- `docs_build/dev/reports/codex_changed_files.txt`
53+
- `docs_build/dev/reports/PR_26175_OWNER_050-project-instructions-add-valid-reference-files.md`
54+
- `docs_build/dev/reports/PR_26175_OWNER_050-project-instructions-add-valid-reference-files_branch-validation.md`
55+
- `docs_build/dev/reports/PR_26175_OWNER_050-project-instructions-add-valid-reference-files_requirement-checklist.md`
56+
- `docs_build/dev/reports/PR_26175_OWNER_050-project-instructions-add-valid-reference-files_validation-lane.md`
57+
- `docs_build/dev/reports/PR_26175_OWNER_050-project-instructions-add-valid-reference-files_manual-validation-notes.md`
58+
59+
## Validation
60+
61+
- PASS: `git status --short --branch`.
62+
- PASS: `git rev-list --left-right --count origin/main...HEAD`.
63+
- PASS: `git diff --name-only`.
64+
- PASS: `git diff --check`.
65+
- PASS: Targeted reference checks confirmed both filenames and the new addendum are referenced from active instruction surfaces.
66+
- PASS: File presence checks confirmed both canonical admin-note reference files exist.
67+
68+
## Artifact
69+
70+
- `tmp/PR_26175_OWNER_050-project-instructions-add-valid-reference-files_delta.zip`

‎docs_build/dev/reports/PR_26175_OWNER_050-project-instructions-add-valid-reference-files_branch-validation.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
# PR_26175_OWNER_050-project-instructions-add-valid-reference-files Branch Validation
2+
3+
## Branch
4+
`codex/pr-26175-owner-050-project-instructions-add-valid-reference-files`
5+
6+
## Base
7+
- Base branch: `origin/main`
8+
- Base commit at branch creation: `99c53e368`
9+
10+
## Checks
11+
- Current branch is the scoped OWNER_050 branch: PASS.
12+
- Branch was created from clean synchronized `main`: PASS.
13+
- Local/origin sync at branch creation was `0 0`: PASS.
14+
- Scope is limited to Project Instructions governance, admin-note reference files, plan, reports, and Codex review artifacts: PASS.
15+
- No runtime files changed: PASS.
16+
- No UI files changed: PASS.
17+
- No engine core files changed: PASS.
18+
- No backlog files changed: PASS.
19+
- No roadmap files changed: PASS.
20+
21+
## Result
22+
PASS

0 commit comments

Comments
 (0)