learnship 2.0.11 → 2.1.1

package/learnship/workflows/forensics.md

@@ -0,0 +1,118 @@
+---
+description: Post-mortem investigation for failed or stuck workflows — read-only diagnostic report
+---
+
+# Forensics
+
+Post-mortem investigation for failed or stuck workflows. Analyzes git history, `.planning/` artifacts, and file system state to detect anomalies and generate a structured diagnostic report.
+
+**Usage:** `forensics` or `forensics [problem description]`
+
+**Principle:** This is a read-only investigation. Do not modify project files. Only write the forensic report.
+
+## Step 1: Get Problem Description
+
+If a description was provided as an argument, use it. Otherwise ask:
+
+> "What went wrong? Describe the issue."
+
+Record the problem description for the report.
+
+## Step 2: Gather Evidence
+
+Collect data from all available sources. Missing sources are fine — adapt to what exists.
+
+### 2a. Git History
+
+```bash
+git log --oneline -30
+git log --format="%H %ai %s" -30
+git log --name-only --format="" -20 | sort | uniq -c | sort -rn | head -20
+git status --short
+git diff --stat
+```
+
+Record:
+- Commit timeline (dates, messages, frequency)
+- Most-edited files (potential stuck-loop indicator)
+- Uncommitted changes (potential crash/interruption indicator)
+
+### 2b. Planning State
+
+Read these files if they exist:
+- `.planning/STATE.md` — current milestone, phase, progress, blockers
+- `.planning/ROADMAP.md` — phase list with status
+- `.planning/config.json` — workflow configuration
+
+### 2c. Phase Artifacts
+
+```bash
+ls .planning/phases/*/
+```
+
+For each phase, check which artifacts exist (PLAN, SUMMARY, VERIFICATION, CONTEXT, RESEARCH, UAT). Track which phases have complete artifact sets vs gaps.
+
+## Step 3: Analyze Anomalies
+
+| Pattern | Indicates | Severity |
+|---------|-----------|----------|
+| Same file edited 5+ times in 20 commits | Stuck execution loop | High |
+| PLAN.md exists but no SUMMARY.md | Execution interrupted | Medium |
+| Large time gap between consecutive commits | Session interrupted or context exhausted | Medium |
+| VERIFICATION.md with `gaps_found` | Phase incomplete | Medium |
+| STATE.md references non-existent phase dir | State/filesystem mismatch | High |
+| Uncommitted changes + old timestamps | Abandoned session | Low |
+
+## Step 4: Determine Root Cause
+
+| Category | Description | Recovery |
+|----------|-------------|----------|
+| **Execution stuck** | Agent looped on same files/tests | Re-run with `--wave` or fix trigger |
+| **Context exhaustion** | Agent ran out of context mid-phase | Break into smaller plans, re-run |
+| **Session interrupted** | Human or system terminated mid-work | Resume with `/resume-work` |
+| **State mismatch** | STATE.md doesn't match filesystem | Manual STATE.md correction |
+| **Plan deficiency** | Plans were wrong | Re-plan with `plan-phase --gaps` |
+| **External failure** | API, dependency, or environment issue | Fix external issue, re-run |
+
+## Step 5: Write Forensic Report
+
+```bash
+node -e "require('fs').mkdirSync('.planning/reports',{recursive:true})"
+```
+
+Write `.planning/reports/FORENSIC-[YYYY-MM-DD].md` with: evidence summary, anomalies detected, root cause (category + explanation + confidence), recommended recovery steps, and prevention advice.
+
+Commit:
+```bash
+git add .planning/reports/
+git commit -m "docs: forensic report"
+```
+
+## Step 6: Present Findings
+
+```
+learnship > FORENSIC REPORT COMPLETE
+
+Root Cause: [category] — [one-line explanation]
+Confidence: [high/medium/low]
+
+Recovery:
+1. [action]
+2. [action]
+
+Report: .planning/reports/FORENSIC-[date].md
+```
+
+---
+
+## Learning Checkpoint
+
+Read `learning_mode` from `.planning/config.json`.
+
+**If `auto`:**
+
+> **Learning moment:** Failures are high-signal learning opportunities:
+>
+> `@agentic-learning reflect` — What pattern caused this failure? What would you watch for next time? Structured reflection on failures builds diagnostic intuition.
+
+**If `manual`:** Add quietly: *"Tip: `@agentic-learning reflect` to extract lessons from this failure."*

package/learnship/workflows/help.md

