Skip to content

Commit 0a364f8

Browse files
ToolboxAidToolboxAid
authored
PR_26171_063 codex instruction enforcement hardening
Harden Codex instruction, owner, parity, report, ZIP, and functional parity gates.
1 parent 9aea9f8 commit 0a364f8

8 files changed

Lines changed: 549 additions & 472 deletions

‎docs_build/dev/PROJECT_INSTRUCTIONS.md‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2008,3 +2008,50 @@ Required Git workflow report fields:
20082008
- PR URL
20092009
- merge result
20102010
- final main commit
2011+
2012+
## CODEX INSTRUCTION ENFORCEMENT START GATE
2013+
2014+
Codex must run this gate before every PR execution and before any file changes.
2015+
2016+
Required instruction reads:
2017+
- Read `docs_build/dev/PROJECT_INSTRUCTIONS.md`.
2018+
- Read `docs_build/dev/PROJECT_MULTI_PC.txt`.
2019+
- Treat the newest applicable section in `PROJECT_INSTRUCTIONS.md` as authoritative when rules overlap.
2020+
- Treat the current owner/parity section in `PROJECT_MULTI_PC.txt` as authoritative for PC/Laptop routing.
2021+
2022+
Required pre-change report:
2023+
- Codex must report instruction compliance as `PASS` or `FAIL` before making file changes.
2024+
- The report must include branch, clean status, PR owner, PR parity, implementation path, validation scope, required report list, and ZIP requirement.
2025+
- Any `FAIL` is a hard stop unless the PR explicitly scopes branch audit or recovery documentation without implementation.
2026+
2027+
Hard stops before changes:
2028+
- If the current branch is not `main`, HARD STOP.
2029+
- If the repository is not clean before the PR branch is created, HARD STOP.
2030+
- If the PR owner does not match the PC/Laptop ownership map in `PROJECT_MULTI_PC.txt`, HARD STOP.
2031+
- If the PR number parity does not match the assigned machine in `PROJECT_MULTI_PC.txt`, HARD STOP.
2032+
- If the PR asks for implementation and the implementation path is wrong, HARD STOP.
2033+
- If a PR asks for functional parity and only placeholder-only work is possible, HARD STOP and report the missing source or blocker.
2034+
- If scoped validation is skipped without a documented reason, HARD STOP.
2035+
2036+
Path enforcement:
2037+
- Use the active path named by the PR and verified in the repository.
2038+
- Do not create wrong replacement paths.
2039+
- For Text To Speech work, the active toolbox path is `toolbox/text-to-speech/`.
2040+
- Do not create `tools/text2speech/` for new work.
2041+
- If a PR names archived tools, games, or samples as a functionality sample, treat the archive as a read-only reference sample, not as a reason to skip implementation.
2042+
2043+
Completion hard stops:
2044+
- If the required repo ZIP is missing, HARD STOP.
2045+
- If the required repo ZIP is empty or not under `tmp/`, HARD STOP.
2046+
- If required reports are missing, HARD STOP.
2047+
- If `docs_build/dev/reports/codex_review.diff` is missing, HARD STOP.
2048+
- If `docs_build/dev/reports/codex_changed_files.txt` is missing, HARD STOP.
2049+
- If manual validation notes are missing, HARD STOP.
2050+
- If the PR-specific report is missing, HARD STOP.
2051+
- If an instruction compliance checklist is required and missing, HARD STOP.
2052+
- If requested scoped validation did not run and no explicit skip reason is recorded, HARD STOP.
2053+
2054+
Functional parity rule:
2055+
- A PR that asks to restore or rebuild working functionality must produce functional parity with the approved sample or source.
2056+
- Placeholder shells, dead controls, static mockups, and nonfunctional UI are not acceptable completion states for functional parity PRs.
2057+
- If functional parity cannot be reached in scope, Codex must stop and report the exact blocker instead of packaging placeholder-only work.

