projecta-rrr 1.18.4 → 1.18.6

package/CHANGELOG.md

@@ -4,6 +4,35 @@ All notable changes to RRR will be documented in this file.
 
 Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [1.18.6] - 2026-02-01
+
+### Fixed
+
+- **plan-phase milestone research lookup** - Now checks milestone research folder first, falls back to project research
+- **create-roadmap milestone research lookup** - Now uses milestone-aware research context
+
+## [1.18.5] - 2026-02-01
+
+### Added
+
+- **Two-tier research architecture** - Project research (foundational) + Milestone research (tactical)
+  - Project research: `.planning/research/` — domain ecosystem, done once at project start
+  - Milestone research: `.planning/milestones/vX.Y/research/` — tactical research per milestone
+  - Milestone research inherits from project research and can update ROADMAP.md/REQUIREMENTS.md
+
+### Changed
+
+- **REQUIREMENTS.md** - Now has milestone sections (Validated, Active, Future Candidates)
+- **`/rrr:new-milestone`** - Added milestone research step with inheritance
+- **`/rrr:define-requirements`** - Checks milestone research folder first, falls back to project
+- **`rrr-project-researcher`** - Dual-mode: project vs milestone research
+- **`rrr-research-synthesizer`** - Supports both paths, adds "Suggested Project Updates" for milestone
+
+### Removed
+
+- Stale pushpa phase folders (29, 30)
+- Misplaced v1.18-context-aware research (moved to proper milestone folder)
+
 ## [1.18.4] - 2026-02-01
 
 ### Changed

package/agents/rrr-project-researcher.md

@@ -1,40 +1,105 @@
 ---
 name: rrr-project-researcher
-description: Researches domain ecosystem before roadmap creation. Produces multiple files in .planning/research/ consumed by /rrr:create-roadmap. Spawned by /rrr:research-project orchestrator.
+description: Researches domain ecosystem. Supports two modes - project research (.planning/research/) and milestone research (.planning/milestones/vX.Y/research/). Milestone research inherits from project research.
 tools: Read, Write, Bash, Grep, Glob, WebSearch, WebFetch, mcp__context7__*
 color: cyan
 ---
 
 <role>
-You are a RRR project researcher. You research the domain ecosystem before roadmap creation, producing comprehensive findings that inform phase structure.
+You are a RRR researcher. You research domain ecosystems and produce findings that inform roadmap and requirements.
 
-You are spawned by:
+**Two Research Modes:**
+
+| Mode | When | Output Path | Inherits From |
+|------|------|-------------|---------------|
+| Project Research | New project setup | `.planning/research/` | Nothing (foundational) |
+| Milestone Research | New milestone setup | `.planning/milestones/vX.Y/research/` | Project research |
 
-- `/rrr:research-project` orchestrator (project-wide research before roadmap)
+You are spawned by:
 
-Your job: Answer "What does this domain ecosystem look like?" Produce multiple research files that inform roadmap creation.
+- `/rrr:new-project` Phase 6 (project research)
+- `/rrr:research-project` orchestrator (project research refresh)
+- `/rrr:new-milestone` step 8 (milestone research)
 
 **Core responsibilities:**
-- Survey the domain ecosystem broadly
+- Survey the domain ecosystem (project mode) OR specific features (milestone mode)
 - Identify technology landscape and options
 - Map feature categories (table stakes, differentiators)
 - Document architecture patterns and anti-patterns
 - Catalog domain-specific pitfalls
-- Write multiple files in `.planning/research/`
+- Write files to the specified output path
+- For milestone mode: read and build upon project research
+- Flag any updates needed for project-level docs (ROADMAP.md, REQUIREMENTS.md)
 - Return structured result to orchestrator
 </role>
 
+<research_modes>
+
+## Project Research Mode (Foundational)
+
+**Trigger:** Prompt includes `.planning/research/` as output path or mentions "project research"
+
+**Focus:** Broad domain ecosystem survey
+- What's the landscape for this type of product?
+- What's the standard stack?
+- What are table stakes features?
+- What are common pitfalls?
+
+**Outputs to:** `.planning/research/`
+
+**Does NOT inherit:** This is foundational research.
+
+## Milestone Research Mode (Incremental)
+
+**Trigger:** Prompt includes `.planning/milestones/vX.Y/research/` as output path or mentions "milestone research"
+
+**Focus:** Tactical research for specific new features
+- What's needed to add [feature X] to existing architecture?
+- What are gotchas for [new capability]?
+- How do these features typically integrate?
+
+**Outputs to:** `.planning/milestones/vX.Y/research/`
+
+**MUST inherit:** Read `.planning/research/` first for context. Don't re-research what's already established.
+
+**Can flag updates to:**
+- REQUIREMENTS.md (new requirements discovered)
+- ROADMAP.md (suggested phases, future milestone candidates)
+
+</research_modes>
+
 <downstream_consumer>
-Your research files are consumed by `/rrr:create-roadmap` which uses them to:
+Your research files are consumed by `/rrr:create-roadmap` (project) or `/rrr:define-requirements` (milestone):
 
-| File | How Roadmap Uses It |
-|------|---------------------|
+| File | How It's Used |
+|------|---------------|
 | `SUMMARY.md` | Phase structure recommendations, ordering rationale |
-| `STACK.md` | Technology decisions for the project |
-| `FEATURES.md` | What to build in each phase |
+| `STACK.md` | Technology decisions (new libs for milestone mode) |
+| `FEATURES.md` | What to build, table stakes vs differentiators |
 | `ARCHITECTURE.md` | System structure, component boundaries |
 | `PITFALLS.md` | What phases need deeper research flags |
 
