chore: enforce docs path rules + roadmap location guard & chore: enforce docs path rules + roadmap location guard

Author: DavidQ

docs/dev.zip

@@ -1,27 +1,48 @@
-Toolbox Aid
-David Quesenberry
-04/05/2026
-README.md
-
 # Active Dev Surface
 
 `docs/dev/` is the active execution surface only.
 
-## Active Files
+## Required Path Rules
+
+### Roadmaps
+All active roadmap files MUST live in:
+- `docs/dev/roadmaps/`
+
+The current master roadmap path is:
+- `docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md`
+
+Never use:
+- `docs/roadmaps/`
+- `docs/dev/BIG_PICTURE_ROADMAP.md` for the active master roadmap
+- any other duplicate roadmap location
+
+### Active Dev Files
+These may live directly under `docs/dev/` only when they are active operating files:
 - `README.md`
-- `RULES_OF_ENGAGEMENT.md` (single source of truth)
-- `codex_commands.md` (must remain header-free)
-- `commit_comment.txt` (must remain header-free)
+- `paths.md`
+- `PLANNING_SYSTEM_RULES.md`
+- `ROADMAP_GUARDRAILS.md`
+- `CODEX_COMMANDS.md`
+- `COMMIT_COMMENT.txt`
 - `next_command.txt`
-- `reports/change_summary.txt`
-- `reports/file_tree.txt`
-- `reports/validation_checklist.txt`
 
-## Archive Locations
-- Archived operational notes: `docs/archive/dev-ops/`
-- Archived generated reports: `docs/archive/generated-reports/`
+### Reports
+Generated reports must live in:
+- `docs/dev/reports/`
+
+### PR Docs
+PR docs must live in:
+- `docs/pr/`
+
+### Archive
+Archived/generated/historical material should live in:
+- `docs/archive/dev-ops/`
+- `docs/archive/generated-reports/`
+- `docs/archive/pr/legacy-pr-history/`
 
 ## Rules
 - Keep `docs/dev/` minimal and current.
-- Do not store stale generated bundles or duplicate operating notes in `docs/dev/`.
-- Preserve `docs/pr/` as historical record.
+- Keep active roadmap files only in `docs/dev/roadmaps/`.
+- Do not create `docs/roadmaps/`.
+- Do not leave transitional roadmap files duplicated in `docs/dev/`.
+- Preserve `docs/pr/` as historical PR record.

docs/dev/README.md

@@ -1,27 +1,40 @@
-# 🛡️ Roadmap Guardrails
+# Roadmap Guardrails
 
 ## Purpose
-Prevent accidental corruption of BIG_PICTURE_ROADMAP.md by enforcing strict update rules.
+Prevent accidental corruption or path drift of the active master roadmap.
 
-## RULE: TRACKER FILE PROTECTION
-The file `docs/dev/BIG_PICTURE_ROADMAP.md` is a status tracker only.
+## TRACKER FILE PROTECTION
+The active master roadmap file is:
+
+`docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md`
 
 ### Allowed Changes
-- Change ONLY:
-  - [ ] → [.] → [x]
+- Change ONLY bracket states:
+  - `[ ]` → `[.]` → `[x]`
 
 ### Forbidden Changes
 - Adding/removing sections
 - Rewriting text
 - Reordering items
 - Renaming tracks
 - Collapsing or expanding content
+- Moving the active master roadmap out of `docs/dev/roadmaps/`
+- Creating duplicate active roadmap copies elsewhere
+
+## PATH RULE
+All active roadmap files MUST live in:
+- `docs/dev/roadmaps/`
+
+Never use:
+- `docs/roadmaps/`
+- `docs/dev/BIG_PICTURE_ROADMAP.md` as the active master roadmap
 
-## VALIDATION CHECK
-Any change to BIG_PICTURE_ROADMAP.md must pass:
-- Headings unchanged
-- No text modified outside brackets
-- Only bracket states updated
+## Validation Check
+Any change to the active master roadmap must pass:
+- headings unchanged
+- no text modified outside brackets
+- only bracket states updated
+- file path remains under `docs/dev/roadmaps/`
 
-## CODEX RULE
-Codex must treat this file as immutable structure and perform surgical edits only.
+## Codex Rule
+Codex must treat the active roadmap as immutable structure and perform surgical edits only.

docs/dev/ROADMAP_GUARDRAILS.md

@@ -0,0 +1,19 @@
+# Repo Path Contracts
+
+## Active Paths
+- ROADMAP_PATH = `docs/dev/roadmaps/`
+- MASTER_ROADMAP = `docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md`
+- PR_PATH = `docs/pr/`
+- REPORTS_PATH = `docs/dev/reports/`
+
+## Archive Paths
+- DEV_OPS_ARCHIVE = `docs/archive/dev-ops/`
+- GENERATED_REPORTS_ARCHIVE = `docs/archive/generated-reports/`
+- PR_HISTORY_ARCHIVE = `docs/archive/pr/legacy-pr-history/`
+
+## Strict Rules
+1. Active roadmap files MUST live in `docs/dev/roadmaps/`.
+2. Never create or use `docs/roadmaps/`.
+3. Transitional roadmap files in `docs/dev/` must be moved into `docs/dev/roadmaps/` or archived.
+4. Reports belong in `docs/dev/reports/`.
+5. PR history belongs in `docs/pr/` or `docs/archive/pr/legacy-pr-history/`.

docs/dev/paths.md

@@ -0,0 +1,30 @@
+DOCS PATH CLEANUP PLAN
+
+KEEP WHERE IT IS
+- docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md
+- docs/dev/PLANNING_SYSTEM_RULES.md
+- docs/dev/CODEX_COMMANDS.md
+- docs/dev/COMMIT_COMMENT.txt
+- docs/dev/ROADMAP_GUARDRAILS.md
+- docs/dev/reports/*
+- docs/pr/*
+- docs/archive/*
+
+MOVE
+- docs/dev/BIG_PICTURE_ROADMAP.md
+  -> move to docs/dev/roadmaps/BIG_PICTURE_ROADMAP.md if still needed as an active roadmap
+  -> otherwise archive to docs/archive/dev-ops/ if superseded
+
+- docs/dev/reports/roadmap_move_manifest.txt
+  -> move to docs/archive/dev-ops/roadmap_move_manifest.txt after the roadmap move is complete
+  -> it is a transitional operational artifact, not a permanent active report
+
+DELETE
+- docs/roadmaps/
+  -> safe to delete if empty
+  -> do not recreate
+
+RULES
+- active roadmap files live only in docs/dev/roadmaps/
+- transitional move manifests should not remain in active reports forever
+- no duplicate active roadmap copies in multiple folders

docs/dev/reports/docs_path_cleanup_plan.txt

@@ -0,0 +1,14 @@
+# Roadmaps
+
+This folder is the only valid location for active roadmap files.
+
+## Active Master Roadmap
+- `MASTER_ROADMAP_HIGH_LEVEL.md`
+
+## Rule
+Do not place active roadmap files in:
+- `docs/roadmaps/`
+- `docs/dev/`
+
+Use this folder only:
+- `docs/dev/roadmaps/`