learnship 1.9.22 → 2.0.0

package/learnship/workflows/guard.md

@@ -0,0 +1,164 @@
+---
+description: Safety mode — warn on destructive commands, lock file scope
+---
+
+# Guard
+
+Safety mode for sensitive phases. Warns before destructive commands, locks file scope to prevent accidental changes outside the working area, and persists guard state across sessions.
+
+**Usage:** `guard [scope]` — activate guard mode for a specific scope (directory, file pattern, or phase)
+**Usage:** `guard off` — deactivate guard mode
+
+## Step 1: Parse Arguments
+
+If argument is `off` → deactivate guard mode (Step 6).
+
+Otherwise, interpret the scope:
+- **Directory path** (e.g., `src/auth/`) → guard all files under that path
+- **File pattern** (e.g., `*.migration`) → guard files matching the pattern
+- **Phase number** (e.g., `3`) → guard files modified by that phase's plans
+- **No argument** → guard the current phase's file scope
+
+## Step 2: Determine File Scope
+
+**If a directory or pattern was provided:** Use it directly.
+
+**If a phase number was provided:**
+```bash
+# Extract files_modified from all plans in the phase
+grep -h "files_modified" .planning/phases/[padded_phase]-*/*-PLAN.md -A 50 2>/dev/null | grep "^ *-" | sed 's/^ *- //'
+```
+
+**If no argument — auto-detect from current phase:**
+```bash
+# Read current phase from STATE.md
+cat .planning/STATE.md 2>/dev/null | grep -i "phase"
+
+# Get files from current phase plans
+grep -rh "files_modified" .planning/phases/$(ls .planning/phases/ | sort | tail -1)/*-PLAN.md -A 50 2>/dev/null | grep "^ *-" | sed 's/^ *- //'
+```
+
+**Brownfield enhancement:** If `.planning/codebase/CONCERNS.md` exists, read it and auto-suggest guard scope for files flagged as high-risk:
+```bash
+cat .planning/codebase/CONCERNS.md 2>/dev/null | grep -i "risk\|sensitive\|critical\|production"
+```
+
+## Step 3: Activate Guard
+
+Write guard state to `.planning/guard-state.md`:
+
+```markdown
+---
+active: true
+activated: [ISO timestamp]
+scope: [description of what's guarded]
+---
+
+# Guard Mode Active
+
+## Protected Scope
+
+[list of files/directories/patterns being guarded]
+
+## Destructive Command Warnings
+
+The following commands will trigger a warning before execution:
+- `rm`, `rm -rf`, `git reset --hard`, `git clean -fd`
+- `DROP TABLE`, `DELETE FROM`, `TRUNCATE`
+- `git push --force`, `git rebase` (on shared branches)
+- Any write to files outside the guarded scope
+
+## Session Log
+
+- [timestamp]: Guard activated — scope: [scope description]
+```
+
+```bash
+git add .planning/guard-state.md
+git commit -m "docs: activate guard mode — scope: [description]"
+```
+
+Display:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ learnship ► GUARD MODE ACTIVE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Protected scope:
+[list of guarded files/dirs]
+
+Warnings will trigger for:
+- Destructive commands (rm -rf, git reset --hard, DROP TABLE)
+- Writes outside guarded scope
+- Force pushes and rebases on shared branches
+
+▶ Run: guard off  — to deactivate
+```
+
+## Step 4: Guard Behavior (While Active)
+
+When guard mode is active (`.planning/guard-state.md` exists with `active: true`):
+
+**Before any file write:** Check if the target file is within the guarded scope.
+- **Inside scope** → proceed normally
+- **Outside scope** → warn: "⚠ Guard: This file is outside the guarded scope ([scope]). Proceed anyway?"
+
+**Before destructive commands:** Always warn:
+```
+⚠ Guard: Destructive command detected: [command]
+This will [description of what it does].
+Proceed? (yes/no)
+```
+
+**Log all guard events** to the Session Log in `guard-state.md`.
+
+## Step 5: Persistent State
+
+Guard mode persists across sessions via `.planning/guard-state.md`. Any workflow that reads `.planning/config.json` should also check for active guard state:
+
+```bash
+# Check if guard is active
+grep -q "active: true" .planning/guard-state.md 2>/dev/null && echo "GUARD_ACTIVE"
+```
+
+## Step 6: Deactivate
+
+When `guard off` is invoked:
+
+Update `.planning/guard-state.md`:
+```markdown
+---
+active: false
+activated: [original timestamp]
+deactivated: [ISO timestamp]
+scope: [original scope]
+---
+```
+
+```bash
+git add .planning/guard-state.md
+git commit -m "docs: deactivate guard mode"
+```
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ learnship ► GUARD MODE DEACTIVATED
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Guard was active for: [duration]
+Events logged: [N]
+```
+
+---
+
+## Learning Checkpoint
+
+Read `learning_mode` from `.planning/config.json`.
+
+**If `auto`:** After activating guard, offer:
+
+> 💡 **Learning moment:** Safety modes reflect risk awareness:
+>
+> `@agentic-learning either-or` — When should you use guard mode vs just being careful? Log the decision criteria for future reference.
+
+**If `manual`:** Add quietly: *"Tip: `@agentic-learning either-or` to log when guard mode is worth the overhead."*

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 42 commands |
+| `/help` | This screen — see all 49 commands |
 
 Everything else below is discoverable from `/ls` as you go.
 