+**For Milestone Research — Project Updates Section:**
+
+Include a section at the end of SUMMARY.md:
+
+```markdown
+## Suggested Project Updates
+
+### REQUIREMENTS.md Updates
+- Add to v[X.Y+1] Candidates: [requirement] — [rationale]
+- Add to Future Backlog: [requirement] — [rationale]
+
+### ROADMAP.md Updates
+- Suggest future milestone: [name] — [rationale]
+- Note for current milestone phases: [observation]
+
+### Out of Scope Reconsiderations
+- Revisit [feature]: [reason circumstances changed]
+```
+
+This allows milestone research to flow updates back to project-level docs.
+
 **Be comprehensive but opinionated.** Survey options, then recommend. "Use X because Y" not just "Options are X, Y, Z."
 </downstream_consumer>
 
@@ -340,7 +405,10 @@ Before submitting research:
 
 ## Output Location
 
-All files written to: `.planning/research/`
+**Project Research:** `.planning/research/`
+**Milestone Research:** `.planning/milestones/vX.Y/research/` (path provided in prompt)
+
+The orchestrator specifies the exact output path. Write to the path given in `<output>` section of your prompt.
 
 ## SUMMARY.md
 
@@ -690,12 +758,37 @@ What's needed to achieve this:
 
 Orchestrator provides:
 - Project name and description
+- Research type: PROJECT or MILESTONE
 - Research mode (ecosystem/feasibility/comparison)
 - Project context (from PROJECT.md if exists)
+- Output path (where to write files)
 - Specific questions to answer
 
+**For Milestone Research, also provided:**
+- Milestone version (e.g., v1.1)
+- Target features for this milestone
+- Instruction to read project research for context
+
 Parse and confirm understanding before proceeding.
 
+## Step 1.5: Load Project Research Context (Milestone Mode Only)
+
+**If this is milestone research:**
+
+Read existing project research for context:
+```
+Read .planning/research/SUMMARY.md
+Read .planning/research/STACK.md (for established tech decisions)
+Read .planning/research/ARCHITECTURE.md (for existing structure)
+```
+
+This gives you the foundation. Your milestone research BUILDS ON this, doesn't replace it.
+
+**Key questions for milestone mode:**
+- What's already established that I shouldn't re-research?
+- What new capabilities does this milestone add?
+- How do new features integrate with existing architecture?
+
 ## Step 2: Identify Research Domains
 
 Based on project description, identify what needs investigating:
@@ -840,18 +933,26 @@ When research cannot proceed:
 
 Research is complete when:
 
-- [ ] Domain ecosystem surveyed
+**Both Modes:**
+- [ ] Domain ecosystem surveyed (broad for project, focused for milestone)
 - [ ] Technology stack recommended with rationale
 - [ ] Feature landscape mapped (table stakes, differentiators, anti-features)
 - [ ] Architecture patterns documented
 - [ ] Domain pitfalls catalogued
 - [ ] Source hierarchy followed (Context7 → Official → WebSearch)
 - [ ] All findings have confidence levels
-- [ ] Output files created in `.planning/research/`
+- [ ] Output files created in specified path
 - [ ] SUMMARY.md includes roadmap implications
 - [ ] Files written (DO NOT commit — orchestrator handles this)
 - [ ] Structured return provided to orchestrator
 
+**Milestone Research Additional:**
+- [ ] Project research read for context (inheritance)
+- [ ] Research focuses on NEW capabilities, doesn't re-research established patterns
+- [ ] "Suggested Project Updates" section included in SUMMARY.md
+- [ ] New requirements flagged for REQUIREMENTS.md
+- [ ] Future milestone candidates identified (if any)
+
 Research quality indicators:
 
 - **Comprehensive, not shallow:** All major categories covered
@@ -860,5 +961,6 @@ Research quality indicators:
 - **Honest about gaps:** LOW confidence items flagged, unknowns admitted
 - **Actionable:** Roadmap creator could structure phases based on this research
 - **Current:** Year included in searches, publication dates checked
+- **Incremental (milestone):** Builds on project research, doesn't duplicate
 
 </success_criteria>

package/agents/rrr-research-synthesizer.md

@@ -1,6 +1,6 @@
 ---
 name: rrr-research-synthesizer
-description: Synthesizes research outputs from parallel researcher agents into SUMMARY.md. Spawned by /rrr:new-project after 4 researcher agents complete.
+description: Synthesizes research outputs from parallel researcher agents into SUMMARY.md. Supports both project research (.planning/research/) and milestone research (.planning/milestones/vX.Y/research/).
 tools: Read, Write, Bash
 color: purple
 ---
@@ -8,18 +8,28 @@ color: purple
 <role>
 You are a RRR research synthesizer. You read the outputs from 4 parallel researcher agents and synthesize them into a cohesive SUMMARY.md.
 
+**Two Research Modes:**
+
+| Mode | Research Path | Also Reads |
+|------|---------------|------------|
+| Project | `.planning/research/` | Nothing (foundational) |
+| Milestone | `.planning/milestones/vX.Y/research/` | `.planning/research/SUMMARY.md` (project context) |
+
 You are spawned by:
 
-- `/rrr:new-project` orchestrator (after STACK, FEATURES, ARCHITECTURE, PITFALLS research completes)
+- `/rrr:new-project` Phase 6 (project research synthesis)
+- `/rrr:new-milestone` step 8 (milestone research synthesis)
 
 Your job: Create a unified research summary that informs roadmap creation. Extract key findings, identify patterns across research files, and produce roadmap implications.
 
 **Core responsibilities:**
 - Read all 4 research files (STACK.md, FEATURES.md, ARCHITECTURE.md, PITFALLS.md)
+- For milestone mode: also read project research SUMMARY.md for context
 - Synthesize findings into executive summary
 - Derive roadmap implications from combined research
 - Identify confidence levels and gaps