@@ -16,7 +16,7 @@ You only need to remember **5 commands** to use learnship effectively:
 | `/next` | Auto-pilot — reads state and runs the right workflow for you |
 | `/new-project` | Starting a brand new project |
 | `/quick "..."` | One-off task with atomic commit, no ceremony |
-| `/help` | This screen — see all 49 commands |
+| `/help` | This screen — see all 57 commands |
 
 Everything else below is discoverable from `/ls` as you go.
 
@@ -87,9 +87,11 @@ Everything else below is discoverable from `/ls` as you go.
 | `/review [mode]` | Multi-persona code review (correctness, testing, security, performance, maintainability) |
 | `/challenge [description]` | Product + engineering challenge gate — is this worth building? |
 | `/ship` | Ship pipeline: test → lint → commit → push → PR |
-| `/ideate [focus]` | Codebase-grounded divergent thinking — discover what to work on |
+| `/ideate [focus]` | Codebase-grounded divergent thinking — discover what to work on (`--explore` for Socratic mode) |
 | `/guard [scope\|off]` | Safety mode — warn on destructive commands, lock file scope |
 | `/sync-docs` | Detect stale documentation after code changes |
+| `/docs-update` | Generate, update, and verify project documentation |
+| `/secure-phase [N]` | Per-phase STRIDE security verification |
 
 ### Decision Intelligence — institutional memory
 
@@ -99,6 +101,22 @@ Everything else below is discoverable from `/ls` as you go.
 | `/knowledge-base` | Aggregate all decisions + lessons into searchable KNOWLEDGE.md |
 | `/knowledge-base search [query]` | Search the project knowledge base |
 
+### Recovery — when things go wrong
+
+| Workflow | What it does |
+|----------|-------------|
+| `/forensics [problem]` | Post-mortem investigation for failed/stuck workflows (read-only) |
+| `/undo --last N\|--phase NN\|--plan NN-MM` | Safe git revert — preserves history, checks dependencies |
+
+### Session — capture and report
+
+| Workflow | What it does |
+|----------|-------------|
+| `/note [text]` | Zero-friction idea capture — no questions, just write |
+| `/session-report` | Post-session summary for stakeholder sharing |
+| `/extract-learnings [N]` | Structured learning extraction from phase artifacts |
+| `/milestone-summary [version]` | Comprehensive milestone summary for team onboarding |
+
 ### Milestone Intelligence — reflect and hand off
 
 | Workflow | What it does |

package/learnship/workflows/ideate.md

@@ -4,10 +4,11 @@ description: Codebase-grounded divergent thinking — discover what is worth wor
 
 # Ideate
 
-Codebase-grounded divergent ideation. Scans the actual codebase for hotspots, TODOs, test gaps, and friction points, then generates 15-25 improvement ideas across multiple thinking frames. Adversarial filter eliminates weak ideas. Presents top 5-7 ranked survivors.
+Codebase-grounded divergent ideation with Socratic exploration. Two modes: **scan mode** (default) scans the actual codebase for hotspots and generates ranked improvement ideas. **Explore mode** (`--explore`) uses Socratic questioning to help you think through an idea before committing to artifacts.
 
-**Usage:** `ideate` — open-ended ideation on the current project
+**Usage:** `ideate` — open-ended scan-based ideation on the current project
 **Usage:** `ideate [focus]` — focused ideation on a specific area, concept, or constraint
+**Usage:** `ideate --explore [topic]` — Socratic exploration of an idea with mid-conversation research
 
 **Sequencing:** Run between milestones — after `/complete-milestone`, before `/discuss-milestone` or `/new-milestone`. Requires an existing project with `AGENTS.md` and `.planning/`.
 
@@ -26,7 +27,14 @@ ls AGENTS.md 2>/dev/null && ls .planning/PROJECT.md 2>/dev/null
 
 **If project exists:** Continue.
 
-## Step 2: Scope
+## Step 2: Mode Selection
+
+Parse arguments for `--explore` flag.
+
+**If `--explore` is present:** Jump to Step 2b (Socratic Exploration).
+**Otherwise:** Continue to Step 2a (Scan Mode).
+
+## Step 2a: Scope (Scan Mode)
 
 If a focus argument was provided, use it as the ideation lens.
 If no argument, proceed with open-ended ideation.
@@ -38,7 +46,57 @@ find .planning/ -name "*-ideation-*.md" -mtime -30 2>/dev/null
 
 If recent ideation exists, ask: "Found recent ideation work. Resume from it, or start fresh?"
 