@@ -79,6 +79,18 @@ Everything else below is discoverable from `/ls` as you go.
 | `/check-todos` | Review and act on captured todos |
 | `/add-tests [N]` | Generate unit and E2E tests post-execution |
 
+### Compounding & Quality — capture, review, ship
+
+| Workflow | What it does |
+|----------|-------------|
+| `/compound` | Capture a solution while context is fresh → `.planning/solutions/` |
+| `/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 |
+| `/guard [scope\|off]` | Safety mode — warn on destructive commands, lock file scope |
+| `/sync-docs` | Detect stale documentation after code changes |
+
 ### Decision Intelligence — institutional memory
 
 | Workflow | What it does |
@@ -119,7 +131,7 @@ Everything else below is discoverable from `/ls` as you go.
 
 **Standard phase loop:**
 ```
-/discuss-phase N → /plan-phase N → /execute-phase N → /verify-work N
+/discuss-phase N → /plan-phase N → /execute-phase N → /verify-work N → /review → /ship → /compound
 ```
 
 **Quick fix:**

package/learnship/workflows/ideate.md

@@ -0,0 +1,182 @@
+---
+description: Codebase-grounded divergent thinking — discover what is worth working on
+---
+
+# 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.
+
+**Usage:** `ideate` — open-ended ideation on the current project
+**Usage:** `ideate [focus]` — focused ideation on a specific area, concept, or constraint
+
+**Sequencing:** Run before `/new-project`, `/challenge`, or `/discuss-milestone` to discover what's worth building.
+
+## Step 1: Scope
+
+If a focus argument was provided, use it as the ideation lens.
+If no argument, proceed with open-ended ideation.
+
+Check for recent ideation work:
+```bash
+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 2: Codebase Scan
+
+Gather grounding context before generating ideas:
+
+```bash
+# Project shape
+cat AGENTS.md 2>/dev/null || cat CLAUDE.md 2>/dev/null || cat README.md 2>/dev/null
+
+# TODOs and FIXMEs in codebase
+grep -rn "TODO\|FIXME\|HACK\|XXX" --include="*.ts" --include="*.js" --include="*.py" --include="*.rb" --include="*.go" --include="*.rs" . 2>/dev/null | head -30
+
+# Test coverage gaps (files without corresponding test files)
+find . -name "*.ts" -not -name "*.test.*" -not -name "*.spec.*" -not -path "*/node_modules/*" -not -path "*/.git/*" 2>/dev/null | head -20
+
+# Recent git activity (hotspots)
+git log --oneline -20 --format="%s" 2>/dev/null
+git log --since="30 days ago" --format="" --name-only 2>/dev/null | sort | uniq -c | sort -rn | head -15
+```
+
+**Brownfield enhancement:** If `.planning/codebase/` exists, also read:
+```bash
+cat .planning/codebase/ARCHITECTURE.md 2>/dev/null
+cat .planning/codebase/CONCERNS.md 2>/dev/null
+cat .planning/codebase/TESTING.md 2>/dev/null
+```
+
+Read compounded solutions and knowledge:
+```bash
+ls .planning/solutions/ 2>/dev/null
+cat .planning/KNOWLEDGE.md 2>/dev/null
+```
+
+## Step 3: Divergent Ideation
+
+Read `parallelization` from `.planning/config.json` (defaults to `false`).
+
+**If `parallelization` is `true` (subagent mode):**
+
+Spawn 3-4 ideation agents in parallel, each with a different thinking frame:
+
+```
+Task(
+  subagent_type="learnship-ideation-agent",
+  prompt="
+    <objective>
+    Generate 6-8 improvement ideas for this project using the [FRAME] lens.
+    Ground every idea in the codebase scan results — no abstract advice.
+    Return: title, summary, why_it_matters, evidence (specific files/patterns)
+
+    Frame: [one of the frames below]
+    Focus: [focus hint if provided]
+    </objective>
+
+    <context>
+    [codebase scan results]
+    [solutions and knowledge if available]
+    </context>
+  "
+)
+```
+
+**Thinking frames:**
+1. **User/operator pain** — friction, confusion, error-prone workflows
+2. **Inversion/removal** — what could be automated, eliminated, or simplified
+3. **Assumption-breaking** — what if the current approach is wrong?
+4. **Leverage/compounding** — what would make all future work easier?
+
+**If `parallelization` is `false` (sequential mode):**
+
+Using `@./agents/ideation-agent.md`, generate 15-25 ideas across all four frames sequentially.
+
+## Step 4: Deduplicate & Filter
+
+Merge ideas from all frames:
+
+1. **Deduplicate** — merge ideas that describe the same improvement from different angles
+2. **Adversarial filter** — for each idea, ask:
+   - Is this grounded in the actual codebase, or generic advice?
+   - Is this actionable within a reasonable scope?
+   - Does the evidence support the claimed impact?
+   - Would a senior engineer roll their eyes at this suggestion?
+3. **Eliminate** weak ideas with explicit reasons
+
+## Step 5: Rank Survivors
+
+Rank the surviving ideas (target: 5-7) by:
+
+| Factor | Weight |
+|--------|--------|
+| **Impact** — how much does this improve the project? | High |
+| **Evidence** — how grounded is the idea in codebase data? | High |
+| **Feasibility** — can this be done in a reasonable scope? | Medium |
+| **Compounding** — does this make future work easier? | Medium |
+
+## Step 6: Present Results
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ learnship ► IDEATION COMPLETE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Focus: [focus or "open-ended"]
+Scanned: [N] files, [M] TODOs, [K] hotspots
+Generated: [total] ideas → [filtered] eliminated → [survivors] survivors
+
+## Top Ideas
+
+### 1. [Title]
+**Impact:** high | medium | low
+**Evidence:** [specific files/patterns from codebase]
+**Summary:** [2-3 sentences]
+**Scope:** [estimated effort — small/medium/large]
+
+### 2. [Title]
+[...]
+
+---
+
+Eliminated ideas (with reasons):
+- [idea]: [why eliminated]
+[...]
+```
+
+Save the ideation artifact:
+```bash
+DATE=$(date +%Y%m%d)
+node -e "require('fs').mkdirSync('.planning',{recursive:true})"
+# Write ideation results to .planning/[DATE]-ideation-[slug].md
+git add .planning/[DATE]-ideation-[slug].md
+git commit -m "docs: ideation — [focus or 'open-ended'] ([N] survivors)"
+```
+
+## Step 7: Route to Action
+
+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
+- **Start a new project** → feed selected idea into `/new-project`
+- **Add to current milestone** → feed into `/add-phase`
+- **Challenge an idea** → run `/challenge [idea]` to stress-test it
+- **Save and return later** → already saved to `.planning/`
+
+---
+
+## Learning Checkpoint
+
+Read `learning_mode` from `.planning/config.json`.
+
+**If `auto`:** After ideation, offer:
+
+> 💡 **Learning moment:** Ideation is where divergent thinking gets practiced:
+>
+> `@agentic-learning brainstorm [top idea]` — Take the #1 idea and brainstorm collaboratively. Explore variations, edge cases, and alternative approaches.
+>
+> `@agentic-learning either-or [idea A] vs [idea B]` — Compare two competing ideas. Which is worth pursuing? Log the reasoning.
+
+**If `manual`:** Add quietly: *"Tip: `@agentic-learning brainstorm [idea]` to explore the top idea collaboratively."*

package/learnship/workflows/knowledge-base.md

@@ -32,6 +32,9 @@ find .planning/ -name "*-RESEARCH.md" | sort
 
 # AGENTS.md regressions
 grep -A 5 "### 20" AGENTS.md 2>/dev/null
+
+# Compounded solutions
+find .planning/solutions/ -name "*.md" -type f 2>/dev/null | sort
 ```
 
 ## Step 3: Extract Knowledge