‎docs_build/dev/PROJECT_MULTI_PC.txt‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -448,3 +448,61 @@ Queue next PR
448448
```
449449

450450
That is probably the fastest path to doubling throughput without creating chaos.
451+
452+
----------------------------------------------------------------------------------------
453+
454+
Current Authoritative Multi-PC Gate
455+
456+
Codex must read this file before every PR execution.
457+
458+
Machine parity:
459+
460+
PC / Environment 1:
461+
- Uses even-numbered PR sequence values.
462+
- Example: `PR_26171_064-*`.
463+
464+
Laptop / Environment 2:
465+
- Uses odd-numbered PR sequence values.
466+
- Example: `PR_26171_063-*`.
467+
468+
Owner map:
469+
470+
PC / Environment 1 owns Creator Journey work:
471+
- Game Journey
472+
- Game Hub
473+
- Idea
474+
- Design
475+
- Objects
476+
- Worlds
477+
- Interface
478+
- Controls
479+
- Rules
480+
- Progression
481+
- Play Test
482+
- Progress Tracking
483+
- Game Design
484+
- Game Crew
485+
486+
Laptop / Environment 2 owns Content Creation and asset/publishing work:
487+
- Graphics
488+
- Toolbox images
489+
- Audio
490+
- MIDI
491+
- Messages
492+
- Text To Speech
493+
- TTS
494+
- Publishing
495+
- Marketplace
496+
- Community
497+
- Arcade
498+
499+
Governance, recovery, diagnostics, and instruction-hardening PRs:
500+
- Follow PR number parity unless Master Control explicitly assigns an owner.
501+
- Must not implement tool/runtime work from the opposite owner.
502+
- Must document owner/parity compliance in the PR report.
503+
504+
Hard stop rules:
505+
- If the PR number parity does not match the current machine, stop before changes.
506+
- If the PR scope belongs to the other machine owner, stop before changes.
507+
- If the PR crosses PC and Laptop ownership, stop and require Master Control to split or assign the work.
508+
- If the requested implementation path conflicts with the active owner path, stop before changes.

‎docs_build/dev/reports/PR_26171_063-codex-instruction-enforcement-hardening.md‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
# PR_26171_063 Codex Instruction Enforcement Hardening
2+
3+
## Purpose
4+
5+
Make Codex explicitly obey `docs_build/dev/PROJECT_INSTRUCTIONS.md` and `docs_build/dev/PROJECT_MULTI_PC.txt` before every PR.
6+
7+
## Scope
8+
9+
- Added a Codex instruction enforcement start gate to `docs_build/dev/PROJECT_INSTRUCTIONS.md`.
10+
- Added current authoritative PC/Laptop owner and PR parity rules to `docs_build/dev/PROJECT_MULTI_PC.txt`.
11+
- Documented hard stops for branch state, clean status, owner mismatch, parity mismatch, wrong implementation paths, missing reports, missing ZIPs, skipped validation, and placeholder-only functional parity work.
12+
13+
## Requirement Checklist
14+
15+
- PASS: Codex must read `docs_build/dev/PROJECT_INSTRUCTIONS.md` before execution.
16+
- PASS: Codex must read `docs_build/dev/PROJECT_MULTI_PC.txt` before execution.
17+
- PASS: Codex must report instruction compliance PASS/FAIL before changes.
18+
- PASS: Codex must hard stop when not on `main` before starting.
19+
- PASS: Codex must hard stop when the repo is not clean before starting.
20+
- PASS: Codex must hard stop when PR owner does not match PC/Laptop ownership.
21+
- PASS: Codex must hard stop when PR number parity does not match assigned machine.
22+
- PASS: Codex must hard stop when required ZIP is missing.
23+
- PASS: Codex must hard stop when required reports are missing.
24+
- PASS: Codex must hard stop when implementation path is wrong.
25+
- PASS: Codex must hard stop when scoped validation was skipped without reason.
26+
- PASS: Codex must not continue with placeholder-only work when the PR asks for functional parity.
27+
- PASS: Codex must not create wrong paths such as `tools/text2speech` when active path is `toolbox/text-to-speech`.
28+
- PASS: Codex must not treat archived tools as "do not implement" when the PR says they are the functionality sample.
29+
30+
## Owner And Parity Evidence
31+
32+
- Current PR: `PR_26171_063-codex-instruction-enforcement-hardening`.
33+
- Sequence: `063`.
34+
- Sequence parity: odd.
35+
- Assigned machine under the new authoritative gate: Laptop / Environment 2.
36+
- Scope type: governance, recovery, diagnostics, and instruction-hardening.
37+
- Result: PASS because governance/instruction-hardening PRs follow PR number parity unless Master Control explicitly assigns another owner.
38+
39+
## Validation Scope
40+
41+
- Playwright impacted: No.
42+
- No Playwright impact. This PR is docs/workflow only.
43+
- Validation is docs/static only.
44+
- Runtime, tool, engine, samples, and Game Hub validation are skipped because no runtime, UI, toolState, engine, or sample behavior changed.
45+
46+
## ZIP
47+
48+
- Required ZIP path: `tmp/PR_26171_063-codex-instruction-enforcement-hardening_delta.zip`.

‎docs_build/dev/reports/PR_26171_063-instruction-compliance-checklist.md‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
# PR_26171_063 Instruction Compliance Checklist
2+
3+
## Pre-Change Gate
4+
5+
- PASS: Read `docs_build/dev/PROJECT_INSTRUCTIONS.md` before file changes.
6+
- PASS: Read `docs_build/dev/PROJECT_MULTI_PC.txt` before file changes.
7+
- PASS: Reported instruction compliance PASS/FAIL before file changes.
8+
- PASS: Starting branch was `main`.
9+
- PASS: Starting repository status was clean.
10+
- PASS: Created scoped branch `pr/26171-063-codex-instruction-enforcement-hardening` after the clean `main` check.
11+
12+
## Current PR Routing
13+
14+
- PASS: PR number `063` is odd.
15+
- PASS: Odd PR parity maps to Laptop / Environment 2 under the new authoritative Multi-PC gate.
16+
- PASS: PR scope is instruction/governance hardening and follows parity because no Master Control owner override was provided.
17+
- PASS: No PC-owned tool implementation was changed.
18+
- PASS: No Laptop-owned tool implementation was changed.
19+
20+
## Path And Functional Parity Gate
21+
22+
- PASS: No implementation path was changed by this docs-only PR.
23+
- PASS: `toolbox/text-to-speech/` is documented as the active Text To Speech path.
24+
- PASS: `tools/text2speech/` is documented as a wrong new-work path.
25+
- PASS: Placeholder-only functional parity work is prohibited.
26+
- PASS: Archived functionality samples are documented as read-only reference samples when explicitly named by a PR.
27+
28+
## Completion Gate
29+
30+
- PASS: Required PR-specific report exists.
31+
- PASS: Required instruction compliance checklist exists.
32+
- PASS: Required manual validation notes exist.
33+
- PASS: Required `docs_build/dev/reports/codex_review.diff` exists after artifact generation.
34+
- PASS: Required `docs_build/dev/reports/codex_changed_files.txt` exists after artifact generation.
35+
- PASS: Required ZIP exists after packaging.
36+
- PASS: Scoped validation was not skipped; docs/static validation was run.
37+
- PASS: Playwright was not run because the PR explicitly requires no Playwright.

‎docs_build/dev/reports/PR_26171_063-manual-validation-notes.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# PR_26171_063 Manual Validation Notes
2+
3+
## Manual Review
4+
5+
- Confirmed the new start gate requires reading `PROJECT_INSTRUCTIONS.md` and `PROJECT_MULTI_PC.txt` before every PR.
6+
- Confirmed the new gate requires visible PASS/FAIL instruction compliance before file changes.
7+
- Confirmed the hard stop list covers branch, clean status, owner, parity, required ZIP, required reports, wrong paths, skipped validation, and placeholder-only functional parity work.
8+
- Confirmed Text To Speech path enforcement names `toolbox/text-to-speech/` as active and rejects new `tools/text2speech/` work.
9+
- Confirmed archived tools can be used as read-only functionality samples when a PR explicitly names them.
10+
11+
## Manual Runtime Checks
12+
13+
- No Playwright was run.
14+
- No browser runtime checks were performed.
15+
- No Project Workspace/Game Hub runtime checks were performed.
16+
- No Local API checks were performed.
17+
- No Text To Speech runtime checks were performed.
18+
19+
These checks are out of scope because this PR only changes documentation and governance reports.

‎docs_build/dev/reports/PR_26171_063-validation.md‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
# PR_26171_063 Validation
2+
3+
## Scope
4+
5+
Docs/static validation only.
6+
7+
No Playwright was run because the PR explicitly says "No Playwright" and the changed files are governance docs and reports only.
8+
9+
## Commands
10+
11+
- `git diff --check`
12+
- PASS: no whitespace errors.
13+
- Targeted required-text validation for `docs_build/dev/PROJECT_INSTRUCTIONS.md`, `docs_build/dev/PROJECT_MULTI_PC.txt`, and PR_26171_063 reports.
14+
- PASS: all required hardening anchors were found.
15+
- Note: the first targeted text check found missing exact `No Playwright` wording in manual notes; the note was corrected and the validation was rerun successfully.
16+
17+
## Skipped
18+
19+
- `npm run test:workspace-v2`
20+
- SKIP: legacy command name for Project Workspace/Game Hub validation; no workspace or toolState behavior changed.
21+
- `npm run test:playwright:static`
22+
- SKIP: command name is Playwright-scoped and this PR explicitly says no Playwright.
23+
- Runtime, tool, engine, samples, and browser validation
24+
- SKIP: docs/workflow-only change.
25+
26+
## Artifact Verification
27+
28+
- PASS: `docs_build/dev/reports/codex_review.diff` exists.
29+
- PASS: `docs_build/dev/reports/codex_changed_files.txt` exists.
30+
- PASS: `tmp/PR_26171_063-codex-instruction-enforcement-hardening_delta.zip` exists.
31+
- PASS: ZIP size is greater than zero.
32+
- PASS: ZIP contents preserve repo-relative paths.

‎docs_build/dev/reports/codex_changed_files.txt‎

Lines changed: 28 additions & 53 deletions
Original file line numberDiff line numberDiff line change
@@ -1,62 +1,37 @@
1-
# Codex Changed Files - PR_26171_040-idea-board-production-copy-cleanup
1+
# Codex Changed Files - PR_26171_063-codex-instruction-enforcement-hardening
22

3-
## Git Workflow
4-
- Current branch: `codex/pr-26171-040-idea-board-production-copy-cleanup`.
5-
- Expected starting branch: `main` (PASS before branch creation).
6-
- Created branch: `codex/pr-26171-040-idea-board-production-copy-cleanup`.
7-
- Commit before conflict resolution: `acbc5b113e9e90a4051e810897415ea222040ddd`.
8-
- Initial push result: PASS, branch pushed to `origin/codex/pr-26171-040-idea-board-production-copy-cleanup`.
9-
- PR URL: `https://github.com/ToolboxAid/HTML-JavaScript-Gaming/pull/15`.
10-
- Conflict resolution: merged `origin/main` at `7393b650228c84d266701cc3f4ce3696029dd47e`; conflicts were limited to `codex_changed_files.txt` and `codex_review.diff`.
11-
- Conflict resolution push result: pending until after merge-validation commit.
12-
- Merge result: pending until after PR validation/merge.
13-
- Final main sync: pending until after merge and final pull.
3+
## Conflict Resolution Note
4+
- Merged latest `origin/main` into the PR branch after GitHub reported merge conflicts.
5+
- Regenerated Codex artifacts from the PR_063 delta against updated `origin/main`.
6+
- No implementation scope was changed while resolving conflicts.
147