-## Step 3: Codebase Scan
+## Step 2b: Socratic Exploration (only with `--explore`)
+
+If a topic was provided, acknowledge it and begin exploring:
+```
+## Explore: {topic}
+
+Let's think through this together. I'll ask questions to help clarify the idea
+before we commit to any artifacts.
+```
+
+If no topic, ask:
+```
+## Explore
+
+What's on your mind? This could be a feature idea, an architectural question,
+a problem you're trying to solve, or something you're not sure about yet.
+```
+
+**Conversation rules (2-5 exchanges):**
+- Ask **one question at a time** (never a list of questions)
+- Questions should probe: constraints, tradeoffs, users, scope, dependencies, risks
+- Listen for signals: "or" / "versus" / "tradeoff" indicate competing priorities worth exploring
+- Reflect back what you hear to confirm understanding before moving forward
+- **Follow the user's energy** — if they're excited about one aspect, go deeper there
+
+**Mid-conversation research offer (after 2-3 exchanges):**
+
+If the conversation surfaces factual questions, technology comparisons, or unknowns:
+```
+This touches on [specific question]. Want me to do a quick research pass before we continue?
+This would take ~30 seconds and might surface useful context.
+
+[Yes, research this] / [No, let's keep exploring]
+```
+
+If yes and parallelization is enabled, spawn a research agent. Otherwise do an inline research pass. Share findings and continue.
+
+**Crystallize outputs (after 3-6 exchanges):**
+
+When the conversation reaches natural conclusions, propose **up to 4 outputs**:
+
+| Type | Destination | When to suggest |
+|------|-------------|----------------|
+| Note | `.planning/notes/{slug}.md` | Observations, context, decisions worth remembering |
+| Todo | via `/add-todo` | Concrete actionable tasks identified |
+| Decision | via `/decision-log` | Architectural or scope decisions made |
+| Phase proposal | via `/add-phase` | Idea crystallized into a deliverable phase |
+
+Write selected outputs, then jump to Step 7 (Present Results) with a tailored summary.
+
+## Step 3: Codebase Scan (Scan Mode)
 
 Gather grounding context before generating ideas:
 
@@ -175,6 +233,7 @@ git commit -m "docs: ideation — [focus or 'open-ended'] ([N] survivors)"
 Present the "What's next?" options using the platform's blocking question tool:
 
 - **Deep-dive an idea** → expand on the selected idea with more detail
+- **Explore an idea** → run `ideate --explore [idea]` for Socratic deep-dive
 - **Add to current milestone** → feed into `/add-phase`
 - **Start a new milestone** → feed into `/discuss-milestone` then `/new-milestone`
 - **Challenge an idea** → run `/challenge [idea]` to stress-test it

package/learnship/workflows/ls.md

@@ -148,4 +148,4 @@ If the user says yes (or "go", "do it", "run it", "proceed") — immediately inv
 
 - `/ls` is an alias for the status + routing logic in `progress`. Use either.
 - For full auto-pilot (no prompt), use `/next` instead.
-- To see all 49 available commands: `/help`
+- To see all 57 available commands: `/help`

package/learnship/workflows/milestone-summary.md