@@ -53,6 +56,11 @@ From each source, extract structured knowledge items:
 - "Don't Hand-Roll" entries → Knowledge item: `library`
 - "Common Pitfalls" entries → Knowledge item: `pitfall`
 
+**From compounded solutions (`.planning/solutions/`):**
+- Bug track solutions → Knowledge item: `lesson` (root cause + prevention)
+- Knowledge track solutions → Knowledge item: `pattern` or `anti-pattern`
+- Read YAML frontmatter for classification (module, problem_type, severity, tags)
+
 Deduplicate: if the same concept appears multiple times, merge into one entry with multiple `sources`.
 
 ## Step 4: Write / Update KNOWLEDGE.md

package/learnship/workflows/ls.md

@@ -119,10 +119,14 @@ Determine the next action (same logic as `progress`):
 5. **Plans = 0, no CONTEXT.md** → needs discussion
    - Next: `discuss-phase [X]`
 
-6. **All plans have summaries, more phases remain** → move forward
+6. **All plans have summaries, UAT not done** → verify before moving on
+   - Next: `verify-work [X]`
+
+7. **All plans have summaries, UAT passed, more phases remain** → move forward
    - Next: `discuss-phase [X+1]`
+   - Suggest: `/review` → `/ship` → `/compound` before starting next phase
 
