|
| 1 | +# BUILD_PR_LEVEL_18_20_TRACK_H_PR_CONSOLIDATION_EXECUTION |
| 2 | + |
| 3 | +## Purpose |
| 4 | +Execute Track H (PR Consolidation Strategy) as real repo work by consolidating fragmented PR review surfaces into capability-level review units and adding enforceable repo-side guidance so future PRs are packaged as complete capabilities. |
| 5 | + |
| 6 | +## Roadmap intent |
| 7 | +This PR may advance the following Track H items only if fully executed and validated: |
| 8 | +- `bundle related PRs into capability-level units` `[ ] -> [x]` |
| 9 | +- `reduce multi-PR fragmentation` `[ ] -> [x]` |
| 10 | +- `ensure each PR represents a complete capability` `[ ] -> [x]` |
| 11 | +- parent `Track H - PR Consolidation Strategy` `[ ] -> [x]` |
| 12 | + |
| 13 | +## Scope |
| 14 | +Included: |
| 15 | +- audit fragmented PR/doc capability history in `docs/pr/` |
| 16 | +- identify related PR clusters that should be reviewed as one capability |
| 17 | +- create capability-level consolidation docs/indexes so reviewers can consume one capability from one place |
| 18 | +- add repo-side PR packaging guidance/checklist that enforces complete-capability PRs going forward |
| 19 | +- normalize active PR guidance references to point at capability-level units |
| 20 | +- produce validation reports |
| 21 | +- preserve unrelated working-tree changes |
| 22 | + |
| 23 | +Excluded: |
| 24 | +- no implementation/runtime feature work |
| 25 | +- no engine/shared/game/tool behavior changes |
| 26 | +- no Track 20 work |
| 27 | +- no roadmap text rewrites |
| 28 | +- no deletion of roadmap content |
| 29 | +- no `start_of_day` modifications |
| 30 | +- no broad doc cleanup outside PR-consolidation purpose |
| 31 | + |
| 32 | +## Hard guards |
| 33 | +- one PR purpose only: complete Track H |
| 34 | +- docs-first |
| 35 | +- execution-backed only |
| 36 | +- no commit-only packaging |
| 37 | +- any deleted or superseded PR doc must be replaced by authoritative capability-level review surfaces |
| 38 | +- preserve historical traceability: old PR identifiers must remain discoverable through index/mapping docs even if review is consolidated |
| 39 | +- roadmap changes must be status-only and only after validation |
| 40 | + |
| 41 | +## Required outputs |
| 42 | +Codex must create/update: |
| 43 | +- `docs/dev/reports/BUILD_PR_LEVEL_18_20_TRACK_H_PR_CONSOLIDATION_EXECUTION_FRAGMENTATION_AUDIT.md` |
| 44 | +- `docs/dev/reports/BUILD_PR_LEVEL_18_20_TRACK_H_PR_CONSOLIDATION_EXECUTION_CAPABILITY_GROUPS.md` |
| 45 | +- `docs/dev/reports/BUILD_PR_LEVEL_18_20_TRACK_H_PR_CONSOLIDATION_EXECUTION_CONSOLIDATION_MAP.md` |
| 46 | +- `docs/dev/reports/BUILD_PR_LEVEL_18_20_TRACK_H_PR_CONSOLIDATION_EXECUTION_VALIDATION.md` |
| 47 | +- `docs/dev/templates/pr_capability_bundle_checklist.md` |
| 48 | + |
| 49 | +Capability review surfaces to create/update as needed: |
| 50 | +- `docs/pr/capabilities/`... |
| 51 | +- or another clearly named capability-level folder under `docs/pr/` |
| 52 | + |
| 53 | +## Execution details |
| 54 | + |
| 55 | +### 1) Fragmentation audit |
| 56 | +Audit `docs/pr/` and identify clusters where one capability is split across many small PR docs. |
| 57 | +For each cluster, record: |
| 58 | +- capability name |
| 59 | +- related PR docs |
| 60 | +- why the cluster is fragmented |
| 61 | +- recommended authoritative review doc |
| 62 | + |
| 63 | +### 2) Capability-level consolidation |
| 64 | +For each fragmented cluster selected in this PR: |
| 65 | +- create one authoritative capability review doc |
| 66 | +- summarize what the capability does, current status, linked artifacts, and validation path |
| 67 | +- preserve traceability back to original PR docs |
| 68 | +- reduce reviewer need to open many PR docs to understand one capability |
| 69 | + |
| 70 | +### 3) Future enforcement guidance |
| 71 | +Create/update a reusable checklist/template that future PR bundles must satisfy: |
| 72 | +- one complete capability per PR where possible |
| 73 | +- avoid fragmented partial-review PRs |
| 74 | +- include execution + validation + roadmap advancement expectations |
| 75 | +- preserve ZIP workflow and docs-first rules |
| 76 | + |
| 77 | +### 4) Reference normalization |
| 78 | +Where active repo instructions or PR navigation docs point to fragmented review surfaces, update those pointers to the new capability-level authoritative surfaces. |
| 79 | + |
| 80 | +## Acceptance |
| 81 | +- fragmented PR clusters are audited and documented |
| 82 | +- capability-level authoritative review docs exist for fragmented clusters addressed by this PR |
| 83 | +- reviewers can navigate one capability from one authoritative surface |
| 84 | +- future PR packaging guidance exists and is explicit |
| 85 | +- traceability from original PR docs to consolidated capability docs is preserved |
| 86 | +- roadmap updates are status-only and execution-backed |
| 87 | +- Track H is complete only if all three Track H items are validated |
| 88 | + |
| 89 | +## Validation requirements |
| 90 | +Validation must confirm: |
| 91 | +- number of fragmented clusters found |
| 92 | +- number of capability-level authoritative docs created/updated |
| 93 | +- original PR traceability preserved |
| 94 | +- active navigation pointers updated where applicable |
| 95 | +- no `start_of_day` changes |
| 96 | +- unrelated working-tree changes preserved |
| 97 | +- roadmap edits are limited to Track H status-only transitions |
| 98 | + |
| 99 | +## Roadmap update rules |
| 100 | +Only update status markers in the current repo roadmap file. |
| 101 | + |
| 102 | +Allowed transitions only if fully executed and validated: |
| 103 | +- `bundle related PRs into capability-level units` `[ ] -> [x]` |
| 104 | +- `reduce multi-PR fragmentation` `[ ] -> [x]` |
| 105 | +- `ensure each PR represents a complete capability` `[ ] -> [x]` |
| 106 | +- parent `Track H - PR Consolidation Strategy` `[ ] -> [x]` |
| 107 | + |
| 108 | +Do not change Track 20 in this PR. |
0 commit comments