@@ -0,0 +1,150 @@
+---
+description: Generate a comprehensive milestone summary for team onboarding — a new contributor reads it and understands the project
+---
+
+# Milestone Summary
+
+Generate a comprehensive, human-friendly project summary from completed milestone artifacts. Designed for team onboarding — a new contributor can read the output and understand the entire project.
+
+**Usage:** `milestone-summary` or `milestone-summary [version]`
+
+## Step 1: Resolve Version
+
+If a version was provided, use it. Otherwise:
+1. Check `.planning/STATE.md` for current milestone version
+2. Check `.planning/milestones/` for the latest archived version
+3. If nothing found: "No milestone found. Run `/new-project` or `/new-milestone` first."
+
+## Step 2: Locate Artifacts
+
+**Archived milestone** (`.planning/milestones/v{VERSION}-ROADMAP.md` exists):
+```
+ROADMAP_PATH=".planning/milestones/v${VERSION}-ROADMAP.md"
+REQUIREMENTS_PATH=".planning/milestones/v${VERSION}-REQUIREMENTS.md"
+```
+
+**Current/in-progress milestone** (no archive yet):
+```
+ROADMAP_PATH=".planning/ROADMAP.md"
+REQUIREMENTS_PATH=".planning/REQUIREMENTS.md"
+```
+
+**Always available:**
+```
+PROJECT_PATH=".planning/PROJECT.md"
+STATE_PATH=".planning/STATE.md"
+```
+
+Read all files that exist. Missing files are fine — the summary adapts.
+
+## Step 3: Discover Phase Artifacts
+
+For each phase directory in `.planning/phases/`:
+
+```bash
+ls .planning/phases/*/
+```
+
+For each phase, read:
+- CONTEXT.md — what was decided
+- SUMMARY.md files — what was built
+- VERIFICATION.md — quality status
+- UAT.md — test results
+- LEARNINGS.md — extracted learnings (if exists)
+- SECURITY.md — security status (if exists)
+
+## Step 4: Generate Summary
+
+Write `.planning/MILESTONE-SUMMARY-v{VERSION}.md`:
+
+```markdown
+# Milestone {VERSION}: {Name} — Summary
+
+**Generated:** [date]
+**Status:** [complete / in-progress]
+
+---
+
+## Project Overview
+
+[From PROJECT.md — 3-5 sentences describing what the project is and why it exists]
+
+## Milestone Goal
+
+[From ROADMAP.md — what this milestone set out to deliver]
+
+## What Was Built
+
+### Phase 1: [Name]
+**Goal:** [from ROADMAP.md]
+**Status:** [complete/partial]
+**Key deliverables:**
+- [from SUMMARY.md files — what was actually built]
+
+**Decisions made:**
+- [from CONTEXT.md — key implementation choices]
+
+### Phase 2: [Name]
+[...]
+
+## Architecture
+
+[Synthesized from AGENTS.md project structure, phase summaries, and any ARCHITECTURE.md]
+
+## Key Decisions
+
+[Aggregated from DECISIONS.md and phase CONTEXT.md files — the top 5-10 decisions that shaped the project]
+
+## Lessons Learned
+
+[Aggregated from LEARNINGS.md files if they exist, or synthesized from SUMMARYs]
+
+## Current State
+
+- **Last phase completed:** [N]
+- **Open items:** [from STATE.md blockers]
+- **Test status:** [from UAT/VERIFICATION files]
+- **Security status:** [from SECURITY files if they exist]
+
+## How to Get Started
+
+[Practical instructions: how to clone, install deps, run the dev server, run tests]
+
+---
+
+*Generated by learnship milestone-summary*
+```
+
+## Step 5: Commit and Present
+
+```bash
+git add ".planning/MILESTONE-SUMMARY-v${VERSION}.md"
+git commit -m "docs: milestone ${VERSION} summary"
+```
+
+```
+learnship > MILESTONE SUMMARY COMPLETE
+
+Milestone {VERSION}: {Name}
+Phases covered: [N]
+Decisions documented: [N]
+Lessons captured: [N]
+
+Report: .planning/MILESTONE-SUMMARY-v{VERSION}.md
+
+Share this with new team members or stakeholders for a complete project overview.
+```
+
+---
+
+## Learning Checkpoint
+
+Read `learning_mode` from `.planning/config.json`.
+
+**If `auto`:**
+
+> **Learning moment:** Summarizing a milestone is a natural point for comprehensive reflection:
+>
+> `@agentic-learning reflect` — What was the most significant thing you learned across this entire milestone? What would you do differently if starting over? Milestone-level reflection reveals patterns invisible at the phase level.
+
+**If `manual`:** Add quietly: *"Tip: `@agentic-learning reflect` for milestone-level learning consolidation."*

package/learnship/workflows/new-project.md

@@ -152,7 +152,6 @@ Create `.planning/config.json` with all settings:
   "granularity": "coarse|standard|fine",
   "model_profile": "quality|balanced|budget",
   "learning_mode": "auto|manual",
-  "parallelization": false|true,
   "test_first": false|true,
   "planning": {
     "commit_docs": true|false,
@@ -165,7 +164,30 @@ Create `.planning/config.json` with all settings:
     "verifier": true|false,
     "validation": true|false,
     "review": true|false,
-    "solutions_search": true|false
+    "solutions_search": true|false,
+    "security_enforcement": true|false,
+    "discuss_mode": "discuss",
+    "tdd_mode": false|true
+  },
+  "parallelization": {
+    "enabled": false|true,
+    "plan_level": true,
+    "task_level": false,
+    "max_concurrent_agents": 5,
+    "min_plans_for_parallel": 2
+  },
+  "gates": {
+    "confirm_project": true,
+    "confirm_phases": true,
+    "confirm_roadmap": true,
+    "confirm_plan": true,
+    "execute_next_plan": true,
+    "issues_review": true,
+    "confirm_transition": true
+  },
+  "safety": {
+    "always_confirm_destructive": true,
+    "always_confirm_external_services": true
   },
   "review": {
     "auto_after_verify": false|true
@@ -175,6 +197,9 @@ Create `.planning/config.json` with all settings:
     "conventional_commits": true|false,
     "pr_template": true|false
   },