-7. **All phases done** → ready to ship
+8. **All phases done** → ready to ship
    - Next: `audit-milestone`
 
 Display clearly, then **ask**:
@@ -142,4 +146,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 40+ available commands: `/help`
+- To see all 49 available commands: `/help`

package/learnship/workflows/milestone-retrospective.md

@@ -67,6 +67,51 @@ Ask each question and wait for a real answer before moving to the next. These ar
 **Question 5: What should carry forward?**
 "Any patterns, decisions, or lessons from this milestone that should explicitly inform the next one? What goes into the decision register?"
 
+## Step 2b: Quantitative Summary
+
+Gather data-driven metrics for this milestone:
+
+```bash
+# Commits per phase
+for dir in .planning/phases/*/; do
+  PHASE=$(basename "$dir")
+  COUNT=$(git log --oneline --all -- "$dir" 2>/dev/null | wc -l | tr -d ' ')
+  echo "$PHASE: $COUNT commits"
+done
+
+# Total LOC changed
+git log --oneline --format="" --numstat $(git log --all --oneline .planning/ 2>/dev/null | tail -1 | cut -d' ' -f1)..HEAD 2>/dev/null | awk '{add+=$1; del+=$2} END {print "+" add " -" del " lines"}'
+
+# Test file ratio
+TOTAL_FILES=$(find . -name "*.ts" -o -name "*.js" -o -name "*.py" -o -name "*.rb" -o -name "*.go" 2>/dev/null | grep -v node_modules | grep -v .git | wc -l | tr -d ' ')
+TEST_FILES=$(find . -name "*.test.*" -o -name "*.spec.*" -o -name "*_test.*" 2>/dev/null | grep -v node_modules | grep -v .git | wc -l | tr -d ' ')
+echo "Test ratio: $TEST_FILES test files / $TOTAL_FILES total files"
+
+# Debug sessions count
+DEBUG_COUNT=$(ls .planning/debug/resolved/ 2>/dev/null | wc -l | tr -d ' ')
+echo "Debug sessions resolved: $DEBUG_COUNT"
+
+# Velocity (days from first to last commit in milestone)
+FIRST_DATE=$(git log --reverse --format="%ai" .planning/ 2>/dev/null | head -1 | cut -d' ' -f1)
+LAST_DATE=$(git log --format="%ai" .planning/ 2>/dev/null | head -1 | cut -d' ' -f1)
+echo "Duration: $FIRST_DATE to $LAST_DATE"
+```
+
+Present the quantitative summary before the qualitative questions:
+
+```
+## Quantitative Summary
+
+| Metric | Value |
+|--------|-------|
+| Phases completed | [N] |
+| Total commits | [N] |
+| LOC changed | +[N] / -[N] |
+| Test file ratio | [N]% |
+| Debug sessions | [N] |
+| Duration | [N] days |
+```
+
 ## Step 3: Synthesize Themes
 
 After all five answers, synthesize the key themes:

package/learnship/workflows/new-project.md

@@ -21,7 +21,7 @@ Initialize a new project with full context gathering, optional research, require
 
 ## Step 1: Setup
 