-- Write SUMMARY.md
+- For milestone mode: include "Suggested Project Updates" section
+- Write SUMMARY.md to the specified path
 - Commit ALL research files (researchers write but don't commit — you commit everything)
 </role>
 
@@ -39,15 +49,34 @@ Your SUMMARY.md is consumed by the rrr-roadmapper agent which uses it to:
 
 <execution_flow>
 
-## Step 1: Read Research Files
+## Step 1: Determine Research Directory
+
+Parse your prompt for the output path:
+- **Project mode:** `.planning/research/` (default)
+- **Milestone mode:** `.planning/milestones/vX.Y/research/` (specified in prompt)
+
+Set `RESEARCH_DIR` accordingly.
+
+## Step 1.5: Read Project Research Context (Milestone Mode Only)
+
+**If this is milestone research:**
 
-Read all 4 research files:
+Read project research for context:
+```bash
+cat .planning/research/SUMMARY.md
+```
+
+This gives you the foundation the milestone research builds upon.
+
+## Step 2: Read Research Files
+
+Read all 4 research files from `RESEARCH_DIR`:
 
 ```bash
-cat .planning/research/STACK.md
-cat .planning/research/FEATURES.md
-cat .planning/research/ARCHITECTURE.md
-cat .planning/research/PITFALLS.md
+cat ${RESEARCH_DIR}/STACK.md
+cat ${RESEARCH_DIR}/FEATURES.md
+cat ${RESEARCH_DIR}/ARCHITECTURE.md
+cat ${RESEARCH_DIR}/PITFALLS.md
 ```
 
 Parse each file to extract:
@@ -119,15 +148,45 @@ Identify gaps that couldn't be resolved and need attention during planning.
 
 Use template: ~/.claude/rrr/templates/research-project/SUMMARY.md
 
-Write to `.planning/research/SUMMARY.md`
+Write to `${RESEARCH_DIR}/SUMMARY.md`
+
+**For Milestone Mode — Add "Suggested Project Updates" Section:**
+
+```markdown
+## Suggested Project Updates
+
+Based on milestone research, the following updates to project-level docs are recommended:
+
+### REQUIREMENTS.md Updates
+
+| Requirement | Target Section | Rationale |
+|-------------|---------------|-----------|
+| [new requirement] | v[X.Y+1] Candidates | [why discovered/needed] |
+| [new requirement] | Future Backlog | [why discovered/needed] |
+
+### ROADMAP.md Updates
+
+| Update | Type | Rationale |
+|--------|------|-----------|
+| [suggestion] | Future milestone candidate | [why] |
+| [suggestion] | Current milestone note | [observation] |
+
+### Out of Scope Reconsiderations
+
+| Feature | Action | Rationale |
+|---------|--------|-----------|
+| [feature] | Consider for [version] | [circumstances changed] |
+```
+
+This section allows milestone research to flow updates back to project-level docs.
 
 ## Step 7: Commit All Research
 
 The 4 parallel researcher agents write files but do NOT commit. You commit everything together.
 
 ```bash
-git add .planning/research/
-git commit -m "docs: complete project research
+git add "${RESEARCH_DIR}/"
+git commit -m "docs: complete [project/milestone] research
 
 Files:
 - STACK.md

package/commands/rrr/create-roadmap.md

@@ -46,7 +46,11 @@ Roadmaps define what work happens in what order. Phases map to requirements.
 @.planning/PROJECT.md
 @.planning/config.json
 @.planning/REQUIREMENTS.md
-@.planning/research/SUMMARY.md (if exists)
+@.planning/STATE.md (to detect active milestone)
+
+**Research context (checked in order):**
+1. `.planning/milestones/vX.Y/research/SUMMARY.md` (milestone-specific)
+2. `.planning/research/SUMMARY.md` (project-level fallback)
 </context>
 
 <process>

package/commands/rrr/define-requirements.md

@@ -43,8 +43,11 @@ Output: `.planning/REQUIREMENTS.md`
 
 <context>
 @.planning/PROJECT.md
-@.planning/research/FEATURES.md (if exists)
-@.planning/research/SUMMARY.md (if exists)
+@.planning/STATE.md (to detect active milestone)
+
+**Research context (priority order):**
+1. `.planning/milestones/vX.Y/research/` (milestone-specific)
+2. `.planning/research/` (project-level fallback)
 </context>
 
 <process>
@@ -54,11 +57,29 @@ Output: `.planning/REQUIREMENTS.md`
 # Verify project exists
 [ -f .planning/PROJECT.md ] || { echo "ERROR: No PROJECT.md found. Run /rrr:new-project first."; exit 1; }
 
-# Check for research
-[ -f .planning/research/FEATURES.md ] && echo "HAS_RESEARCH" || echo "NO_RESEARCH"
+# Detect active milestone from STATE.md
+ACTIVE_MILESTONE=""
+if [ -f .planning/STATE.md ]; then
+  ACTIVE_MILESTONE=$(grep -oE "Milestone:\\s*v[0-9]+\\.[0-9]+" .planning/STATE.md | grep -oE "v[0-9]+\\.[0-9]+")
+fi
+
+# Check for research (milestone-specific first, then project-level)
+RESEARCH_DIR=""
+if [ -n "$ACTIVE_MILESTONE" ] && [ -f ".planning/milestones/${ACTIVE_MILESTONE}/research/FEATURES.md" ]; then
+  RESEARCH_DIR=".planning/milestones/${ACTIVE_MILESTONE}/research"
+  echo "HAS_MILESTONE_RESEARCH: $ACTIVE_MILESTONE"
+elif [ -f .planning/research/FEATURES.md ]; then
+  RESEARCH_DIR=".planning/research"
+  echo "HAS_PROJECT_RESEARCH"
+else
+  echo "NO_RESEARCH"
+fi
 
 # Check if requirements already exist
 [ -f .planning/REQUIREMENTS.md ] && echo "REQUIREMENTS_EXISTS" || echo "NO_REQUIREMENTS"
+
+echo "ACTIVE_MILESTONE=${ACTIVE_MILESTONE}"
+echo "RESEARCH_DIR=${RESEARCH_DIR}"
 ```
 </step>
 
@@ -79,13 +100,19 @@ If "Replace": Continue with workflow
 </step>
 
 <step name="execute">
-**If HAS_RESEARCH:**
+**If HAS_MILESTONE_RESEARCH or HAS_PROJECT_RESEARCH:**
 Follow the define-requirements.md workflow:
-- Load research features from FEATURES.md
+- Load research features from `${RESEARCH_DIR}/FEATURES.md`
+- Also read `${RESEARCH_DIR}/SUMMARY.md` for "Suggested Project Updates" (if milestone research)
 - Present features by category
-- Ask user to scope each category (v1 / v2 / out of scope)
+- Ask user to scope each category (current milestone / future milestone / out of scope)
 - Capture any additions research missed
-- Generate REQUIREMENTS.md with checkable list
+- Generate/update REQUIREMENTS.md with milestone-specific section
+
+**For milestone research mode:**
+- Requirements go into the ACTIVE milestone section (e.g., "## v1.1 — [Name] (Active)")
+- Check "Suggested Project Updates" from research for pre-populated candidates
+- Future milestone candidates go to "Future Milestones" section
 
 **If NO_RESEARCH:**
 Gather requirements through questioning:
@@ -93,8 +120,8 @@ Gather requirements through questioning:
 - Ask: "What are the main things users need to be able to do?"
 - For each capability mentioned, probe for specifics
 - Group into categories (Authentication, Content, etc.)
-- For each category, ask what's v1 vs v2 vs out of scope
-- Generate REQUIREMENTS.md with checkable list
+- For each category, ask what's current milestone vs future vs out of scope
+- Generate/update REQUIREMENTS.md with milestone-specific section
 
 Same output format either way — the difference is source (research vs conversation).
 </step>

package/commands/rrr/new-milestone.md

@@ -251,26 +251,127 @@ node ~/.claude/rrr/scripts/rrr-hud.js 2>/dev/null || echo "HUD skipped"
    git commit -m "docs: start milestone v[X.Y] [Name]"
    ```
 
-8. **Route to next step:**
+8. **Milestone research decision:**
 
+   Use AskUserQuestion:
+   - header: "Research"
+   - question: "Research the domain for this milestone's features?"
+   - options:
+     - "Yes, research first (Recommended)" — Discover patterns for new capabilities
+     - "No, define requirements directly" — Familiar territory, skip research
+
+   **If "Yes, research first":**
+
+   Create milestone research directory:
+   ```bash
+   NEW_VERSION="[milestone version from step 3]"
+   mkdir -p ".planning/milestones/v${NEW_VERSION}/research"
    ```
-   Milestone v[X.Y] [Name] initialized.
 
-   PROJECT.md updated with new goals.
+   Display:
+   ```
+   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    MILESTONE RESEARCH
+   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-   ---
+   Researching [milestone features] for v[X.Y]...
+   Reading project research for context...
+   ```
 
-   ## ▶ Next Up
+   **Spawn 4 parallel milestone researchers:**
 
-   Choose your path:
+   Each researcher gets:
+   - Milestone context (target features from step 2)
+   - Project research context (read `.planning/research/` if exists)
+   - Output path: `.planning/milestones/v${NEW_VERSION}/research/`
 
-   **Option A: Research first** (new domains/capabilities)
-   Research ecosystem before scoping. Discovers patterns, expected features, architecture approaches.
+   ```
+   Task(prompt="
+   <research_type>
+   Milestone Research — Stack dimension for v[X.Y] [milestone name].
+   </research_type>
+
+   <milestone_context>
+   This is SUBSEQUENT milestone research (not greenfield).
+   Target features: [features from step 2]
+   Don't re-research existing system. Focus on what's NEW.
+   </milestone_context>
+
+   <project_research>
+   Read and incorporate context from: .planning/research/ (if exists)
+   Your milestone research BUILDS ON project research, doesn't replace it.
+   </project_research>
+
+   <question>
+   What stack additions/changes are needed for [milestone features]?
+   </question>
+
+   <downstream_consumer>
+   Your STACK.md feeds into milestone roadmap phases.
+   Focus on: new libraries needed, version updates, integration patterns.
+   </downstream_consumer>
+
+   <can_update_project>
+   If you discover something that should update project-level docs:
+   - Flag it in your output
+   - Include specific update suggestions for ROADMAP.md or REQUIREMENTS.md
+   </can_update_project>
+
+   <output>
+   Write to: .planning/milestones/v${NEW_VERSION}/research/STACK.md
+   </output>
+   ", subagent_type="rrr-project-researcher", description="Milestone stack research")
+
+   [Similar prompts for FEATURES.md, ARCHITECTURE.md, PITFALLS.md]
+   ```
 
-   `/rrr:research-project`
+   After all 4 complete, spawn synthesizer:
+   ```
+   Task(prompt="
+   Synthesize milestone research into SUMMARY.md.
+
+   Read these files:
+   - .planning/milestones/v${NEW_VERSION}/research/STACK.md
+   - .planning/milestones/v${NEW_VERSION}/research/FEATURES.md
+   - .planning/milestones/v${NEW_VERSION}/research/ARCHITECTURE.md
+   - .planning/milestones/v${NEW_VERSION}/research/PITFALLS.md
+
+   Also read project research for context:
+   - .planning/research/SUMMARY.md (if exists)
+
+   Write to: .planning/milestones/v${NEW_VERSION}/research/SUMMARY.md
+
+   Include:
+   - How milestone builds on existing architecture
+   - New requirements discovered (for REQUIREMENTS.md update)
+   - Suggested phases for this milestone
+   - Any project-level updates recommended
+   ", subagent_type="rrr-research-synthesizer", description="Synthesize milestone research")
+   ```
+
+   Commit research:
+   ```bash
+   git add ".planning/milestones/v${NEW_VERSION}/research/"
+   git commit -m "docs: research milestone v${NEW_VERSION} features"
+   ```
+
+   **If "No, define requirements directly":** Skip research, continue to step 9.
+
+9. **Route to next step:**
+
+   ```
+   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    MILESTONE v[X.Y] INITIALIZED ✓
+   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+   PROJECT.md updated with new goals.
+   [If research done: Research complete in .planning/milestones/v[X.Y]/research/]
+
+   ---
+
+   ## ▶ Next Up
 
-   **Option B: Define requirements directly** (familiar territory)
-   Skip research, define requirements from what you know.
+   **Define requirements for v[X.Y]**
 
    `/rrr:define-requirements`
 
@@ -287,6 +388,8 @@ node ~/.claude/rrr/scripts/rrr-hud.js 2>/dev/null || echo "HUD skipped"
 - Active requirements reflect new milestone goals
 - STATE.md reset for new milestone
 - MILESTONE-CONTEXT.md consumed and deleted (if existed)
+- Milestone research offered (if selected: .planning/milestones/vX.Y/research/ created)
+- Milestone research reads project research for context (inheritance)
 - Git commit made
-- User routed to define-requirements (or research-project)
+- User routed to define-requirements
 </success_criteria>

package/commands/rrr/plan-phase.md

@@ -39,22 +39,40 @@ Phase number: $ARGUMENTS (optional - auto-detects next unplanned phase if not pr
 - `--gaps` — Gap closure mode (reads VERIFICATION.md, skips research)
 - `--skip-verify` — Skip planner → checker verification loop
 
-**Research defaults:** If `.planning/research/SUMMARY.md` exists (from `/rrr:new-project`), research is skipped by default unless:
+**Research defaults:** If research SUMMARY.md exists (milestone or project level), research is skipped by default unless:
 - `--research` flag is set, OR
 - Phase involves risky domains (auth, payments, security, webhooks), OR
 - `.planning/codebase/` is missing for brownfield projects
 
+**Research location (checked in order):**
+1. `.planning/milestones/vX.Y/research/SUMMARY.md` (milestone-specific)
+2. `.planning/research/SUMMARY.md` (project-level fallback)
+
 Check for existing research and plans:
 
 **On macOS/Linux:**
 ```bash
+# Detect active milestone
+ACTIVE_MILESTONE=$(grep -oE "Milestone:\\s*v[0-9]+\\.[0-9]+" .planning/STATE.md 2>/dev/null | grep -oE "v[0-9]+\\.[0-9]+")
+
+# Check for research (milestone-specific first, then project-level)
+RESEARCH_DIR=""
+if [ -n "$ACTIVE_MILESTONE" ] && [ -f ".planning/milestones/${ACTIVE_MILESTONE}/research/SUMMARY.md" ]; then
+  RESEARCH_DIR=".planning/milestones/${ACTIVE_MILESTONE}/research"
+  echo "HAS_MILESTONE_RESEARCH: $ACTIVE_MILESTONE"
+elif [ -f .planning/research/SUMMARY.md ]; then
+  RESEARCH_DIR=".planning/research"
+  echo "HAS_PROJECT_RESEARCH"
+else
+  echo "NO_RESEARCH"
+fi
+
 # Use library to find phase directory first (searches both old and new structures)
 PHASE_DIR=$(find_phase_dir "$PHASE")
 if [ -n "$PHASE_DIR" ]; then
   ls "${PHASE_DIR}"/*-RESEARCH.md 2>/dev/null
   ls "${PHASE_DIR}"/*-PLAN.md 2>/dev/null
 fi
-ls .planning/research/SUMMARY.md 2>/dev/null
 ```
 
 **On Windows (Platform: win32):**
@@ -65,7 +83,9 @@ Use Glob tool with both structures:
 - Then search within found directory:
   - `Glob pattern: "{PHASE_DIR}/*-RESEARCH.md"`
   - `Glob pattern: "{PHASE_DIR}/*-PLAN.md"`
-- `Glob pattern: ".planning/research/SUMMARY.md"`
+- Check research (milestone first, then project):
+  - `Glob pattern: ".planning/milestones/v*/research/SUMMARY.md"`
+  - `Glob pattern: ".planning/research/SUMMARY.md"`
 
 </context>
 
@@ -490,16 +510,19 @@ fi
 
 **Smart research guardrails (default behavior):**
 
-Check for project-level research:
+Check for research (milestone-specific first, then project-level):
 
 **On macOS/Linux:**
 ```bash
-ls .planning/research/SUMMARY.md 2>/dev/null
+# Detect active milestone and find research (already set in context step)
+# RESEARCH_DIR is set to milestone research or project research path
+ls "${RESEARCH_DIR}/SUMMARY.md" 2>/dev/null
 ls "${PHASE_DIR}"/*-RESEARCH.md 2>/dev/null
 ```
 
 **On Windows:**
-- `Glob pattern: ".planning/research/SUMMARY.md"`
+- `Glob pattern: ".planning/milestones/v*/research/SUMMARY.md"` (milestone first)
+- `Glob pattern: ".planning/research/SUMMARY.md"` (project fallback)
 - `Glob pattern: "${PHASE_DIR}/*-RESEARCH.md"`
 
 **Research Decision Matrix:**
@@ -508,8 +531,9 @@ ls "${PHASE_DIR}"/*-RESEARCH.md 2>/dev/null
 |-----------|--------|
 | `--research` flag set | Force research (override all) |
 | Phase-level RESEARCH.md exists | Use existing, skip to step 6 |
+| Milestone-level SUMMARY.md exists AND phase is NOT risky | Skip research, display: `Using milestone research from /rrr:new-milestone` |
 | Project-level SUMMARY.md exists AND phase is NOT risky | Skip research, display: `Using project research from /rrr:new-project` |
-| Project-level SUMMARY.md exists AND phase IS risky | Run research (risky domains need phase-specific research) |
+| Research SUMMARY.md exists AND phase IS risky | Run research (risky domains need phase-specific research) |
 | Neither research exists | Run research |
 
 **Risky domain detection:** Phase name or description contains: `auth`, `payment`, `security`, `webhook`, `oauth`, `stripe`, `bank`, `credential`, `encryption`, `api-key`.

package/commands/rrr/research-project.md

@@ -40,14 +40,36 @@ Research domain ecosystem. Spawns 4 parallel rrr-project-researcher agents for c
 
 <process>
 
-## 1. Validate Prerequisites
+## 1. Validate Prerequisites & Detect Milestone
 
 ```bash
 [ -f .planning/PROJECT.md ] || { echo "ERROR: No PROJECT.md. Run /rrr:new-project first."; exit 1; }
-[ -f .planning/ROADMAP.md ] && echo "WARNING: ROADMAP.md exists. Research is typically done before roadmap."
-[ -d .planning/research ] && echo "RESEARCH_EXISTS" || echo "NO_RESEARCH"
+
+# Detect active milestone from ROADMAP.md
+ACTIVE_MILESTONE=""
+if [ -f .planning/ROADMAP.md ]; then
+  # Try "Current Milestone: vX.Y" format
+  ACTIVE_MILESTONE=$(grep -oE "Current Milestone:\s*v[0-9]+\.[0-9]+" .planning/ROADMAP.md | grep -oE "v[0-9]+\.[0-9]+")
+  # Try "**Milestone:** vX.Y" format
+  [ -z "$ACTIVE_MILESTONE" ] && ACTIVE_MILESTONE=$(grep -oE "\*\*Milestone:\*\*\s*v[0-9]+\.[0-9]+" .planning/ROADMAP.md | grep -oE "v[0-9]+\.[0-9]+")
+fi
+
+# Set research directory based on milestone
+if [ -n "$ACTIVE_MILESTONE" ]; then
+  RESEARCH_DIR=".planning/milestones/${ACTIVE_MILESTONE}/research"
+  echo "MILESTONE_RESEARCH: ${ACTIVE_MILESTONE}"
+else
+  RESEARCH_DIR=".planning/research"
+  echo "PROJECT_RESEARCH: initial setup (no milestone yet)"
+fi
+
+[ -d "$RESEARCH_DIR" ] && echo "RESEARCH_EXISTS" || echo "NO_RESEARCH"
 ```
 
+**Research location logic:**
+- If active milestone exists → `.planning/milestones/vX.Y/research/`
+- If no milestone (initial project) → `.planning/research/`
+
 ## 2. Handle Existing Research
 
 **If RESEARCH_EXISTS:** Use AskUserQuestion (View existing / Replace / Cancel)
@@ -77,7 +99,7 @@ Present for approval.
 ## 5. Spawn Research Agents
 
 ```bash
-mkdir -p .planning/research
+mkdir -p "${RESEARCH_DIR}"
 ```
 
 **Determine milestone context:**
@@ -121,7 +143,7 @@ Your STACK.md feeds into /rrr:create-roadmap. Be prescriptive:
 </quality_gate>
 
 <output>
-Write to: .planning/research/STACK.md
+Write to: ${RESEARCH_DIR}/STACK.md
 Use template: ~/.claude/rrr/templates/research-project/STACK.md
 </output>
 ", subagent_type="rrr-project-researcher", description="Stack research")
@@ -160,7 +182,7 @@ Your FEATURES.md feeds into /rrr:define-requirements. Categorize clearly:
 </quality_gate>
 
 <output>
-Write to: .planning/research/FEATURES.md
+Write to: ${RESEARCH_DIR}/FEATURES.md
 Use template: ~/.claude/rrr/templates/research-project/FEATURES.md
 </output>
 ", subagent_type="rrr-project-researcher", description="Features research")
@@ -199,7 +221,7 @@ Your ARCHITECTURE.md informs phase structure in roadmap. Include:
 </quality_gate>
 
 <output>
-Write to: .planning/research/ARCHITECTURE.md
+Write to: ${RESEARCH_DIR}/ARCHITECTURE.md
 Use template: ~/.claude/rrr/templates/research-project/ARCHITECTURE.md
 </output>
 ", subagent_type="rrr-project-researcher", description="Architecture research")
@@ -238,7 +260,7 @@ Your PITFALLS.md prevents mistakes in roadmap/planning. For each pitfall:
 </quality_gate>
 
 <output>
-Write to: .planning/research/PITFALLS.md
+Write to: ${RESEARCH_DIR}/PITFALLS.md
 Use template: ~/.claude/rrr/templates/research-project/PITFALLS.md
 </output>
 ", subagent_type="rrr-project-researcher", description="Pitfalls research")
@@ -248,7 +270,7 @@ Use template: ~/.claude/rrr/templates/research-project/PITFALLS.md
 
 ## 6. Synthesize Results
 
-After all agents complete, read their outputs and write `.planning/research/SUMMARY.md`:
+After all agents complete, read their outputs and write `${RESEARCH_DIR}/SUMMARY.md`:
 - Read template: `~/.claude/rrr/templates/research-project/SUMMARY.md`
 - Synthesize executive summary from all 4 files
 - Add confidence assessment
@@ -283,7 +305,7 @@ This section directly feeds into `/rrr:create-roadmap`.
 ## 7. Commit Research
 
 ```bash
-git add .planning/research/
+git add "${RESEARCH_DIR}/"
 git commit -m "docs: research [domain] ecosystem
 
 Key findings:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "projecta-rrr",
-  "version": "1.18.4",
+  "version": "1.18.6",
   "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/templates/requirements.md

@@ -2,6 +2,16 @@
 
 Template for `.planning/REQUIREMENTS.md` — checkable requirements that define "done."
 
+## Philosophy
+
+Requirements evolve with the project:
+- **Validated** = shipped and verified (immutable history)
+- **Active (current milestone)** = being built now
+- **Future milestones** = planned but not yet active
+- **Out of Scope** = explicit exclusions
+
+Milestone research can ADD requirements. Each milestone has its own section.
+
 <template>
 
 ```markdown
@@ -9,34 +19,48 @@ Template for `.planning/REQUIREMENTS.md` — checkable requirements that define
 
 **Defined:** [date]
 **Core Value:** [from PROJECT.md]
+**Current Milestone:** v[X.Y]
 
-## v1 Requirements
+## Validated
 
-Requirements for initial release. Each maps to roadmap phases.
+Requirements shipped and verified. These are immutable — they represent what works.
 
-### Authentication
+### v1.0 — [Milestone Name]
 
-- [ ] **AUTH-01**: User can sign up with email and password
-- [ ] **AUTH-02**: User receives email verification after signup
-- [ ] **AUTH-03**: User can reset password via email link
-- [ ] **AUTH-04**: User session persists across browser refresh
+- [x] **AUTH-01**: User can sign up with email and password — *verified [date]*
+- [x] **AUTH-02**: User receives email verification after signup — *verified [date]*
+- [x] **CONT-01**: User can create text post — *verified [date]*
 
-### [Category 2]
+### v1.1 — [Milestone Name] (if applicable)
+
+- [x] **NOTF-01**: User receives in-app notifications — *verified [date]*
+
+## v[X.Y] — [Current Milestone Name] (Active)
+
+Requirements for current milestone. Mapped to roadmap phases.
+
+### [Category 1]
 
 - [ ] **[CAT]-01**: [Requirement description]
 - [ ] **[CAT]-02**: [Requirement description]
-- [ ] **[CAT]-03**: [Requirement description]
 
-### [Category 3]
+### [Category 2]
 
 - [ ] **[CAT]-01**: [Requirement description]
 - [ ] **[CAT]-02**: [Requirement description]
 
-## v2 Requirements
+## Future Milestones
+
+Requirements planned for future milestones. Not in current roadmap.
 
-Deferred to future release. Tracked but not in current roadmap.
+### v[X.Y+1] Candidates
 
-### [Category]
+*Flagged by research or deferred from current milestone*
+
+- **[CAT]-01**: [Requirement description] — *Source: [milestone research / user request]*
+- **[CAT]-02**: [Requirement description] — *Source: [milestone research / user request]*
+
+### Backlog (Unassigned)
 
 - **[CAT]-01**: [Requirement description]
 - **[CAT]-02**: [Requirement description]
@@ -45,25 +69,22 @@ Deferred to future release. Tracked but not in current roadmap.
 
 Explicitly excluded. Documented to prevent scope creep.
 
-| Feature | Reason |
-|---------|--------|
-| [Feature] | [Why excluded] |
-| [Feature] | [Why excluded] |
+| Feature | Reason | Revisit? |
+|---------|--------|----------|
+| [Feature] | [Why excluded] | [v2/Never] |
+| [Feature] | [Why excluded] | [v2/Never] |
 
 ## Traceability
 
-Which phases cover which requirements. Updated by create-roadmap.
+Which phases cover which requirements for the CURRENT milestone.
 
 | Requirement | Phase | Status |
 |-------------|-------|--------|
-| AUTH-01 | Phase 1 | Pending |
-| AUTH-02 | Phase 1 | Pending |
-| AUTH-03 | Phase 1 | Pending |
-| AUTH-04 | Phase 1 | Pending |
+| [REQ-ID] | Phase [N] | Pending |
 | [REQ-ID] | Phase [N] | Pending |
 
-**Coverage:**
-- v1 requirements: [X] total
+**Coverage (v[X.Y]):**
+- Active requirements: [X] total
 - Mapped to phases: [Y]
 - Unmapped: [Z] ⚠️
 
@@ -76,27 +97,43 @@ Which phases cover which requirements. Updated by create-roadmap.
 
 <guidelines>
 
+**Milestone-Based Structure:**
+
+The hierarchy is: Project → Milestone → Phases → Plans
+
+- **Validated** = Shipped requirements from past milestones (immutable)
+- **Active** = Current milestone's requirements (has checkboxes, maps to phases)
+- **Future** = Candidates for future milestones (no checkboxes yet)
+- **Out of Scope** = Explicit exclusions
+
 **Requirement Format:**
 - ID: `[CATEGORY]-[NUMBER]` (AUTH-01, CONTENT-02, SOCIAL-03)
 - Description: User-centric, testable, atomic
-- Checkbox: Only for v1 requirements (v2 are not yet actionable)
+- Checkbox: Only for ACTIVE milestone requirements
 
 **Categories:**
 - Derive from research FEATURES.md categories
 - Keep consistent with domain conventions
 - Typical: Authentication, Content, Social, Notifications, Moderation, Payments, Admin
 
-**v1 vs v2:**
-- v1: Committed scope, will be in roadmap phases
-- v2: Acknowledged but deferred, not in current roadmap
-- Moving v2 → v1 requires roadmap update
+**Milestone Transitions:**
+
+When starting new milestone (via `/rrr:new-milestone`):
+1. Move completed requirements from Active → Validated
+2. Create new Active section for new milestone
+3. Milestone research can add to Future Candidates
+
+When milestone research discovers new requirements:
+1. Add to Future Candidates section with source attribution
+2. Can suggest for current milestone (if scope allows) or future
 
 **Out of Scope:**
 - Explicit exclusions with reasoning
-- Prevents "why didn't you include X?" later
+- "Revisit?" column indicates if this might change
 - Anti-features from research belong here with warnings
 
 **Traceability:**
+- Only tracks CURRENT milestone's requirements
 - Empty initially, populated by create-roadmap
 - Each requirement maps to exactly one phase
 - Unmapped requirements = roadmap gap (error in create-roadmap)
@@ -136,30 +173,29 @@ Which phases cover which requirements. Updated by create-roadmap.
 
 **Defined:** 2025-01-14
 **Core Value:** Users can share and discuss content with people who share their interests
+**Current Milestone:** v1.1
 
-## v1 Requirements
-
-### Authentication
-
-- [ ] **AUTH-01**: User can sign up with email and password
-- [ ] **AUTH-02**: User receives email verification after signup
-- [ ] **AUTH-03**: User can reset password via email link
-- [ ] **AUTH-04**: User session persists across browser refresh
+## Validated
 
-### Profiles
+### v1.0 — MVP Core
 
-- [ ] **PROF-01**: User can create profile with display name
-- [ ] **PROF-02**: User can upload avatar image
-- [ ] **PROF-03**: User can write bio (max 500 chars)
-- [ ] **PROF-04**: User can view other users' profiles
+- [x] **AUTH-01**: User can sign up with email and password — *verified 2025-02-01*
+- [x] **AUTH-02**: User receives email verification after signup — *verified 2025-02-01*
+- [x] **AUTH-03**: User can reset password via email link — *verified 2025-02-01*
+- [x] **AUTH-04**: User session persists across browser refresh — *verified 2025-02-01*
+- [x] **PROF-01**: User can create profile with display name — *verified 2025-02-05*
+- [x] **PROF-02**: User can upload avatar image — *verified 2025-02-05*
+- [x] **PROF-03**: User can write bio (max 500 chars) — *verified 2025-02-05*
+- [x] **PROF-04**: User can view other users' profiles — *verified 2025-02-05*
+- [x] **CONT-01**: User can create text post — *verified 2025-02-10*
+- [x] **CONT-02**: User can upload image with post — *verified 2025-02-10*
+- [x] **CONT-03**: User can edit own posts — *verified 2025-02-10*
+- [x] **CONT-04**: User can delete own posts — *verified 2025-02-10*
+- [x] **CONT-05**: User can view feed of posts — *verified 2025-02-10*
 
-### Content
+## v1.1 — Social & Engagement (Active)
 
-- [ ] **CONT-01**: User can create text post
-- [ ] **CONT-02**: User can upload image with post
-- [ ] **CONT-03**: User can edit own posts
-- [ ] **CONT-04**: User can delete own posts
-- [ ] **CONT-05**: User can view feed of posts
+Requirements for current milestone. Adding social features.
 
 ### Social
 
@@ -169,63 +205,65 @@ Which phases cover which requirements. Updated by create-roadmap.
 - [ ] **SOCL-04**: User can comment on posts
 - [ ] **SOCL-05**: User can view activity feed (followed users' posts)
 
-## v2 Requirements
+### Notifications (from v1.1 research)
+
+- [ ] **NOTF-01**: User receives in-app notifications for follows
+- [ ] **NOTF-02**: User receives in-app notifications for comments
+
+## Future Milestones
+
+### v1.2 Candidates
+
+*Flagged by v1.1 milestone research*
+
+- **NOTF-03**: User receives email for new followers — *Source: v1.1 research*
+- **NOTF-04**: User receives email for comments on own posts — *Source: v1.1 research*
+- **NOTF-05**: User can configure notification preferences — *Source: v1.1 research*
+
+### v2.0 Candidates
 
-### Notifications
+*Major features requiring significant work*
 
-- **NOTF-01**: User receives in-app notifications
-- **NOTF-02**: User receives email for new followers
-- **NOTF-03**: User receives email for comments on own posts
-- **NOTF-04**: User can configure notification preferences
+- **MODR-01**: User can report content — *Source: project research*
+- **MODR-02**: User can block other users — *Source: project research*
+- **MODR-03**: Admin can view reported content — *Source: project research*
+- **MODR-04**: Admin can remove content — *Source: project research*
+- **MODR-05**: Admin can ban users — *Source: project research*
 
-### Moderation
+### Backlog (Unassigned)
 
-- **MODR-01**: User can report content
-- **MODR-02**: User can block other users
-- **MODR-03**: Admin can view reported content
-- **MODR-04**: Admin can remove content
-- **MODR-05**: Admin can ban users
+- **REAL-01**: Real-time typing indicators
+- **REAL-02**: Push notifications
 
 ## Out of Scope
 
-| Feature | Reason |
-|---------|--------|
-| Real-time chat | High complexity, not core to community value |
-| Video posts | Storage/bandwidth costs, defer to v2+ |
-| OAuth login | Email/password sufficient for v1 |
-| Mobile app | Web-first, mobile later |
+| Feature | Reason | Revisit? |
+|---------|--------|----------|
+| Real-time chat | High complexity, not core to community value | v2.0 |
+| Video posts | Storage/bandwidth costs | v2.0 |
+| OAuth login | Email/password sufficient for now | v1.2 |
+| Mobile app | Web-first | v2.0 |
 
 ## Traceability
 
 | Requirement | Phase | Status |
 |-------------|-------|--------|
-| AUTH-01 | Phase 1 | Pending |
-| AUTH-02 | Phase 1 | Pending |
-| AUTH-03 | Phase 1 | Pending |
-| AUTH-04 | Phase 1 | Pending |
-| PROF-01 | Phase 2 | Pending |
-| PROF-02 | Phase 2 | Pending |
-| PROF-03 | Phase 2 | Pending |
-| PROF-04 | Phase 2 | Pending |
-| CONT-01 | Phase 3 | Pending |
-| CONT-02 | Phase 3 | Pending |
-| CONT-03 | Phase 3 | Pending |
-| CONT-04 | Phase 3 | Pending |
-| CONT-05 | Phase 3 | Pending |
-| SOCL-01 | Phase 4 | Pending |
-| SOCL-02 | Phase 4 | Pending |
-| SOCL-03 | Phase 4 | Pending |
-| SOCL-04 | Phase 4 | Pending |
-| SOCL-05 | Phase 4 | Pending |
-
-**Coverage:**
-- v1 requirements: 18 total
-- Mapped to phases: 18
+| SOCL-01 | Phase 14 | Pending |
+| SOCL-02 | Phase 14 | Pending |
+| SOCL-03 | Phase 14 | Pending |
+| SOCL-04 | Phase 15 | Pending |
+| SOCL-05 | Phase 15 | Pending |
+| NOTF-01 | Phase 16 | Pending |
+| NOTF-02 | Phase 16 | Pending |
+
+**Coverage (v1.1):**
+- Active requirements: 7 total
+- Mapped to phases: 7
 - Unmapped: 0 ✓
 
 ---
 *Requirements defined: 2025-01-14*
-*Last updated: 2025-01-14 after initial definition*
+*Last updated: 2025-02-15 after v1.1 milestone research*
 ```
 
 </example>