learnship 2.0.10 → 2.1.0

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
 
@@ -479,6 +506,43 @@ git add .planning/ROADMAP.md .planning/STATE.md .planning/REQUIREMENTS.md && git
 
 > **🔴 MANDATORY — This step must always be completed. Do not skip it, do not defer it, do not move to Step 9 without writing AGENTS.md to the project root. AGENTS.md is the persistent memory file that every future session depends on.**
 
+**Substep 8a-pre — Check for existing context files.** Run this command now:
+
+```bash
+node -e "const fs=require('fs');const files=['AGENTS.md','CLAUDE.md','GEMINI.md','.cursorrules'];const found=files.filter(f=>fs.existsSync(f));if(found.length){console.log('EXISTING: '+found.join(', '));}else{console.log('NONE FOUND');}"
+```
+
+**If the command prints `EXISTING:`** — Ask the user:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ learnship ► EXISTING CONTEXT FILES DETECTED
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+I found existing context file(s): [list from command output]
+
+What would you like to do?
+
+ 1. Replace (recommended for new learnship projects)
+    → Overwrite with learnship's AGENTS.md
+
+ 2. Merge
+    → Keep your existing content, add learnship sections
+
+ 3. Keep separate
+    → Write AGENTS.md alongside your existing file(s)
+
+Reply 1, 2, or 3.
+```
+
+> 🔴 **HARD GATE — Wait for the user's reply. Do NOT auto-decide.**
+
+- **Replace (1):** Continue to substep 8a. The old files will be overwritten.
+- **Merge (2):** Read the existing file(s) first, then in substep 8b, append learnship sections that are missing (Soul, Principles, Request Routing Protocol, etc.) while preserving the user's existing content at the top.
+- **Keep separate (3):** Continue to substep 8a. Write `AGENTS.md` as a new file. Leave existing files untouched.
+
+**If the command prints `NONE FOUND`:** Continue directly to substep 8a.
+
 **Substep 8a — Read the template.** Read `@./templates/agents.md` in full RIGHT NOW before writing anything. This is the canonical template. You need its exact content.
 
 > 🛑 **HARD GATE:** Did you just read `@./templates/agents.md`? If not, go back and read it now. The next substep requires copying sections verbatim from the template. You cannot do that without reading it first.
@@ -518,7 +582,7 @@ git add .planning/ROADMAP.md .planning/STATE.md .planning/REQUIREMENTS.md && git
 > 🔴 **HARD GATE — Run this verification command now. Do not skip it. Do not proceed without running it.**
 
 ```bash
-node -e "const fs=require('fs');if(!fs.existsSync('AGENTS.md')){console.log('AGENTS.md NOT FOUND');process.exit(1);}const f=fs.readFileSync('AGENTS.md','utf8');const required=['Soul','Principles','Request Routing Protocol','Platform Context','Current Phase','Project Structure','Tech Stack','Skills','Regressions'];const missing=required.filter(s=>!f.includes('## '+s));if(missing.length){console.log('AGENTS.md INCOMPLETE — missing sections:\\n'+missing.map(s=>'  ## '+s).join('\\n'));process.exit(1);}const verbatim=['pair programmer','Direct, no fluff','Have opinions','Friction Is Signal','Minimal Upstream Fix','decision tree'];const missingV=verbatim.filter(s=>!f.includes(s));if(missingV.length){console.log('AGENTS.md TEMPLATE VIOLATION — these verbatim phrases are missing (did you rewrite instead of copy?):\\n'+missingV.join('\\n'));process.exit(1);}console.log('AGENTS.md VERIFIED OK — all '+required.length+' sections present, verbatim content intact');"
+node -e "const fs=require('fs');if(!fs.existsSync('AGENTS.md')){console.log('AGENTS.md NOT FOUND');process.exit(1);}const f=fs.readFileSync('AGENTS.md','utf8');const required=['Soul','Principles','Request Routing Protocol','Platform Context','Current Phase','Project Structure','Tech Stack','Skills','Regressions'];const missing=required.filter(s=>!f.includes('## '+s));if(missing.length){console.log('AGENTS.md INCOMPLETE — missing sections:\\n'+missing.map(s=>'  ## '+s).join('\\n'));process.exit(1);}const verbatim=['pair programmer','Direct, no fluff','Have opinions','Friction Is Signal','Surgical Change','Nothing Extra','Understand First','decision tree'];const missingV=verbatim.filter(s=>!f.includes(s));if(missingV.length){console.log('AGENTS.md TEMPLATE VIOLATION — these verbatim phrases are missing (did you rewrite instead of copy?):\\n'+missingV.join('\\n'));process.exit(1);}console.log('AGENTS.md VERIFIED OK — all '+required.length+' sections present, verbatim content intact');"
 ```
 
 > 🛑 **If the command prints `INCOMPLETE` or `TEMPLATE VIOLATION` or exits with code 1:** The AGENTS.md is broken. Re-read `@./templates/agents.md` and fix the missing sections or restore the verbatim content. Run the verification again. You MUST see `AGENTS.md VERIFIED OK` before continuing to Step 9.

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
 ```
 
 ---