-You are running on **Windsurf**. Platform config directory: `.windsurf/`
+<!-- LEARNSHIP_PLATFORM_LABEL -->
 
 > **Routing protocol suspended.** While this workflow is running, every user message is an answer to a workflow question — not a task to route. Do NOT apply the request routing protocol until `/new-project` is fully complete and `.planning/PROJECT.md` exists.
 
@@ -59,7 +59,7 @@ git init
 
 Add the platform config directory to `.gitignore` so AI platform files are not tracked in the project repo:
 ```bash
-grep -q '.windsurf/' .gitignore 2>/dev/null || echo '.windsurf/' >> .gitignore
+<!-- LEARNSHIP_GITIGNORE_CMD -->
 ```
 
 Create the planning directory:
@@ -108,7 +108,7 @@ Ask: "Which workflow agents should be enabled?"
 
 **Group D — Parallel execution:**
 
-Windsurf does not support real subagents. Parallelization is automatically set to `false`.
+<!-- LEARNSHIP_PARALLEL_BLOCK -->
 
 Ask: "Commit planning docs to git?"
 - **Yes** (recommended) — Planning docs tracked in version control
@@ -379,6 +379,8 @@ Last updated: [today's date]
 git add AGENTS.md && git commit -m "docs: add AGENTS.md with project context"
 ```
 
+<!-- LEARNSHIP_AGENTSMD_PLATFORM_NOTE -->
+
 ## Step 9: Done
 
 ```

package/learnship/workflows/next.md

@@ -67,7 +67,8 @@ Evaluate in order:
 | Plans exist, summaries < plans | `execute-phase [X]` |
 | Plans = 0, CONTEXT.md exists | `plan-phase [X]` |
 | Plans = 0, no CONTEXT.md | `discuss-phase [X]` |
-| All summaries complete, more phases remain | `discuss-phase [X+1]` |
+| All summaries complete, UAT not done | `verify-work [X]` |
+| All summaries complete, UAT passed, more phases remain | `discuss-phase [X+1]` |
 | All phases complete | `audit-milestone` |
 
 ---
@@ -97,4 +98,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 available commands: `/help`
+- To see all 49 available commands: `/help`

package/learnship/workflows/plan-phase.md

@@ -53,6 +53,29 @@ Ask: "No CONTEXT.md found for Phase [X]. Plans will use research and requirement
 
 **If CONTEXT.md exists:** Load it and confirm: "Using phase context from: [path]"
 
+## Step 2b: Search Solutions for Prior Art
+
+**Skip if:** `workflow.solutions_search` is `false` in config (defaults to `true`).
+
+Search `.planning/solutions/` for prior art matching this phase's keywords:
+
+```bash
+# Check if solutions directory exists
+ls .planning/solutions/ 2>/dev/null
+
+# Search for matching solutions by phase keywords
+grep -ril "[phase_keyword1]\|[phase_keyword2]\|[phase_keyword3]" .planning/solutions/ 2>/dev/null
+```
+
+If matches found, read the frontmatter (first 30 lines) of each match. Surface relevant prior solutions to the planner:
+
+```
+Solutions prior art found:
+- .planning/solutions/[category]/[file].md — [title] (relevant: [why])
+```
+
+These solutions provide context for planning — the planner should reference them to avoid reinventing known solutions.
+
 ## Step 3: Research Phase
 
 **Skip if:** `--skip-research` flag, or `workflow.research` is `false` in config, or RESEARCH.md already exists (unless `--research` flag forces re-research).

package/learnship/workflows/progress.md

@@ -101,9 +101,15 @@ Context: [✓ CONTEXT.md exists | — not yet]
    - If CONTEXT.md exists: `▶ Next: plan-phase [X]`
    - If no CONTEXT.md: `▶ Next: discuss-phase [X]` (recommended) or `plan-phase [X]`
 
-5. **Summaries = plans AND plans > 0** → phase complete
-   - If more phases remain: `▶ Next: discuss-phase [X+1]`
-   - If all phases done: `▶ Next: audit-milestone`
+5. **Summaries = plans AND plans > 0, UAT not done** → verify first
+   - `▶ Next: verify-work [X]`
+
+6. **Summaries = plans, UAT passed, more phases remain** → move forward
+   - `▶ Next: discuss-phase [X+1]`
+   - Suggest: `/review` → `/ship` → `/compound` before starting next phase
+
+7. **All phases done** → ready to ship
+   - `▶ Next: audit-milestone`
 
 After presenting the recommended next step, ask: