mother-brain 0.7.2 → 0.7.4

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.2";
+var VERSION = "0.7.4";
 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.2",
+  "version": "0.7.4",
   "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
@@ -541,13 +542,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 +605,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 +1513,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 +1533,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 +1638,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 +1669,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 +1742,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 +1957,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/release-checklist.md

@@ -22,6 +22,8 @@ One-click release: commit, version bump, push, tag, and publish.
 ## Step 2D.1: Verify & Analyze
 - Check current folder is mother-brain framework folder
 - If in a project folder: Display error and offer to return to framework
+- Refresh remote release context (quiet):
+  - Run `git fetch --tags origin`
 - Run `git status` to verify there are changes to release
 - If no changes: Display "Nothing to release" and return to menu
 

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/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:**