158
## Changed Files
16-
- docs_build/dev/reports/codex_changed_files.txt
9+
- docs_build/dev/PROJECT_INSTRUCTIONS.md
10+
- docs_build/dev/PROJECT_MULTI_PC.txt
11+
- docs_build/dev/reports/PR_26171_063-codex-instruction-enforcement-hardening.md
12+
- docs_build/dev/reports/PR_26171_063-instruction-compliance-checklist.md
13+
- docs_build/dev/reports/PR_26171_063-validation.md
14+
- docs_build/dev/reports/PR_26171_063-manual-validation-notes.md
1715
- docs_build/dev/reports/codex_review.diff
18-
- docs_build/dev/reports/coverage_changed_js_guardrail.txt
19-
- docs_build/dev/reports/playwright_v8_coverage_report.txt
20-
- src/dev-runtime/server/local-api-router.mjs
21-
- src/shared/toolbox/tool-metadata-inventory.js
22-
- tests/playwright/tools/IdeaBoardTableNotes.spec.mjs
23-
- tests/playwright/tools/ToolboxRoutePages.spec.mjs
24-
- toolbox/idea-board/index.html
25-
- toolbox/idea-board/index.js
16+
- docs_build/dev/reports/codex_changed_files.txt
2617

27-
## Requirement Evidence
28-
- PASS: Creator-visible Idea Board page copy no longer uses DB-shaped, in-page data model, ID/flag/metadata/seed/debug/mock/test/internal wording.
29-
- PASS: Shared Toolbox metadata for Idea Board now uses simple creator-facing language for short description, description, and progress checklist text.
30-
- PASS: Existing persisted Toolbox metadata rows now source-sync Idea Board copy so the browser-visible registry summary updates from source-controlled text.
31-
- PASS: Idea Board table workflow, Add Idea, Add Note, Edit/Delete, Save/Cancel, Status dropdown, accordion behavior, notes under idea rows, and existing in-page data structure were preserved.
32-
- PASS: Targeted Playwright production-copy checks verify the Idea Board main surface does not expose the prohibited creator-visible wording.
33-
- PASS: Copied/adapted files verified as not applicable for this copy-only PR; no Tool Template V2 file copy was required.
18+
## Git Diff Stat Against Updated origin/main
19+
```text
20+
docs_build/dev/PROJECT_INSTRUCTIONS.md | 47 ++
21+
docs_build/dev/PROJECT_MULTI_PC.txt | 58 ++
22+
..._063-codex-instruction-enforcement-hardening.md | 48 ++
23+
...R_26171_063-instruction-compliance-checklist.md | 37 ++
24+
.../PR_26171_063-manual-validation-notes.md | 19 +
25+
docs_build/dev/reports/PR_26171_063-validation.md | 32 +
26+
docs_build/dev/reports/codex_changed_files.txt | 48 ++
27+
docs_build/dev/reports/codex_review.diff | 699 +++++++++------------
28+
8 files changed, 569 insertions(+), 419 deletions(-)
29+
```
3430