package/learnship/workflows/plan-phase.md

@@ -8,9 +8,15 @@ Create executable plans for a roadmap phase. Default flow: Research → Plan →
 
 On platforms with subagent support (Claude Code, OpenCode, Codex), each stage spawns a dedicated specialist agent with its own full context budget. On all other platforms, all stages run sequentially in the same context.
 
-**Usage:** `plan-phase [N]` — optionally add `--skip-research` or `--skip-verify`
+**Usage:** `plan-phase [N]` — optionally add `--skip-research`, `--skip-verify`, or `--research` (force re-research)
 
-> **Platform note:** Read `parallelization` from `.planning/config.json`. When `true`, researcher/planner/checker each run as a spawned subagent. When `false` (default), all stages run inline using agent persona files.
+**Flags:**
+- `--skip-research` — skip the research stage even if enabled in config
+- `--skip-verify` — skip the plan verification stage
+- `--research` — force re-research even if RESEARCH.md already exists
+- `--gaps` — plan only for gaps found during verification
+
+> **Platform note:** Read `parallelization` from `.planning/config.json`. When enabled, researcher/planner/checker each run as a spawned subagent. When `false` (default), all stages run inline using agent persona files.
 
 ## Step 1: Initialize
 
@@ -23,6 +29,15 @@ Read config:
 cat .planning/config.json
 ```
 
+Read TDD mode:
+```bash
+TDD_MODE=$(node -e "try{const c=JSON.parse(require('fs').readFileSync('.planning/config.json','utf8'));process.stdout.write(String((c.workflow||{}).tdd_mode||false));}catch(e){process.stdout.write('false');}" 2>/dev/null || echo 'false')
+```
+
+When `TDD_MODE` is `true`, instruct the planner to apply `type: tdd` to eligible tasks — the executor will use the red-green-refactor cycle for those tasks.
+
+**Context window scaling:** Check `context_window` in config (default: 200000). At >= 500000, include the 3 most recent prior phase CONTEXT.md and SUMMARY.md files in the planner's context. At < 500000, include only frontmatter from prior phases.
+
 Create the phase directory if it doesn't exist:
 ```bash
 node -e "require('fs').mkdirSync('.planning/phases/[padded_phase]-[phase_slug]',{recursive:true})"

package/learnship/workflows/quick.md

@@ -10,9 +10,11 @@ Execute small, ad-hoc tasks with full agentic guarantees: atomic commits, STATE.
 
 **Flags:**
 - `--discuss` — lightweight discussion phase before planning (surfaces gray areas)
-- `--full` — adds plan-checking and post-execution verification
+- `--research` — spawns a focused research agent before planning (investigates approaches, libraries, pitfalls)
+- `--validate` — enables plan-checking (max 2 iterations) and post-execution verification
+- `--full` — enables all of the above: discussion + research + plan-checking + verification
 
