Refine Codex reports governance wording

ToolboxAid · ToolboxAid · commit af2489f8cfad · 2026-06-28T16:14:11.000-04:00
diff --git a/dev/build/ProjectInstructions/addendums/codex_artifact_and_reporting_standard.md b/dev/build/ProjectInstructions/addendums/codex_artifact_and_reporting_standard.md
@@ -97,19 +97,15 @@ Optional:
 
 Generated non-report artifacts must live under `dev/workspace/`.
 
-## Tracked Report Governance
+## Codex Reports
 
-`dev/reports/` is an authoritative repository report location and is tracked by Git.
-
-Rules:
-
-- Any changes to `dev/reports/` generated during a PR are expected to be included in that PR.
-- A clean `main` means the latest report files have been committed and merged.
-- Do not delete report files only to make the worktree clean.
+- `dev/reports/` contains the authoritative Codex reports for the repository.
+- Reports committed to `main` are the official record.
+- Reports generated during a PR are expected to be committed as part of that PR.
+- Once merged into `main`, those report versions become the canonical repository history.
+- Do not delete report files solely to obtain a clean worktree.
 - Do not add `dev/reports/` to `.gitignore`.
-- Do not move reports outside the repository.
-- Continue using `dev/reports/` for reports and `dev/workspace/zips/` for ZIPs.
-- Generated post-merge closeout reports should either be committed in a follow-up governance/report PR or avoided on `main` when no commit is intended.
+- Continue storing ZIPs under `dev/workspace/zips/`.
 
 ## Completion Reporting
 
diff --git a/dev/build/ProjectInstructions/addendums/pr_workflow.md b/dev/build/ProjectInstructions/addendums/pr_workflow.md
@@ -105,7 +105,7 @@ Closed gates:
 - PR merged and changes pushed.
 - Current branch is `main`.
 - `main` includes the merge commit or recorded final commit.
-- Worktree clean, including tracked `dev/reports/` updates committed and merged.
+- Worktree clean, including intended `dev/reports/` updates committed and merged.
 - Local/origin sync is `0/0`.
 - No untracked files.
 - Branch disposition is recorded as `retained`.
@@ -132,7 +132,7 @@ Closed gates:
 - If OWNER decision is required, stop and report.
 - Every PR lifecycle state must satisfy the Codex Completion Contract when Codex executes work for that state.
 - ZIP artifacts belong under `dev/workspace/zips/` and must not replace required reports under `dev/reports/`.
-- Generated reports under `dev/reports/` are tracked source for the PR. Do not delete report files only to make the worktree clean, do not ignore `dev/reports/`, and do not move reports outside the repository.
+- Reports generated during a PR are expected to be committed as part of that PR. Do not delete report files solely to obtain a clean worktree, and do not add `dev/reports/` to `.gitignore`.
 - Stacked PR chains produce one final outcome ZIP per attempted PR and stop before later PRs after failure or hard stop.
 
 ## Batch Governance Mode
diff --git a/dev/build/ProjectInstructions/repository/canonical_repository_structure.md b/dev/build/ProjectInstructions/repository/canonical_repository_structure.md
@@ -62,7 +62,7 @@ Dev workspace ownership:
 - dev/archive/ owns historical reference material only.
 - dev/build/ owns active Project Instructions, architecture, database DDL/DML/seed docs, standards, backlog, PR planning, and governance.
 - dev/config/ owns development-only runner and tooling configuration.
-- dev/reports/ owns active and historical generated reports. Report files under `dev/reports/` are authoritative tracked repository source and must not be deleted only to make the worktree clean.
+- dev/reports/ owns authoritative Codex reports for the repository. Reports committed to `main` are the official record.
 - dev/scripts/ owns development-only scripts and runners.
 - dev/templates/ owns reusable development templates.
 - dev/tests/ owns non-deployable test suites.
@@ -110,7 +110,7 @@ These legacy transition buckets may remain until explicit migration PRs move the
 - New development follows the canonical structure.
 - New deployable `src/` work follows `src/web/`, `src/api-runtime/`, or `src/runtime/`.
 - New non-deployable work belongs under `dev/`.
-- Required reports belong under flat tracked `dev/reports/`.
+- Required reports belong under flat `dev/reports/`.
 - Required ZIPs belong under `dev/workspace/zips/`; generated temporary artifacts belong under `dev/workspace/tmp/`.
 
 ## Creator Data Boundary
diff --git a/dev/reports/PR_26179_OWNER_036-reports-are-tracked-source_manual-validation-notes.md b/dev/reports/PR_26179_OWNER_036-reports-are-tracked-source_manual-validation-notes.md
@@ -8,4 +8,4 @@ Review the governance wording in:
 - `dev/build/ProjectInstructions/repository/canonical_repository_structure.md`
 - `dev/build/ProjectInstructions/addendums/pr_workflow.md`
 
-Confirm the policy says tracked report files are expected PR source, and that post-merge closeout reports should be committed in a follow-up governance/report PR or avoided on `main` when no commit is intended.
+Confirm the policy says `dev/reports/` contains authoritative Codex reports, reports committed to `main` are the official record, and PR-generated reports are expected to be committed as part of that PR.
diff --git a/dev/reports/PR_26179_OWNER_036-reports-are-tracked-source_report.md b/dev/reports/PR_26179_OWNER_036-reports-are-tracked-source_report.md
@@ -2,13 +2,13 @@
 
 ## Summary
 
-This governance PR clarifies that `dev/reports/` is authoritative tracked repository source. Codex-generated reports are expected to be committed with the PR that generated them, and generated post-merge closeout reports should be committed through a follow-up governance/report PR or avoided on `main` when no commit is intended.
+This governance PR clarifies that `dev/reports/` contains the authoritative Codex reports for the repository and that reports committed to `main` are the official record. Reports generated during a PR are expected to be committed as part of that PR, while repository authority remains the report state committed to `main`.
 
 ## Scope
 
 - Updated Codex artifact/reporting governance.
 - Updated canonical repository structure wording for `dev/reports/`.
-- Updated PR workflow clean-main guidance for tracked reports.
+- Updated PR workflow clean-main guidance for intended report updates.
 - Preserved the existing PR277 post-merge closeout report artifacts instead of deleting them.
 - No runtime code changes.
 - No auth changes.
@@ -17,15 +17,17 @@ This governance PR clarifies that `dev/reports/` is authoritative tracked reposi
 
 ## Policy Added
 
-- `dev/reports/` is authoritative and tracked by Git.
-- Any changes to `dev/reports/` generated during a PR are expected to be included in that PR.
-- A clean `main` means the latest report files have been committed and merged.
-- Do not delete report files only to make the worktree clean.
+- `dev/reports/` contains the authoritative Codex reports for the repository.
+- Reports committed to `main` are the official record.
+- Reports generated during a PR are expected to be committed as part of that PR.
+- Once merged into `main`, those report versions become the canonical repository history.
+- Do not delete report files solely to obtain a clean worktree.
 - Do not add `dev/reports/` to `.gitignore`.
-- Do not move reports outside the repository.
-- Continue using `dev/reports/` for reports and `dev/workspace/zips/` for ZIPs.
-- Generated post-merge closeout reports should either be committed in a follow-up governance/report PR or avoided on `main` if no commit is intended.
+- Continue storing ZIPs under `dev/workspace/zips/`.
 
 ## Validation
 
-Pending at report creation; final results are recorded in the validation report.
+PASS:
+
+- `git diff --check`
+- `npm run validate:canonical-structure`
diff --git a/dev/reports/PR_26179_OWNER_036-reports-are-tracked-source_requirement-checklist.md b/dev/reports/PR_26179_OWNER_036-reports-are-tracked-source_requirement-checklist.md
@@ -3,14 +3,13 @@
 Status: PASS
 
 - Update Project Instructions/governance docs only: PASS
-- Declare `dev/reports/` authoritative and tracked by Git: PASS
-- Require PR-generated `dev/reports/` changes to be included in the PR: PASS
-- Define clean `main` as latest report files committed and merged: PASS
-- Warn not to delete report files only to clean worktree: PASS
+- Declare `dev/reports/` contains authoritative Codex reports: PASS
+- Declare reports committed to `main` are the official record: PASS
+- Require PR-generated reports to be committed as part of the PR: PASS
+- Clarify repository authority is the report state committed to `main`: PASS
+- Warn not to delete report files solely to clean worktree: PASS
 - Warn not to add `dev/reports/` to `.gitignore`: PASS
-- Warn not to move reports outside the repo: PASS
 - Preserve `dev/reports/` and `dev/workspace/zips/` as canonical paths: PASS
-- Document post-merge closeout report handling: PASS
 - No runtime code changes: PASS
 - No auth changes: PASS
 - No Local API changes: PASS
diff --git a/dev/reports/PR_26179_OWNER_036-reports-are-tracked-source_validation-report.md b/dev/reports/PR_26179_OWNER_036-reports-are-tracked-source_validation-report.md
@@ -23,3 +23,5 @@ Canonical repository structure guardrail: PASS
 Blocking violations: 0
 Approved legacy exceptions: 500
 ```
+
+No runtime, auth, Local API, seed, or `.gitignore` changes were made.
diff --git a/dev/reports/codex_changed_files.txt b/dev/reports/codex_changed_files.txt
diff --git a/dev/reports/codex_review.diff b/dev/reports/codex_review.diff