3531
## Validation
36-
- PASS: `node --check toolbox/idea-board/index.js`.
37-
- PASS: `node --check src/dev-runtime/server/local-api-router.mjs`.
38-
- PASS: `node --check src/shared/toolbox/tool-metadata-inventory.js`.
39-
- PASS: `node --check tests/playwright/tools/IdeaBoardTableNotes.spec.mjs`.
40-
- PASS: `node --check tests/playwright/tools/ToolboxRoutePages.spec.mjs`.
41-
- PASS: `npx playwright test tests/playwright/tools/IdeaBoardTableNotes.spec.mjs --project=playwright --workers=1 --reporter=line`.
42-
- PASS: `npx playwright test tests/playwright/tools/ToolboxRoutePages.spec.mjs --project=playwright --workers=1 --reporter=line -g "Idea Board launches"`.
43-
- PASS: `git diff --check`.
44-
- PASS: Post-conflict rerun completed after merging `origin/main` at `7393b650228c84d266701cc3f4ce3696029dd47e`.
45-
- PASS: Playwright V8 coverage report produced because runtime JavaScript changed.
46-
- WARN: Coverage report marks `src/dev-runtime/server/local-api-router.mjs` and `src/shared/toolbox/tool-metadata-inventory.js` as not collected by browser V8 coverage; advisory only per project instructions.
47-
- SKIPPED: Full samples smoke was not run per request.
32+
- PASS: `git diff --check` after conflict resolution.
33+
- PASS: targeted required instruction-anchor validation after conflict resolution.
34+
- SKIP: Playwright, because the PR explicitly requires no Playwright and changes docs/workflow only.
4835

4936
## ZIP
50-
- Path: `tmp/PR_26171_040-idea-board-production-copy-cleanup_delta.zip`.
51-
- Size: final size reported in the delivery summary after conflict-resolution ZIP refresh.
52-
- Contents:
53-
- docs_build/dev/reports/codex_changed_files.txt
54-
- docs_build/dev/reports/codex_review.diff
55-
- docs_build/dev/reports/coverage_changed_js_guardrail.txt
56-
- docs_build/dev/reports/playwright_v8_coverage_report.txt
57-
- src/dev-runtime/server/local-api-router.mjs
58-
- src/shared/toolbox/tool-metadata-inventory.js
59-
- tests/playwright/tools/IdeaBoardTableNotes.spec.mjs
60-
- tests/playwright/tools/ToolboxRoutePages.spec.mjs
61-
- toolbox/idea-board/index.html
62-
- toolbox/idea-board/index.js
37+
- Path: `tmp/PR_26171_063-codex-instruction-enforcement-hardening_delta.zip`.

0 commit comments

Comments
 (0)