-**Composable:** `quick --discuss --full "add dark mode toggle"` gives discussion + plan-checking + verification.
+**Composable:** Granular flags compose freely. `quick --discuss --research --validate` = `--full`.
 
 ## Step 1: Get Task Description
 
@@ -113,6 +115,23 @@ Write `CONTEXT.md` to the task directory:
 </specifics>
 ```
 
+## Step 3b: Research Phase (only with `--research` or `--full`)
+
+**Skip if neither `--research` nor `--full` flag is present.**
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ learnship ► RESEARCHING: [DESCRIPTION]
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Using `@./agents/researcher.md` as your research persona, do a focused research pass on the task:
+- What libraries or approaches are relevant?
+- What pitfalls should the implementation avoid?
+- Are there existing patterns in the codebase to follow?
+
+Write a brief `${NEXT_NUM}-RESEARCH.md` (max 50 lines) to the task directory. This feeds into the planner.
+
 ## Step 4: Create Plan
 
 Using `@./agents/planner.md` as your planning persona, read:
@@ -128,16 +147,17 @@ Each task needs:
 - `<verify>` — how to confirm it worked
 - `<done>` — observable completion criteria
 
-If `--full`: also include `must_haves` in plan frontmatter (truths, artifacts, key_links).
+If `--validate` or `--full`: also include `must_haves` in plan frontmatter (truths, artifacts, key_links).
+If `--research` or `--full`: also read the RESEARCH.md from step 3b.
 
 Verify plan was created (substitute actual NEXT_NUM and SLUG values):
 ```bash
 node -e "const fs=require('fs'); console.log(fs.existsSync('.planning/quick/NEXT_NUM-SLUG/NEXT_NUM-PLAN.md') ? 'OK' : 'MISSING')"
 ```
 
-## Step 5: Plan Check (only with `--full`)
+## Step 5: Plan Check (only with `--validate` or `--full`)
 
-**Skip if `--full` flag is not present.**
+**Skip if neither `--validate` nor `--full` flag is present.**
 
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -187,9 +207,9 @@ After all tasks complete, write `${NEXT_NUM}-SUMMARY.md`:
 [commit hash]
 ```
 
-## Step 7: Verify Results (only with `--full`)
+## Step 7: Verify Results (only with `--validate` or `--full`)
 
-**Skip if `--full` flag is not present.**
+**Skip if neither `--validate` nor `--full` flag is present.**
 
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -235,7 +255,7 @@ Display completion:
 Quick Task [NEXT_NUM]: [DESCRIPTION]
 
 Summary: .planning/quick/[NEXT_NUM]-[SLUG]/[NEXT_NUM]-SUMMARY.md
-[If --full: Verification: [status]]
+[If --validate/--full: Verification: [status]]
 Commit: [hash]
 
 💡 Solved something notable? `/compound` — capture the solution while context is fresh

package/learnship/workflows/review.md

@@ -198,6 +198,7 @@ git commit -m "fix([scope]): [description from finding]"
 
 ```
 ▶ Next steps:
+- /secure-phase [N] — STRIDE security verification before shipping
 - /ship — run the ship pipeline (test → lint → commit → push → PR)
 - /compound — capture any notable patterns from the review
 ```

package/learnship/workflows/secure-phase.md

