mother-brain 0.7.3 → 0.7.5

package/dist/cli.js

@@ -798,7 +798,7 @@ async function uninstall(options) {
 // src/cli.ts
 import { exec as exec3 } from "child_process";
 var program = new Command();
-var VERSION = "0.7.3";
+var VERSION = "0.7.5";
 program.name("mother-brain").description("AI-powered project management framework for GitHub Copilot CLI and Codex CLI").version(VERSION);
 program.command("init").description("Initialize Mother Brain in the current project").option("-f, --force", "Overwrite existing skills").action(init);
 program.command("update").description("Update Mother Brain skills to the latest version").action(update);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mother-brain",
-  "version": "0.7.3",
+  "version": "0.7.5",
   "description": "AI-powered project management framework for GitHub Copilot CLI",
   "type": "module",
   "main": "dist/index.js",

package/skills/mother-brain/SKILL.md

@@ -137,6 +137,7 @@ allowed-tools: powershell view grep glob web_search ask_user create edit skill
 - Template files to load on demand:
   - **Boot/Startup**: Read `references/boot-screen.md` before printing startup status
   - **Outcome Demo**: Read `references/outcome-demo.md` before outcome validation/sign-off
+  - **Outcome Discovery**: Read `references/outcome-discovery.md` before adding a new outcome/phase or pivoting to a new outcome
   - **Menus**: Read `references/branded-menu.md` before displaying any menu
   - **Formatting**: Read `references/formatting-rules.md` before formatting lists/output
   - **Issue reporting**: Read `references/issue-reporting.md` when handling freeform issue detection
@@ -240,7 +241,7 @@ Mother Brain transforms high-level visions into executable reality by:
 - **Adaptive planning**: Roadmaps are living documents, not contracts
 - **Outcome-Driven Roadmap (CORE PRINCIPLE)**: Roadmaps are organized by **Outcomes** (user abilities), not tasks. Each outcome is an "Ability to [do something]" that fulfills a user need. Tasks exist only as internal implementation details. Users validate **acceptance criteria** for outcomes, never technical tasks. This keeps validation meaningful ("Can I now do X?") rather than abstract ("Does this code look right?").
 - **User Needs as Foundation**: During Vision Discovery, capture explicit user needs as "Ability to..." statements. These become the outcomes in the roadmap. Every outcome traces back to which user need it fulfills.
-- **Acceptance Criteria Validation**: User signs off on acceptance criteria for each outcome, not on individual tasks. For each criterion, ask: "Can you do this now? Yes/No". If "No" → invoke Child Brain to analyze and fix.
+- **Acceptance Criteria Validation**: User signs off on acceptance criteria for each outcome, not on individual tasks. Default to **batch sign-off**: show the full criteria list once, run the outcome demo, then ask whether everything works. If something fails or needs adjustment → invoke Child Brain. Only drill into per-criterion Yes/No when the user can't identify what is failing.
 - **Best practice structure**: Organize projects using standard dev conventions
 - **Skill automation**: Create skills for repetitive tasks proactively
 - **User validation**: Always confirm outcomes meet expectations via acceptance criteria before marking complete
@@ -381,17 +382,17 @@ Key rules: Use `allow_freeform: true` on all `ask_user` calls. Check freeform re
    - Proceed immediately to Step 2 (Detect Project State)
 
 ### 2. **Detect Project State & Show Progress**
-    
-   - Runs version check, meta-mode detection, fast startup optimization, auto-update with improvement capture, and artifact scanning.
-   - **Read `references/state-detection.md`** for the full detection procedure (version check, meta-mode, fast startup, auto-update Steps A–D, artifact list)
-   - After detection completes, display the appropriate menu below based on project state:
+     
+    - Runs version check, meta-mode detection, fast startup optimization, auto-update with improvement capture, and artifact scanning.
+    - **Read `references/state-detection.md`** for the full detection procedure (version check, meta-mode, fast startup, auto-update Steps A–D, artifact list)
+    - After detection completes, display the appropriate menu below based on project state:
 
-   **If project exists:**
-   - Load session state from `docs/session-state.json`
-   
-   - **Git Check (ensure git is available)**:
-     - Check if `.git` folder exists in project root
-     - If NOT exists:
+    **If project exists:**
+    - Load session state from `.mother-brain/session-state.json`
+    
+    - **Git Check (ensure git is available)**:
+      - Check if `.git` folder exists in project root
+      - If NOT exists:
        ```
        ⚠️ Git repository not found - initializing...
        ```
@@ -423,11 +424,11 @@ Key rules: Use `allow_freeform: true` on all `ask_user` calls. Check freeform re
    - **If "I have a new idea"**: Jump to **Step 2F: Idea Capture & Prioritization**
    - **If "Improve Mother Brain"**: Jump to **Step 2A: Improve Mother Brain Menu**
 
-   **If existing project WITHOUT Mother Brain artifacts (ONBOARDING):**
-   - Detect: Files exist in directory, but NO `.mother-brain/` folder and NO `docs/vision.md`
-   - Display:
-     ```
-     🧠 I see an existing project here!
+    **If existing project WITHOUT Mother Brain artifacts (ONBOARDING):**
+    - Detect: Files exist in directory, but NO `.mother-brain/` folder (Mother Brain not installed here)
+    - Display:
+      ```
+      🧠 I see an existing project here!
      
      I can help you manage this project using the Mother Brain framework.
      I'll scan your codebase, understand what you've built, and help you
@@ -438,12 +439,19 @@ Key rules: Use `allow_freeform: true` on all `ask_user` calls. Check freeform re
      - "Yes, onboard Mother Brain into this project"
      - "No, start fresh (ignore existing files)"
 
-   - **If user selects onboarding**: Jump to **Step 2.2: Existing Project Onboarding**
+    - **If user selects onboarding**: Jump to **Step 2.2: Existing Project Onboarding**
 
-   **If new project (empty directory or user chose fresh start):**
-   - Display welcome:
-     ```
-     🧠 Welcome to Mother Brain!
+    **If Mother Brain is installed but this folder is scaffolding-only (NEW PROJECT):**
+    - Detect:
+      - `.mother-brain/session-state.json` exists AND its project is unset (e.g., `project: null`)
+      - `.mother-brain/docs/vision.md` does NOT exist
+      - Repo root contains only Mother Brain scaffolding (e.g., `.mother-brain/`, `.github/`, `.agents/`, `AGENTS.md`, optional `.git/`)
+    - Treat this as a **new project** (show the new-project welcome flow below). Do NOT show onboarding.
+
+    **If new project (empty directory or user chose fresh start):**
+    - Display welcome:
+      ```
+      🧠 Welcome to Mother Brain!
      
      I'm your AI project companion. Tell me what you want to build,
      and I'll help you make it real—step by step.
@@ -541,13 +549,13 @@ Key rules: Use `allow_freeform: true` on all `ask_user` calls. Check freeform re
      Encountered friction or have ideas for improvement?
      ```
    
-   - Use `ask_user` with choices:
-     - "Something broke or didn't work"
-     - "A feature is missing"
-     - "The workflow is confusing"
-     - "I have a suggestion for improvement"
-     - "📤 Send my local improvements (auto-detect changes)"
-     - "⬅️ Back to project"
+    - Use `ask_user` with choices:
+      - "Something broke or didn't work"
+      - "A feature is missing"
+      - "The workflow is confusing"
+      - "I have a suggestion for improvement"
+      - "📤 Send community improvements (auto-detect local changes)"
+      - "⬅️ Back to project"
    
    **Step 2A.0.1: Friction Auto-Detection (for "Something broke")**
    
@@ -604,17 +612,25 @@ Key rules: Use `allow_freeform: true` on all `ask_user` calls. Check freeform re
      - Work on implementing if appropriate
      - Offer to send improvement when done
    
-   - **If "Send my local improvements"**: Continue to Step 2A.1 (Auto-Detect)
+   - **If "Send community improvements"**: Continue to Step 2A.1 (Auto-Detect)
    
    - **If "Back to project"**: Return to main menu (Step 2)
 
 ### 2A.1 **Send Improvement** (Automatic Multi-Issue Contribution)
-   - When user selects "📤 Send my local improvements":
+   - When user selects "📤 Send community improvements":
    - **Read `references/improvement-pipeline.md`** for the full pipeline (Steps 2A.1.1–2A.1.5)
    - Covers: gather sources (learning log, core file diffs, conversation context), deduplication via issues tracker, correlate learnings with file changes, generate individual GitHub issues, submit via gh CLI (with manual fallback), update tracker
    - Target repository: `super-state/mother-brain`
    - After submission → return to main menu (Step 2)
 
+### 2H. **Outcome Discovery & Planning** (Mini Requirements Session)
+   - A mini "vision-like" discovery workflow for new outcomes/phases or pivots. Clarifies the outcome, does lightweight research, consults Project Brain constraints, detects skill gaps (via Elder Brain gate + skill-creator), and writes the outcome into the roadmap with a do-now vs later choice.
+   - **Read `references/outcome-discovery.md`** for the full procedure.
+   - This flow must be available from:
+     - Layer 2 (Roadmap): "🔎 Discover a new outcome"
+     - Layer 3 (Outcome execution): "🔎 Pivot to a different outcome"
+   - Also run it when starting an outcome that hasn't been clarified yet (placeholder outcome or unclear scope). In that case, treat the discovery as "clarify/refine this outcome" and update the existing roadmap entry.
+
 ### 2A.2 **Review Community Improvements** (Maintainer Workflow)
    - Maintainer workflow for reviewing community improvement issues. Lists open issues, shows AI-generated analysis, and provides accept/reject/request-changes actions.
    - **Read `references/review-improvements.md`** for the full review procedure (Steps 2A.2.1–2A.2.5, issue listing, diff review, auto-commenting, label management)
@@ -1504,6 +1520,7 @@ Progress: [X/Y] criteria verified
   - "Continue working" (→ resume/start next task in this outcome)
   - "I have feedback on this outcome"
   - "Something's broken"
+  - "🔎 Pivot to a different outcome"
   - "Do something else (→ Roadmap)" (→ Layer 2)
   - "Mark outcome complete"
 - Freeform available → route to Freeform Classification (Step 12)
@@ -1523,6 +1540,12 @@ Progress: [X/Y] criteria verified
   - Invoke Child Brain immediately (friction detected)
   - After Child Brain completes, return to Step 10E
 
+- **If "🔎 Pivot to a different outcome"**:
+  - Run **Step 2H (Outcome Discovery & Planning)**
+  - After discovery:
+    - If user chose "Do this next": set it as active and return to Step 10E
+    - If user chose "Add to roadmap for later": return to Step 10E (current outcome unchanged)
+
 - **If "Do something else"**:
   - Navigate UP one layer to **Step 11 (Roadmap Menu / Layer 2)**
   - Save current outcome progress before navigating
@@ -1622,19 +1645,21 @@ Progress: [X/Y] criteria verified
    
    **Step 11.2: Present Layer 2 Menu**
    
-   - Use `ask_user` with choices:
-     - "Continue next outcome" (→ Layer 3 Outcome Execution Menu)
-     - "Review specific outcome"
-     - "💡 I have a new idea"
-     - "Adjust priorities (Value Framework)"
-     - "Take a break (save progress)"
+- Use `ask_user` with choices:
+  - "Continue next outcome" (→ Layer 3 Outcome Execution Menu)
+  - "Review specific outcome"
+  - "🔎 Discover a new outcome"
+  - "💡 I have a new idea"
+  - "Adjust priorities (Value Framework)"
+  - "Take a break (save progress)"
    - Freeform available for custom actions → route to Freeform Classification (Step 12)
    
    **Step 11.3: Handle Selections**
    
-   - **If "Continue next outcome"**:
-     - Load next uncompleted outcome from roadmap
-     - Jump to **Layer 3 — Outcome Execution Menu (Step 10E)**
+- **If "Continue next outcome"**:
+  - Load next uncompleted outcome from roadmap
+  - If this outcome is still a placeholder or needs clarification, run **Step 2H (Outcome Discovery & Planning)** to refine it before starting execution.
+  - Jump to **Layer 3 — Outcome Execution Menu (Step 10E)**
    
    - **If "Review specific outcome"**:
      - List all outcomes with status (✅/🔄/⬜)
@@ -1651,10 +1676,14 @@ Progress: [X/Y] criteria verified
      - Re-score existing roadmap tasks if weights changed significantly
      - Show what moved, then return to Step 11.2
    
-   - **If "Take a break"**:
-     - Save session state to `session-state.json`
-     - Display progress summary
-     - End session gracefully
+- **If "Take a break"**:
+  - Save session state to `session-state.json`
+  - Display progress summary
+  - Then present a choice:
+    - "Back to Main Menu (Layer 1)" (return to Step 2)
+    - "Back to Roadmap Menu (Layer 2)" (return to Step 11.2)
+    - "Exit session" (end cleanly after showing a short resume hint)
+  - **Exit discipline**: If user selects "Exit session", display a short "Session ended" message and a single resume hint (`/mother-brain`), then STOP. Do not present additional menus after exit.
    
    - Save session state to `docs/session-state.json`:
      ```json
@@ -1720,8 +1749,10 @@ Analyze the freeform text and classify as one of:
 
 2. **Feature/Idea** — User has a new feature or idea
    - Trigger words: "what if", "could we", "add", "new feature", "idea", "I want"
-   - → Route to Step 2F (Idea Capture & Prioritization)
-   - → After capture, return to the LAYER the user was on (not Layer 1)
+   - Use `ask_user` to choose:
+     - "💡 Quick idea capture" (→ Step 2F)
+     - "🔎 Outcome discovery (plan it onto the roadmap)" (→ Step 2H)
+   - After capture/discovery, return to the LAYER the user was on (not Layer 1)
 
 3. **Clarification/Question** — User is asking about the project/roadmap/outcome
    - Trigger words: "why", "what does", "how", "explain", "tell me about", "?"
@@ -1933,3 +1964,6 @@ See `references/resources.md` for:
 - Vision document templates
 - Roadmap examples
 - Task management methodologies
+- **If "🔎 Discover a new outcome"**:
+  - Run **Step 2H (Outcome Discovery & Planning)**
+  - After discovery, return to Step 11.2

package/skills/mother-brain/references/mvp-complete.md

@@ -54,7 +54,10 @@
    
    - If user selects a delivery option:
      - Check if relevant skill exists (e.g., "deployment-manager", "cicd-setup")
-     - If skill doesn't exist: Invoke skill-creator to create delivery skill
+     - If skill doesn't exist:
+       - Consult Project Brain (`.mother-brain/project-brain.md`) for project-specific delivery constraints/preferences
+       - Consult Elder Brain RETRIEVE for the relevant technologies/platforms BEFORE invoking skill-creator
+       - Invoke skill-creator to create the delivery skill with Project Brain + Elder Brain context
      - Execute delivery using appropriate skill
      - Validate deployment/release succeeded
    
@@ -90,6 +93,7 @@
      - Create task documents (like Step 8)
      - Identify patterns that need new skills
    - If new patterns detected: Create skills using skill-creator
+   - Before creating any new skill, consult Elder Brain RETRIEVE for relevant technologies/domains and pass findings into skill-creator
    - Update roadmap with detailed tasks
    - Return to Step 11 (Roadmap Menu)
    
@@ -97,7 +101,7 @@
    - Use `ask_user` (freeform): "What direction do you want to take the project?"
    - Re-run vision discovery (Step 3) with context of what exists
    - Generate new roadmap phases while preserving completed work
-   - Create any needed new skills using skill-creator
+   - Create any needed new skills using skill-creator (consult Elder Brain RETRIEVE first, and bake gotchas into the skill context)
    - Return to Step 11 (Roadmap Menu)
    
    **If "Add new features":**
@@ -106,7 +110,9 @@
    - If patterns detected that need skills:
      - Display: "I detect patterns that could benefit from new skills:"
      - List detected patterns
-     - Invoke skill-creator for each pattern
+     - For each skill:
+       - Consult Elder Brain RETRIEVE for relevant technologies/domains
+       - Invoke skill-creator with Elder Brain findings baked in
    - Add features as new tasks to appropriate phase
    - Update roadmap
    - Return to Step 11 (Roadmap Menu)

package/skills/mother-brain/references/onboarding-workflow.md

@@ -46,7 +46,9 @@ When user selects to onboard Mother Brain into an existing project, follow these
 ## Step 2.2.4: Skill Identification
 - Analyze patterns in existing code
 - Identify repetitive work that warrants skills
-- Invoke skill-creator for detected patterns
+- Consult Project Brain (`.mother-brain/project-brain.md`) for project-specific constraints/preferences (if it exists)
+- Consult Elder Brain RETRIEVE for relevant technologies/domains BEFORE invoking skill-creator
+- Invoke skill-creator for detected patterns with Project Brain + Elder Brain context baked in
 
 ## Step 2.2.5: Confirmation
 - Display:

package/skills/mother-brain/references/outcome-demo.md

@@ -24,9 +24,17 @@ How to verify (quick path):
 - Step 2: [Click/Action]
 - Expected: [What should happen]
 
-Then validate each acceptance criterion (Yes/No).
+Acceptance Criteria:
+- I can ...
+- I can ...
+
+Then validate acceptance criteria using batch sign-off (preferred): show the full list once, then ask if everything works. Use per-criterion Yes/No only as fallback when the user can't identify what's failing.
+
+Use choices like:
+- "✅ Everything works (all criteria pass)"
+- "⚠️ Something isn't working (tell me what's failing)"
+- "🛠 Works but needs adjustment (tell me what to change)"
 
 Rules:
 - If login/authorization/setup requires user action, guide them step-by-step.
 - If auto-launch fails, provide one fallback method and then clear manual steps with full paths/URLs.
-

package/skills/mother-brain/references/outcome-discovery.md

@@ -0,0 +1,142 @@
+# Outcome Discovery — Mini Requirements Session (Per Outcome / Phase)
+
+Use this procedure when:
+- The user wants to add a new outcome to the roadmap
+- The user wants to pivot mid-outcome to a different outcome
+- The user is about to start an existing roadmap outcome that is still a placeholder or unclear (refine it before execution)
+
+Purpose:
+- Treat each new outcome like a mini vision session: clarify intent, do lightweight research, consult project constraints, detect skill gaps, and only then plan it onto the roadmap.
+- End with a clear decision: do it now vs schedule it for later (and confirm priority).
+
+---
+
+## Step OD.1: Capture the Outcome (Freeform)
+
+Display:
+```
+🔎 Outcome Discovery
+
+Tell me the outcome you want.
+Write it as: "Ability to [do something]" if you can.
+```
+
+Use `ask_user` with `allow_freeform: true`.
+
+---
+
+## Step OD.2: Project Brain Gate (Before Planning)
+
+Before drafting acceptance criteria and demo/proof, consult Project Brain:
+- Read `.mother-brain/project-brain.md` (if it exists)
+- Apply relevant preferences/constraints:
+  - Style & tone expectations
+  - Validation checks to preserve
+  - Known integration constraints
+  - Any "do/don't" rules discovered from prior work
+
+---
+
+## Step OD.3: Adaptive Clarification Loop (Repeat Until Clear)
+
+After EACH user response:
+1. Extract domain signals and constraints:
+   - Who is the user?
+   - What is the exact ability (scope boundaries)?
+   - What data is involved (PII/orders/payments/health)?
+   - What does "done" look like (proof)?
+2. If a new/unclear domain is detected, do quick research with `web_search`:
+   - "[domain] best practices"
+   - "[domain] common pitfalls"
+   - "[domain] UX expectations"
+3. Identify likely skill needs (do we need a new skill or to invoke an existing one?)
+4. Ask the single most important next question (avoid long questionnaires).
+
+Use `ask_user` with 2-3 choices whenever discrete options exist, otherwise allow freeform.
+
+Stop the loop only when:
+- The outcome statement is unambiguous
+- Acceptance criteria can be written as testable user checks
+- A demo/proof path is clear
+
+---
+
+## Step OD.4: Draft the Outcome Package (Batch Correction)
+
+Create a draft:
+- Outcome name: `📋 Ability to ...`
+- "So that" benefit line (why this matters)
+- Acceptance criteria (3-7 items, testable by the user)
+- Demo / Proof (what will open, where, and the quick verification path)
+- Internal tasks (high-level list; implementation details only)
+
+Then ask for correction (batch, not per-line):
+
+Use `ask_user`:
+- "✅ Looks right — proceed"
+- "✏️ Needs adjustment (tell me what to change)"
+- "🔄 Actually different outcome (restart discovery)"
+
+If adjustment/restart is chosen, continue OD.3.
+
+---
+
+## Step OD.5: Skill Check (Autonomous, With Elder Brain Gate)
+
+- Scan existing project skills (`.github/skills/`) for relevant capabilities.
+- If a capability gap is detected:
+  - FIRST: Consult Elder Brain RETRIEVE for relevant gotchas/patterns:
+    - Invoke Elder Brain RETRIEVE for the domains/technologies the skill will touch
+    - If Elder Brain returns relevant info, bake it into the skill context
+  - Then invoke `skill-creator` to create/update the necessary skill(s) using:
+    - Project Brain preferences (project-specific constraints)
+    - Lightweight domain research (if needed)
+    - Elder Brain gotchas/patterns (cross-project defensive knowledge)
+  - Do not ask for permission to create the skill; do it as part of discovery.
+
+---
+
+## Step OD.6: Priority + Scheduling Decision (User Choice)
+
+Load:
+- `.mother-brain/docs/value-framework.md` (if it exists)
+- `.mother-brain/docs/vision.md` and `.mother-brain/docs/roadmap.md`
+
+Determine recommended priority:
+- If Value Framework exists: score outcome and compare to nearby outcomes
+- Otherwise: assess vision alignment, user impact, effort, dependencies
+
+Use `ask_user`:
+- "🚀 Do this next (make it the active/next outcome)"
+- "🗓 Add to roadmap for later (keep current plan)"
+- "📌 Adjust priority (tell me higher/lower)"
+
+If "Adjust priority":
+- Ask for brief rationale (freeform), apply the override, and (if repeated) flag for Value Framework weight adjustment.
+
+---
+
+## Step OD.7: Write It Into the Roadmap
+
+- Insert (or refine) the outcome in `.mother-brain/docs/roadmap.md` with:
+  - Acceptance criteria checklist
+  - Demo / Proof section
+  - Priority score / note
+  - Internal tasks list
+- If it belongs in a new phase, create the phase section and explain why (briefly).
+
+Update `.mother-brain/session-state.json`:
+- If "Do this next": set the new outcome as active
+- Otherwise: keep current outcome, just record that a new outcome was added
+
+Return control to the menu the user came from:
+- If called from Roadmap (Layer 2): return to Step 11
+- If called from Outcome work (Layer 3 pivot): return to Step 10E (or Step 11 if the user navigated up)
+
+---
+
+Key rules:
+- Discovery happens BEFORE planning/execution for a new outcome.
+- Always provide the do-now vs later choice after discovery.
+- Keep questions tight: one meaningful question per loop.
+

package/skills/mother-brain/references/review-improvements.md

@@ -4,17 +4,27 @@
    
    **Step 2A.2.1: List Open Improvement Issues**
    
-   - Fetch issues with "improvement" or "community-contribution" labels:
-     ```
-     github-mcp-server: list_issues
-     state: open
-     labels: ["improvement"]
-     ```
+   - **Do NOT assume repo-specific labels exist.** Many repos only have default labels
+     (`enhancement`, `documentation`, etc.). Improvement submissions created by Mother Brain
+     also commonly use a title prefix like `[Improvement]`.
+   
+   - Fetch open improvement issues using this fallback order:
+     - **Primary (title prefix)**: search for issues whose title includes `[Improvement]`
+       - Example (gh CLI):
+         - `gh issue list --repo super-state/mother-brain --state open --search "is:issue is:open [Improvement]" --limit 20`
+     - **Secondary (default labels)**: search for likely labels
+       - `label:enhancement` and/or `label:documentation`
+       - Example (gh CLI):
+         - `gh issue list --repo super-state/mother-brain --state open --label enhancement --limit 20`
+         - `gh issue list --repo super-state/mother-brain --state open --label documentation --limit 20`
+     - **Last-resort (recent open issues)**: list recent open issues and manually select
+       - Example (gh CLI):
+         - `gh issue list --repo super-state/mother-brain --state open --limit 20`
    
    - **If no issues**: Display "📭 No community improvements pending review." → Return to menu
    
    - **If issues exist**: Display summarized list:
-     ```
+      ```
      📥 Community Improvements to Review ([count] pending)
      
      ┌─────────────────────────────────────────────────────────────┐
@@ -25,10 +35,18 @@
      │ 📁 [files affected count] files • [lines changed] lines    │
      └─────────────────────────────────────────────────────────────┘
      
-     [Repeat for each issue, max 5 shown]
+     [Repeat for each issue, up to 10 shown]
+
+     If more than 10 issues exist:
+     - Show a second menu choice to view the next page (issues 11–20)
+     - Also offer a "Deduplicate by title" view (recommended when many issues share the same `[Improvement] YYYY-MM-DD - ...` titles)
      ```
    
-   - Use `ask_user` with issue numbers as choices + "Back to menu"
+   - Use `ask_user` with:
+     - Issue numbers as choices (for the visible page)
+     - "Next page"
+     - "Deduplicate by title (recommended)"
+     - "Back to menu"
    
    **Step 2A.2.2: Review Selected Issue**
 
@@ -66,6 +84,14 @@
      - "❌ Reject - close with explanation"
      - "💬 Request changes - ask for modifications"
      - "⏭️ Skip - review later"
+
+   **Deduplicate by title (helper view)**
+   - When "Deduplicate by title" is selected:
+     - Group open issues by normalized title (strip issue number, keep full title text)
+     - For each group, show ONLY the newest issue number as the representative
+     - Present the representative issue numbers as choices, plus:
+       - "Show all issues (paged)"
+       - "Back to menu"
    
    **Step 2A.2.3: Accept Improvement**
 

package/skills/mother-brain/references/roadmap-generation.md

@@ -125,7 +125,7 @@
      - Outcome 2: [name]
      - Outcome 3: [name]
      
-     **Validation Method**: User confirms each criterion with "Yes, I can do this"
+     **Validation Method**: Batch sign-off (preferred). Show the full acceptance-criteria list once, run the outcome demo, then ask whether everything works. Use per-criterion Yes/No only as fallback when the user can't identify what's failing.
      
      **Next Step After MVP**: [From Step 6A research]
      

package/skills/mother-brain/references/state-detection.md

@@ -11,22 +11,41 @@
       npm view mother-brain version --json 2>$null
       ```
     - Compare against:
-      - If in framework repo: `cli/package.json` version field
-      - If in project: `.mother-brain/version.json` version field
+      - If in framework repo: `cli/package.json` version field (source repo version)
+      - If in project: `.mother-brain/version.json` installed field (installed/tracked version)
     - **If newer version exists**:
-      ```
-      ⚠️ Mother Brain Update Available
-      
-      Installed: v[current]
-      Latest: v[npm version]
+      - **If in a project folder** (has `.mother-brain/version.json`):
+        ```
+        ⚠️ Mother Brain Update Available
+        
+        Installed: v[current]
+        Latest: v[npm version]
+        
+        Update recommended before continuing.
+        ```
+        - Use `ask_user` with choices:
+          - "Update now (recommended)"
+          - "Skip this time"
+        - **If "Update now"**: Run `npx -y mother-brain update`, then continue
+        - **If "Skip"**: Continue but note version mismatch
       
-      Update recommended before continuing.
-      ```
-      - Use `ask_user` with choices:
-        - "Update now (recommended)"
-        - "Skip this time"
-      - **If "Update now"**: Run auto-update (see update commands below), then continue
-      - **If "Skip"**: Continue but note version mismatch
+      - **If in the Mother Brain framework repo** (source code checkout):
+        ```
+        ⚠️ Mother Brain Release Ahead of This Checkout
+        
+        Repo version (cli/package.json): v[current]
+        Latest release (npm): v[npm version]
+        
+        This usually means your local checkout hasn’t been pulled to the latest tag yet.
+        ```
+        - Use `ask_user` with choices:
+          - "Fetch tags + pull latest framework changes (recommended)"
+          - "Skip this time"
+        - **If "Fetch tags + pull"**:
+          - Run `git fetch --tags origin`
+          - Run `git pull --ff-only origin main`
+          - Then continue detection
+        - **If "Skip"**: Continue but note mismatch
     - **If current or check fails**: Continue silently
    
    **🧬 META-MODE DETECTION (AFTER VERSION CHECK)**:
@@ -37,6 +56,8 @@
      4. If ALL of these exist → we are in the Mother Brain framework repo
    
    - **If in Mother Brain framework repo**:
+     - Refresh tags before reporting "last release" (quiet):
+       - Run `git fetch --tags origin`
      - Check `.mother-brain/meta-mode.json` for existing meta session state
      - Display:
        ```
@@ -77,11 +98,34 @@
    - **If NOT in framework repo**: Continue with normal detection below
    
    **⚡ FAST STARTUP OPTIMIZATION (MANDATORY)**:
-   - **Single file check first**: Check ONLY `.mother-brain/session-state.json` - if it exists, project exists
+   - **Single file check first**: Check ONLY `.mother-brain/session-state.json`
+     - If it exists: Mother Brain is installed in this folder (NOT necessarily an "existing project")
+     - If it does not exist: treat as "no Mother Brain artifacts" (possible onboarding or brand-new folder)
    - **Parallel tool calls**: When multiple checks are needed, run them in ONE response (not sequentially)
    - **Lazy loading**: Only load vision.md, roadmap.md, README.md when actually needed (not at startup)
    - **Minimal detection**: For new project detection, a single glob for `.mother-brain/` is sufficient
    - Goal: User sees menu within 1-2 tool calls, not 6+
+
+   **🧩 SCAFFOLDING-ONLY DETECTION (CRITICAL - fixes false "existing project" onboarding)**
+   - A freshly created folder can look like an "existing project" after `mother-brain init` because init creates:
+     - `.mother-brain/session-state.json` (with `project: null`)
+     - `.mother-brain/version.json`
+     - `.github/skills/*`
+     - `.agents/skills/*`
+     - `AGENTS.md`
+     - `.git/` (if git init is performed)
+   - **Rule**: If the folder contains ONLY Mother Brain scaffolding, treat it as a **new project** (show the new-project welcome flow), NOT onboarding.
+   - Detect scaffolding-only as:
+     1. `.mother-brain/session-state.json` exists AND its JSON has `project: null` (or no project name)
+     2. `.mother-brain/docs/vision.md` does NOT exist
+     3. The repo root contains no "real project files" beyond:
+        - `.mother-brain/`
+        - `.github/`
+        - `.agents/`
+        - `.git/`
+        - `AGENTS.md`
+     - If all true → show **New Project** welcome menu (Step 2 new project)
+     - If false → proceed with normal project/onboarding detection
    
    **📦 AUTO-UPDATE CHECK (on startup, if project exists)**:
    - If `.mother-brain/version.json` exists:
@@ -109,4 +153,4 @@
      - `.mother-brain/docs/roadmap.md` - Current roadmap (load only when needed)
      - `.mother-brain/docs/tasks/` - Task documentation folder
      - `.github/skills/` - Project-specific skills
-   
+   

package/skills/mother-brain/references/task-validation.md

@@ -76,7 +76,9 @@
       ```
       📋 Outcome Complete: [Ability to do X]
       
-      Please verify each criterion — can you do this now?
+      Acceptance Criteria:
+      - I can ...
+      - I can ...
       ```
 
     - **MANDATORY: Outcome Demo First (Interactive Experience)**:
@@ -84,30 +86,34 @@
       2. Launch the experience for the user (app/page/flow) so they can interact with the outcome
          - Do NOT ask the user to run startup commands
          - If launching fails, use one fallback, then provide clear manual steps
-      3. Only after the demo is in front of the user, proceed to acceptance-criteria Yes/No sign-off
+      3. Only after the demo is in front of the user, proceed to acceptance-criteria sign-off (batch-first)
     
-    - For EACH acceptance criterion, use `ask_user` with choices:
-      - "Yes, I can do this ✅"
-      - "No, something's wrong ❌"
-   
-   - **If "Yes"**: Mark criterion complete, proceed to next
-   - **If "No"**: 
-     - Invoke Child Brain immediately (friction detected)
-     - Child Brain analyzes what went wrong
-     - Fix applied, re-validate this criterion
+    - **Batch acceptance sign-off (preferred)**:
+      - Display the FULL acceptance-criteria list at once
+      - Then use `ask_user` with choices:
+        - "✅ Everything works (all criteria pass)"
+        - "⚠️ Something isn't working (tell me what's failing)"
+        - "🛠 Works but needs adjustment (tell me what to change)"
+      - If the user reports failures/adjustments:
+        - Ask them to paste the failing criteria text or numbers (freeform)
+        - Invoke Child Brain immediately (friction detected), fix, then re-run demo + batch sign-off
+      - Only drill into per-criterion Yes/No when:
+        - The user says "some fail" but can't identify which, or
+        - The outcome has many criteria and pinpointing is unclear
    
    - **Example validation flow**:
      ```
      📋 Ability to see my emails inside the portal
      
-     Criterion 1: I can see my inbox with sender, subject, and preview
-     → [Yes, I can do this] [No, something's wrong]
-     
-     Criterion 2: I can click an email to read the full content
-     → [Yes, I can do this] [No, something's wrong]
+     Acceptance Criteria:
+     1. I can see my inbox with sender, subject, and preview
+     2. I can click an email to read the full content
+     3. New emails appear without refreshing the page
      
-     Criterion 3: New emails appear without refreshing the page
-     → [Yes, I can do this] [No, something's wrong]
+     Now that the demo is in front of you, which is true?
+     1. ✅ Everything works (all criteria pass)
+     2. ⚠️ Something isn't working (tell me what's failing)
+     3. 🛠 Works but needs adjustment (tell me what to change)
      ```
    
    - **All criteria pass**: Mark outcome complete (✅)
@@ -117,6 +123,15 @@
    - Update task document with final status
    - Update roadmap checklist
    
+   - **Post-outcome wrap-up + commit discipline (order matters)**:
+     1. Run Steps 10B and 10C (mandatory learning + documentation checkpoint)
+     2. If the outcome was accepted, run the outcome-level retrospective:
+        - Invoke Child Brain (post-delivery retrospective)
+        - Apply any approved Mother Brain / Project Brain / skill updates
+     3. If the repo is a git repo and there are uncommitted changes:
+        - Create a commit AFTER the retrospective updates are applied
+        - Then return the user to the Layer 2 Roadmap Menu
+   
    **⚠️ CRITICAL: After marking task complete, proceed through Steps 10B, 10C, and optionally 10D before returning to the Outcome Execution Menu (Layer 3).**
    
    **⛔ BLOCKING GATE - Steps 10B and 10C are MANDATORY:**