+  "hooks": {
+    "context_warnings": true
+  },
   "git": {
     "branching_strategy": "none|phase|milestone",
     "phase_branch_template": "phase-{phase}-{slug}",
@@ -183,6 +208,8 @@ Create `.planning/config.json` with all settings:
 }
 ```
 
+**Note:** The `parallelization` field is now an object (not a flat boolean). Legacy flat `"parallelization": true` is still honored for backward compatibility. The `gates` and `safety` sections use sensible defaults — only ask users about them if they specifically want to customize.
+
 If `planning.commit_docs` is false, add `.planning/` to `.gitignore`:
 ```bash
 echo ".planning/" >> .gitignore
@@ -257,7 +284,7 @@ Verify internally: do you have `ANSWER_1`, `ANSWER_2`, `ANSWER_3`, and `ANSWER_4
 - **Write PROJECT.md** → proceed to Step 4
 - **More to cover** → continue asking follow-ups, then re-ask this gate question
 
-Use the questioning techniques from `@./references/questioning.md` to shape the follow-up questions.
+Use the questioning techniques from `@./references/questioning.md` and domain-aware probes from `@./references/domain-probes.md` to shape the follow-up questions. When the user mentions a known domain (auth, real-time, dashboard, API, database, search, file uploads, caching, testing, deployment, AI/ML), use the relevant probes to ask sharper questions.
 
 ## Step 4: Write PROJECT.md
 
@@ -383,19 +410,62 @@ node -e "const fs=require('fs'),path=require('path');const dir='.planning/resear
 
 > 🛑 **If the command prints `RESEARCH INCOMPLETE` or exits with code 1:** Go back and create or fix the missing files. Then run the verification again. You MUST see `RESEARCH VERIFIED OK` before continuing. Do NOT proceed to Step 6 without a passing verification.
 
-Display key findings:
+**Read all 5 research files now** and present their findings in full. Do NOT summarize into 3 bullets. Display this exact structure, populated from the actual file contents:
+
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  learnship ► RESEARCH COMPLETE ✓
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-**Stack:** [key recommendation]
-**Table Stakes:** [top 3 must-have features]
-**Watch Out For:** [top 2 pitfalls]
+## Recommended Stack
+[Full content from STACK.md ## Recommended Stack — include all items, versions, and rationale]
+
+**Alternatives Considered:** [From STACK.md ## Alternatives Considered]
+**What NOT to Use:** [From STACK.md ## What NOT to Use — include reasons]
+
+## Features
+**Table Stakes (must have for v1):**
+[Full list from FEATURES.md ## Table Stakes]
+
+**Differentiators (v2 candidates):**
+[Full list from FEATURES.md ## Differentiators]
+
+**Anti-Features (avoid):**
+[From FEATURES.md ## Anti-Features]
+
+## Architecture
+**Component Boundaries:**
+[From ARCHITECTURE.md ## Component Boundaries]
+
+**Data Flow:**
+[From ARCHITECTURE.md ## Data Flow]
 
-Files: .planning/research/
+**Recommended Build Order:**
+[From ARCHITECTURE.md ## Build Order]
+
+**Integration Points:**
+[From ARCHITECTURE.md ## Integration Points]
+
+## Top Pitfalls to Avoid
+[Full list from PITFALLS.md ## Common Mistakes]
+
+**Warning Signs:**
+[From PITFALLS.md ## Warning Signs]
+
+**Prevention Strategies:**
+[From PITFALLS.md ## Prevention Strategies]
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Files written: .planning/research/STACK.md, FEATURES.md, ARCHITECTURE.md, PITFALLS.md, SUMMARY.md
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 
+Then ask exactly this:
+
+"Research is complete. Does this align with what you had in mind, or are there stack/architecture decisions you want to override before I define requirements? Reply **continue** to proceed, or tell me what to change."
+
+> 🛑 **HARD GATE — Wait for the user's reply before proceeding to Step 6.** Do NOT automatically continue to requirements. Do NOT write REQUIREMENTS.md. The user must explicitly say "continue" or give a change request. If they request changes, update the relevant research file(s) and re-display the affected section, then re-ask this question.
+
 ## Step 6: Define Requirements
 
 > 🛑 STOP. Do not write REQUIREMENTS.md until you have presented feature categories to the user and received their explicit v1 selections. This is a fully interactive step — you must wait for input.

package/learnship/workflows/next.md

@@ -102,4 +102,4 @@ If no — show `/ls` output so the user can choose manually.
 
 - `/next` always confirms before acting (never fully silent).
 - For status-only with manual choice, use `/ls` instead.
-- To see all 49 available commands: `/help`
+- To see all 57 available commands: `/help`

package/learnship/workflows/note.md

@@ -0,0 +1,110 @@
+---
+description: Zero-friction idea capture — one write, one confirmation line, no questions
+---
+
+# Note
+
+Zero-friction idea capture. One write call, one confirmation line. No questions, no prompts. Runs inline — no subagents.
+
+**Usage:**
+- `note [text]` — save a note
+- `note list` — show all notes
+- `note promote [N]` — promote note N to a todo or decision
+
+Notes are different from todos: **notes are observations**, todos are actions.
+
+## Step 1: Parse Subcommand
+
+| Condition | Subcommand |
+|-----------|------------|
+| Arguments are exactly `list` (case-insensitive) | **list** |
+| Arguments are exactly `promote [N]` where N is a number | **promote** |
+| Arguments are empty (no text at all) | **list** |
+| Anything else | **append** (the text IS the note) |
+
+**Critical:** `list` is only a subcommand when it's the ENTIRE argument. `note list of groceries` saves a note with text "list of groceries".
+
+## Step 2: Determine Scope
+
+- **Project scope** (default): `.planning/notes/` — used when `.planning/` exists
+- **Global scope** (fallback): use project scope if `.planning/` exists, otherwise tell user no project is initialized
+
+**Important:** Do NOT create `.planning/` if it doesn't exist. Fall back gracefully.
+
+## Step 3a: Append — Create a Timestamped Note
+
+1. Ensure notes directory exists:
+```bash
+node -e "require('fs').mkdirSync('.planning/notes',{recursive:true})"
+```
+
+2. Generate slug: first ~4 meaningful words, lowercase, hyphen-separated
+3. Generate filename: `{YYYY-MM-DD}-{slug}.md`
+   - If file exists, append `-2`, `-3`, etc.
+
+4. Write the file:
+```markdown
+---
+date: "YYYY-MM-DD HH:mm"
+promoted: false
+---
+
+{note text verbatim}
+```
+
+5. Confirm with exactly one line: `Noted: {note text}`
+
+**Constraints:**
+- **Never modify the note text** — capture verbatim, including typos
+- **Never ask questions** — just write and confirm
+
+## Step 3b: List — Show All Notes
+
+```bash
+ls .planning/notes/*.md 2>/dev/null
+```
+
+For each file, read frontmatter to get `date` and `promoted` status. Sort by date, number sequentially.
+
+Display:
+```
+## Notes
+
+ #  | Date       | Note
+----|------------|------
+ 1  | 2025-01-20 | [first line of note text]
+ 2  | 2025-01-21 | [first line of note text]
+ *3 | 2025-01-22 | [promoted — first line] 
+
+[N] notes ([M] active, [K] promoted)
+```
+
+Promoted notes shown with `*` prefix and dimmed.
+
+## Step 3c: Promote — Convert Note to Action
+
+Read note N from the numbered list. Display the full note text.
+
+Ask: "Promote this note to:"
+- **Todo** — create via `/add-todo [note text]`
+- **Decision** — create via `/decision-log [note text]`
+- **Phase proposal** — create via `/add-phase [note text]`
+- **Keep as note** — cancel
+
+After promoting, update the note's frontmatter: `promoted: true`.
+
+---
+
+## Learning Checkpoint
+
+Read `learning_mode` from `.planning/config.json`.
+
+**If `auto` and this is an append:** No learning prompt for notes — keep it fast.
+
+**If `auto` and this is a promote:**
+
+> **Learning moment:** Promoting a note means the idea had lasting value:
+>
+> `@agentic-learning either-or` — Why did this note survive? What made it worth promoting over others? Log the reasoning.
+
+**If `manual`:** No note for notes — keep it fast.

package/learnship/workflows/pause-work.md

@@ -103,6 +103,8 @@ Current state:
 - Committed as WIP
 
 ▶ To resume: resume-work
+▶ Capture an idea before you go: /note [text]
+▶ Generate a session summary: /session-report
 ```
 
 ---