@@ -0,0 +1,147 @@
+---
+description: Per-phase security verification — STRIDE threat register, mitigation check, SECURITY.md generation
+---
+
+# Secure Phase
+
+Verify threat mitigations for a completed phase. Reads PLAN.md threat data if present, analyzes the codebase for security concerns, classifies threats, and generates a per-phase SECURITY.md using `@./templates/security.md`.
+
+**Usage:** `secure-phase [N]`
+
+**Sequencing:** Run after `execute-phase [N]` and before or alongside `verify-work [N]`.
+
+## Step 1: Initialize
+
+Read `.planning/config.json` for `workflow.security_enforcement` (defaults to `true`).
+
+If `security_enforcement` is `false`: exit with "Security enforcement disabled. Enable via `/settings`."
+
+Find the phase directory and verify it has been executed (SUMMARY.md exists):
+
+```bash
+ls ".planning/phases/[padded_phase]-[phase_slug]/"*-SUMMARY.md 2>/dev/null
+```
+
+If no SUMMARY.md: "Phase [N] not executed yet. Run `execute-phase [N]` first."
+
+Display:
+```
+learnship > SECURE PHASE [N]: [name]
+```
+
+## Step 2: Discovery
+
+### 2a. Read Phase Artifacts
+
+Read all PLAN.md files for this phase. Look for `<threat_model>` blocks or security-related task descriptions (auth, encryption, input validation, access control, etc.).
+
+### 2b. Read Summary Threat Flags
+
+Read SUMMARY.md files. Look for any security-related notes, deviations, or flags.
+
+### 2c. Analyze Codebase
+
+Scan files modified in this phase for common security patterns:
+
+```bash
+git log --name-only --format="" --grep="([padded_phase]" | sort -u
+```
+
+For each file, check for:
+- Input validation (or lack thereof)
+- Authentication/authorization checks
+- Sensitive data handling (secrets, PII, tokens)
+- SQL/command injection vectors
+- Hardcoded credentials
+- Insecure defaults
+
+## Step 3: Build Threat Register
+
+For each identified concern, create a threat entry:
+
+| Field | Value |
+|-------|-------|
+| Threat ID | T-{phase}-{NN} |
+| Category | STRIDE category (Spoofing/Tampering/Repudiation/Info Disclosure/DoS/Elevation) |
+| Component | Which file or module |
+| Disposition | mitigate / accept / transfer |
+| Status | open / closed |
+
+Classify each threat:
+- **CLOSED** — mitigation found in code OR accepted risk documented OR transferred to third-party
+- **OPEN** — none of the above
+
+## Step 4: Present Threat Plan
+
+If all threats are CLOSED: skip to Step 6.
+
+If open threats exist, present them:
+
+```
+Open Threats ([N]):
+
+| ID | Category | Component | Description |
+|----|----------|-----------|-------------|
+| T-03-01 | Info Disclosure | api/auth.ts | JWT secret in environment without validation |
+
+Options:
+1. Verify all open threats — investigate and resolve
+2. Accept all open — document as accepted risks
+3. Review individually — decide per threat
+```
+
+Wait for user response.
+
+## Step 5: Resolve Open Threats
+
+For option 1 (verify all): Using `@./agents/verifier.md`, check each open threat against the codebase. Update status based on findings.
+
+For option 2 (accept all): Add each to the Accepted Risks Log with user's rationale.
+
+For option 3 (individual): Present each threat one at a time with options: Verify / Accept / Skip.
+
+## Step 6: Write SECURITY.md
+
+Write `.planning/phases/[padded_phase]-[phase_slug]/[padded_phase]-SECURITY.md` using `@./templates/security.md`:
+
+- Fill in trust boundaries from the analysis
+- Fill in the complete threat register
+- Fill in accepted risks log
+- Fill in audit trail
+- Update frontmatter: `threats_open` count, `status` (draft/verified)
+
+If `threats_open` is 0: set `status: verified`.
+
+Commit:
+```bash
+git add ".planning/phases/[padded_phase]-[phase_slug]/[padded_phase]-SECURITY.md"
+git commit -m "security([padded_phase]): phase security verification"
+```
+
+## Step 7: Report
+
+```
+learnship > SECURE PHASE [N] COMPLETE
+
+Threats found: [total]
+Closed: [N]  |  Accepted: [N]  |  Open: [N]
+
+Status: [verified / needs attention]
+Report: [path to SECURITY.md]
+```
+
+If open threats remain: warn that the phase has unresolved security concerns.
+
+---
+
+## Learning Checkpoint
+
+Read `learning_mode` from `.planning/config.json`.
+
+**If `auto`:**
+
+> **Learning moment:** Security verification surfaces patterns worth internalizing:
+>
+> `@agentic-learning learn [security topic]` — Active retrieval on the security concepts encountered. STRIDE categories, common vulnerability patterns, and mitigation strategies build lasting defensive instincts.
+
+**If `manual`:** Add quietly: *"Tip: `@agentic-learning learn [topic]` to deepen security knowledge from this verification."*

