projecta-rrr 1.15.0 → 1.15.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "projecta-rrr",
-  "version": "1.15.0",
+  "version": "1.15.2",
   "description": "A meta-prompting, context engineering and spec-driven development system for Claude Code by Projecta.ai",
   "bin": {
     "projecta-rrr": "bin/install.js"

package/rrr/workflows/complete-milestone.md

@@ -421,17 +421,17 @@ Extract completed milestone details and create archive file.
 
 **Process:**
 
-1. Ensure archive directory exists (Cross-Platform):
+1. Ensure milestone directory exists (Cross-Platform):
 
    **On macOS/Linux:**
    ```bash
-   mkdir -p .planning/archived/roadmaps
+   mkdir -p .planning/milestones/v[X.Y]
    ```
 
    **On Windows:**
    Use Write tool to create a placeholder file, or directory will be created when writing archive.
 
-2. Create archive file path: `.planning/archived/roadmaps/ROADMAP-v[X.Y].md`
+2. Create archive file path: `.planning/milestones/v[X.Y]/ROADMAP.md`
 
 3. Read `~/.claude/rrr/templates/milestone-archive.md` template
 
@@ -456,17 +456,17 @@ Extract completed milestone details and create archive file.
    - {{DECISIONS_FROM_PROJECT}} — Key decisions from PROJECT.md
    - {{ISSUES_RESOLVED_DURING_MILESTONE}} — From summaries
 
-7. Write filled template to `.planning/archived/roadmaps/ROADMAP-v[X.Y].md`
+7. Write filled template to `.planning/milestones/v[X.Y]/ROADMAP.md`
 
 8. Verify archive exists (Cross-Platform):
 
    **On macOS/Linux:**
    ```bash
-   ls .planning/archived/roadmaps/ROADMAP-v[X.Y].md
+   ls .planning/milestones/v[X.Y]/ROADMAP.md
    ```
 
    **On Windows:**
-   Use Glob tool: `pattern: ".planning/archived/roadmaps/ROADMAP-v[X.Y].md"`
+   Use Glob tool: `pattern: ".planning/milestones/v[X.Y]/ROADMAP.md"`
 
 9. **Create fresh ROADMAP.md** (CRITICAL: must always exist):
 
@@ -480,7 +480,7 @@ Extract completed milestone details and create archive file.
    ## Completed Milestones
 
    - ✅ **v[X.Y] [Name]** — Phases [X-Y] (shipped [DATE])
-     - Archive: `.planning/archived/roadmaps/ROADMAP-v[X.Y].md`
+     - Archive: `.planning/milestones/v[X.Y]/`
 
    ## Next Milestone
 
@@ -506,7 +506,7 @@ Extract completed milestone details and create archive file.
    ✅ Fresh ROADMAP.md created (between milestones state)
    ```
 
-**Note:** Phase directories (`.planning/phases/`) are NOT deleted. They accumulate across milestones as the raw execution history. Phase numbering continues (v1.0 phases 1-4, v1.1 phases 5-8, etc.).
+**Note:** Phase directories are moved to `.planning/milestones/v[X.Y]/phases/` in the next step. This keeps each milestone's execution history self-contained in its archive folder.
 
 </step>
 
@@ -521,7 +521,7 @@ Archive requirements and prepare for fresh requirements in next milestone.
    cat .planning/REQUIREMENTS.md
    ```
 
-2. Create archive file: `.planning/milestones/v[X.Y]-REQUIREMENTS.md`
+2. Create archive file: `.planning/milestones/v[X.Y]/REQUIREMENTS.md`
 
 3. Transform requirements for archive:
    - Mark all v1 requirements as `[x]` complete
@@ -565,7 +565,7 @@ Archive requirements and prepare for fresh requirements in next milestone.
 
 6. Confirm:
    ```
-   ✅ Requirements archived to milestones/v[X.Y]-REQUIREMENTS.md
+   ✅ Requirements archived to milestones/v[X.Y]/REQUIREMENTS.md
    ✅ REQUIREMENTS.md deleted (fresh one needed for next milestone)
    ```
 
@@ -578,19 +578,112 @@ Archive requirements and prepare for fresh requirements in next milestone.
 Move the milestone audit file to the archive (if it exists):
 
 ```bash
-# Move audit to milestones folder (if exists)
-[ -f .planning/v[X.Y]-MILESTONE-AUDIT.md ] && mv .planning/v[X.Y]-MILESTONE-AUDIT.md .planning/milestones/
+# Move audit to milestone folder (if exists)
+[ -f .planning/v[X.Y]-MILESTONE-AUDIT.md ] && mv .planning/v[X.Y]-MILESTONE-AUDIT.md .planning/milestones/v[X.Y]/MILESTONE-AUDIT.md
 ```
 
 Confirm:
 ```
-✅ Audit archived to milestones/v[X.Y]-MILESTONE-AUDIT.md
+✅ Audit archived to milestones/v[X.Y]/MILESTONE-AUDIT.md
 ```
 
 (Skip silently if no audit file exists — audit is optional)
 
 </step>
 
+<step name="move_phases">
+
+Move completed milestone phase directories to the milestone archive folder.
+
+**Process:**
+
+1. Create milestone phases directory:
+   ```bash
+   mkdir -p .planning/milestones/v[X.Y]/phases
+   ```
+
+2. Get list of phases in this milestone (from roadmap archive or phase numbers):
+   ```bash
+   # For each phase number in milestone range (e.g., 47-51):
+   for phase_num in {PHASE_START}..{PHASE_END}; do
+     # Find phase directory by number prefix
+     phase_dir=$(ls -d .planning/phases/${phase_num}-* 2>/dev/null | head -1)
+     if [ -n "$phase_dir" ] && [ -d "$phase_dir" ]; then
+       mv "$phase_dir" .planning/milestones/v[X.Y]/phases/
+     fi
+   done
+   ```
+
+3. Verify phases moved (Cross-Platform):
+
+   **On macOS/Linux:**
+   ```bash
+   ls .planning/milestones/v[X.Y]/phases/
+   ```
+
+   **On Windows:**
+   Use Glob: `pattern: ".planning/milestones/v[X.Y]/phases/*"`
+
+4. Confirm:
+   ```
+   ✅ Phases [PHASE_START]-[PHASE_END] moved to milestones/v[X.Y]/phases/
+   ```
+
+**Why move phases:**
+- Keeps milestone archives self-contained (roadmap + requirements + phases)
+- `.planning/phases/` only contains active/upcoming work
+- Reduces clutter in phases directory as project matures
+- Phase lookup still works via `find_phase_dir()` which searches both locations
+
+</step>
+
+<step name="consolidate_legacy_files">
+
+Consolidate any scattered milestone files from older formats into the unified folder structure.
+
+**Process:**
+
+This step cleans up legacy file locations from before the unified milestone folder structure was introduced.
+
+```bash
+# For each milestone folder that exists
+for milestone_dir in .planning/milestones/v*/; do
+  version=$(basename "$milestone_dir")  # e.g., "v1.10"
+
+  # Move scattered REQUIREMENTS file if exists at milestones/ level
+  [ -f ".planning/milestones/${version}-REQUIREMENTS.md" ] && \
+    mv ".planning/milestones/${version}-REQUIREMENTS.md" "${milestone_dir}REQUIREMENTS.md"
+
+  # Move scattered MILESTONE-AUDIT file if exists at milestones/ level
+  [ -f ".planning/milestones/${version}-MILESTONE-AUDIT.md" ] && \
+    mv ".planning/milestones/${version}-MILESTONE-AUDIT.md" "${milestone_dir}MILESTONE-AUDIT.md"
+
+  # Move scattered ROADMAP file if exists at milestones/ level
+  [ -f ".planning/milestones/${version}-ROADMAP.md" ] && \
+    mv ".planning/milestones/${version}-ROADMAP.md" "${milestone_dir}ROADMAP.md"
+
+  # Move ROADMAP from archived/roadmaps/ if exists there
+  [ -f ".planning/archived/roadmaps/ROADMAP-${version}.md" ] && \
+    mv ".planning/archived/roadmaps/ROADMAP-${version}.md" "${milestone_dir}ROADMAP.md"
+done
+
+# Clean up empty archived directory if all roadmaps moved
+rmdir .planning/archived/roadmaps 2>/dev/null || true
+rmdir .planning/archived 2>/dev/null || true
+```
+
+**Confirm (only if files were moved):**
+```
+✅ Consolidated legacy milestone files into unified folders
+```
+
+**Why consolidate:**
+- Maintains backwards compatibility with older projects
+- Ensures all milestone data is in one place
+- Simplifies navigation and backup
+
+</step>
+
 <step name="update_state">
 
 Update STATE.md to reflect milestone completion.
@@ -662,10 +755,8 @@ git push origin v[X.Y]
 Commit milestone completion including archive files.
 
 ```bash
-# Stage archive files (new location)
-git add .planning/archived/roadmaps/ROADMAP-v[X.Y].md
-git add .planning/milestones/v[X.Y]-REQUIREMENTS.md
-git add .planning/milestones/v[X.Y]-MILESTONE-AUDIT.md 2>/dev/null || true
+# Stage milestone archive folder (contains ROADMAP.md, REQUIREMENTS.md, MILESTONE-AUDIT.md, phases/)
+git add .planning/milestones/v[X.Y]/
 
 # Stage updated/created files
 git add .planning/MILESTONES.md
@@ -680,16 +771,18 @@ git add -u .planning/REQUIREMENTS.md 2>/dev/null || true
 git commit -m "$(cat <<'EOF'
 chore: complete v[X.Y] milestone
 
-Archived:
-- archived/roadmaps/ROADMAP-v[X.Y].md (old roadmap)
-- milestones/v[X.Y]-REQUIREMENTS.md
-- milestones/v[X.Y]-MILESTONE-AUDIT.md (if audit was run)
+Archived to milestones/v[X.Y]/:
+- ROADMAP.md (milestone roadmap)
+- REQUIREMENTS.md (milestone requirements)
+- MILESTONE-AUDIT.md (if audit was run)
+- phases/ (all phase directories moved)
 
 Created:
 - ROADMAP.md (fresh, between milestones state)
 
 Deleted:
 - REQUIREMENTS.md (fresh one needed for next milestone)
+- phases/[X]-* through phases/[Y]-* (moved to milestone folder)
 
 Updated:
 - MILESTONES.md (new entry)
@@ -715,8 +808,7 @@ Shipped:
 - [One sentence of what shipped]
 
 Archived:
-- milestones/v[X.Y]-ROADMAP.md
-- milestones/v[X.Y]-REQUIREMENTS.md
+- milestones/v[X.Y]/ (ROADMAP.md, REQUIREMENTS.md, phases/)
 
 Summary: .planning/MILESTONES.md
 Tag: v[X.Y]
@@ -791,10 +883,13 @@ Milestone completion is successful when:
 - [ ] PROJECT.md full evolution review completed
 - [ ] All shipped requirements moved to Validated in PROJECT.md
 - [ ] Key Decisions updated with outcomes
-- [ ] Roadmap archive created (archived/roadmaps/ROADMAP-v[X.Y].md)
+- [ ] Milestone folder created (milestones/v[X.Y]/)
+- [ ] Roadmap archive created (milestones/v[X.Y]/ROADMAP.md)
 - [ ] Fresh ROADMAP.md created (between milestones state) — MUST ALWAYS EXIST
-- [ ] Requirements archive created (milestones/v[X.Y]-REQUIREMENTS.md)
+- [ ] Requirements archive created (milestones/v[X.Y]/REQUIREMENTS.md)
 - [ ] REQUIREMENTS.md deleted (fresh for next milestone)
+- [ ] Phase directories moved to milestones/v[X.Y]/phases/
+- [ ] Legacy scattered files consolidated into milestone folders
 - [ ] STATE.md updated with fresh project reference
 - [ ] Git tag created (v[X.Y])
 - [ ] Milestone commit made (includes archive files)