package/learnship/workflows/session-report.md

@@ -0,0 +1,133 @@
+---
+description: Generate a post-session summary with work performed, outcomes, and estimated resource usage
+---
+
+# Session Report
+
+Generate a post-session summary capturing work performed, outcomes achieved, and git activity. Writes a report to `.planning/reports/` for human review and stakeholder sharing.
+
+**Usage:** `session-report`
+
+## Step 1: Gather Session Data
+
+Collect data from available sources:
+
+### 1a. Git Activity
+
+```bash
+git log --oneline --since="24 hours ago" --no-merges 2>/dev/null || echo "No recent commits"
+
+git diff --stat HEAD~10 HEAD 2>/dev/null | tail -1 || echo "No diff available"
+
+git log --format="%ai" --since="24 hours ago" 2>/dev/null | head -1
+git log --format="%ai" --since="24 hours ago" 2>/dev/null | tail -1
+```
+
+### 1b. Planning State
+
+Read `.planning/STATE.md` to get:
+- Current milestone and phase
+- Progress percentage
+- Active blockers
+- Recent decisions
+
+Read `.planning/ROADMAP.md` to get milestone name and phase goals.
+
+### 1c. Phase Artifacts
+
+```bash
+find .planning/phases -name "*-SUMMARY.md" -newer .planning/STATE.md 2>/dev/null
+find .planning/phases -name "*-UAT.md" -newer .planning/STATE.md 2>/dev/null
+find .planning/phases -name "*-VERIFICATION.md" -newer .planning/STATE.md 2>/dev/null
+```
+
+### 1d. Previous Reports
+
+```bash
+ls -la .planning/reports/SESSION_REPORT*.md 2>/dev/null || echo "No previous reports"
+```
+
+## Step 2: Generate Report
+
+```bash
+node -e "require('fs').mkdirSync('.planning/reports',{recursive:true})"
+```
+
+Write `.planning/reports/SESSION-[YYYYMMDD].md`:
+
+```markdown
+# Session Report
+
+**Generated:** [timestamp]
+**Project:** [from PROJECT.md title or directory name]
+**Milestone:** [N] — [milestone name]
+
+---
+
+## Session Summary
+
+**Duration:** [estimated from first to last commit timestamp, or "Single session"]
+**Phase Progress:** [from STATE.md]
+**Plans Executed:** [count of summaries written this session]
+**Commits Made:** [count from git log]
+
+## Work Performed
+
+| Phase | Plans | Status | Key Deliverables |
+|-------|-------|--------|-----------------|
+| [N]   | [IDs] | [complete/partial] | [what was built] |
+
+## Decisions Made
+
+[Decisions captured during this session, from STATE.md or DECISIONS.md changes]
+
+## Issues Encountered
+
+[Any blockers, bugs, or deviations noted in SUMMARYs]
+
+## Files Changed
+
+[Top 10 most-changed files from git diff --stat]
+
+---
+
+## Next Steps
+
+[What STATE.md says is next]
+
+---
+
+*Generated by learnship session-report*
+```
+
+## Step 3: Commit and Present
+
+```bash
+git add .planning/reports/
+git commit -m "docs: session report [date]"
+```
+
+```
+learnship > SESSION REPORT COMPLETE
+
+Report: .planning/reports/SESSION-[date].md
+Duration: [estimate]
+Commits: [N]
+Plans completed: [M]
+
+Share this report with stakeholders or use it for team standups.
+```
+
+---
+
+## Learning Checkpoint
+
+Read `learning_mode` from `.planning/config.json`.
+
+**If `auto`:**
+
+> **Learning moment:** End of session is a natural reflection point:
+>
+> `@agentic-learning reflect` — What was the most valuable thing accomplished this session? What would you do differently? Structured reflection at session boundaries builds compounding insight.
+
+**If `manual`:** Add quietly: *"Tip: `@agentic-learning reflect` to consolidate lessons from this session."*