learnship 1.9.0

package/learnship/workflows/add-tests.md

@@ -0,0 +1,191 @@
+---
+description: Generate and add test coverage for a specific plan or phase post-execution
+---
+
+# Add Tests
+
+Generate unit and E2E tests for a completed phase. Classifies each changed file into unit (TDD), browser (E2E), or skip categories, presents a test plan for approval, then writes tests following RED-GREEN conventions.
+
+**Usage:** `add-tests [N]` or `add-tests [N] [additional instructions]`
+
+## Step 1: Validate Phase
+
+Phase number is required:
+```
+Usage: add-tests [N] [optional instructions]
+Example: add-tests 3
+Example: add-tests 3 focus on edge cases in the pricing module
+```
+
+Find the phase directory:
+```bash
+ls .planning/phases/ | grep -E "^0*[N]-" | head -1
+PHASE_DIR=".planning/phases/[matched]"
+```
+
+Check that SUMMARY.md exists (phase must be executed):
+```bash
+ls "$PHASE_DIR"/*-SUMMARY.md 2>/dev/null
+```
+
+If no SUMMARY.md: stop — "Phase [N] hasn't been executed yet. Run `execute-phase [N]` first."
+
+## Step 2: Read Phase Artifacts
+
+Read in priority order:
+1. All `*-SUMMARY.md` files — what was implemented, which files changed
+2. `CONTEXT.md` — acceptance criteria and user decisions
+3. `*-VERIFICATION.md` — user-verified scenarios (if UAT was done)
+
+Extract the list of files modified by the phase from SUMMARY.md.
+
+## Step 3: Detect Test Infrastructure
+
+```bash
+find . \( -name "jest.config.*" -o -name "vitest.config.*" -o -name "pytest.ini" -o -name "pyproject.toml" -o -name "playwright.config.*" \) -not -path "*/node_modules/*" 2>/dev/null
+
+find . \( -name "*.test.*" -o -name "*.spec.*" -o -name "test_*.py" \) -not -path "*/node_modules/*" 2>/dev/null | head -10
+```
+
+Identify: test framework, E2E framework (if any), how to run tests, existing test file patterns and locations.
+
+## Step 4: Classify Each File
+
+For each file modified by the phase, classify into one of three categories:
+
+**Unit (TDD)** — when the file contains:
+- Business logic: calculations, pricing, tax, discounts
+- Data transformations: mapping, filtering, aggregation, formatting
+- Validators: input validation, schema validation, business rules
+- State machines: status transitions, workflow steps
+- Pure utilities: string manipulation, date handling, number formatting
+
+**E2E (Browser)** — when the file produces:
+- Keyboard shortcut behavior
+- Navigation and routing
+- Form interactions: submit, validation errors, focus
+- Multi-step user flows
+- Modal dialogs and overlays
+- Data grids: sorting, filtering, inline editing
+
+**Skip** — when the file is:
+- UI layout/styling only (CSS, visual appearance)
+- Configuration files, env vars, feature flags
+- Glue code: DI setup, middleware registration, routing tables
+- Database migrations or schema files
+- Simple CRUD with no business logic
+- Pure type definitions with no logic
+
+Read each file to verify — don't classify by filename alone.
+
+## Step 5: Present Classification
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ learnship ► ADD TESTS — Phase [N]: [name]
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Files classified for testing:
+
+Unit Tests ([N] files):
+- [file]: [reason — "contains pricing calculation logic"]
+- [file]: [reason]
+
+E2E Tests ([M] files):
+- [file]: [reason — "login form with validation"]
+
+Skipped ([K] files):
+- [file]: [reason — "CSS-only, no logic"]
+
+Proceed with this plan? (yes / adjust classification)
+```
+
+Wait for confirmation.
+
+## Step 6: Generate Unit Tests
+
+For each TDD file, write unit tests:
+
+**File location:** Match the project's test file convention (e.g., `src/utils/__tests__/pricing.test.ts` or `tests/test_pricing.py`).
+
+**Pattern:**
+```
+describe('[function/module name]', () => {
+  it('[behavior description]', () => {
+    // Arrange
+    const input = [test input]
+    // Act
+    const result = [function call]
+    // Assert
+    expect(result).toBe([expected])
+  })
+
+  it('handles edge case: [edge case description]', () => {
+    ...
+  })
+})
+```
+
+For each test file written:
+- Cover the happy path
+- Cover 2-3 edge cases (empty input, boundary values, error conditions)
+- Apply any extra instructions provided
+
+Run tests to verify they pass:
+```bash
+[test command] [test file path]
+```
+
+If tests fail: fix them (up to 3 attempts). If tests still fail after 3 attempts, note the blocker and skip that file.
+
+## Step 7: Generate E2E Tests (if applicable)
+
+If E2E framework exists (Playwright, Cypress, etc.), write E2E tests for classified files:
+
+Match existing E2E test conventions in the project. Focus on user-visible behavior described in CONTEXT.md and VERIFICATION.md.
+
+If no E2E framework exists: note it and skip E2E generation.
+
+## Step 8: Commit Tests
+
+Commit unit and E2E tests separately:
+
+```bash
+git add [unit test files]
+git commit -m "test([padded_phase]): add unit tests for [brief description]"
+
+git add [e2e test files]
+git commit -m "test([padded_phase]): add E2E tests for [brief description]"
+```
+
+## Step 9: Report
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ learnship ► TESTS ADDED ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Unit tests: [N] files, [M] test cases
+E2E tests: [K] files (or "none — no E2E framework detected")
+Skipped: [J] files
+
+[If any blockers:]
+⚠️  [N] file(s) could not be tested: [reasons]
+
+▶ Next: validate-phase [N] — map tests to requirements
+        or: verify-work [N] — manual acceptance testing
+```
+
+---
+
+## Learning Checkpoint
+
+Read `learning_mode` from `.planning/config.json`.
+
+**If `auto`:** Offer:
+
+> 💡 **Learning moment:** Tests written. Test what you know about the behaviors you just covered:
+>
+> `@agentic-learning quiz [phase topic]` — Quiz yourself on the behaviors these tests encode. If you can't explain *why* each test case exists, the knowledge is fragile.
+
+**If `manual`:** Add quietly: *"Tip: `@agentic-learning quiz [topic]` to verify you understand what the tests are actually testing."*

package/learnship/workflows/add-todo.md

@@ -0,0 +1,108 @@
+---
+description: Capture a todo/idea mid-session without interrupting flow
+---
+
+# Add Todo
+
+Capture an idea, task, or issue that surfaces during a session. Fast "thought → capture → continue" — saves context without losing momentum.
+
+**Usage:** `add-todo [description]` or just `add-todo` to capture from recent conversation.
+
+## Step 1: Ensure Directories Exist
+
+```bash
+mkdir -p .planning/todos/pending .planning/todos/done
+```
+
+## Step 2: Extract Content
+
+**With description argument:** Use it as the title/focus.
+
+**Without argument:** Read recent conversation context to extract:
+- The specific problem, idea, or task being discussed
+- Relevant file paths mentioned
+- Technical details (error messages, constraints, line numbers)
+
+Formulate:
+- `title` — 3-10 word descriptive title (action verb preferred, e.g., "Add auth token refresh")
+- `problem` — what's wrong or why this is needed (enough context for future Cascade sessions)
+- `solution` — approach hints, or "TBD" if just an idea
+- `files` — relevant file paths with line numbers from context
+
+## Step 3: Infer Area
+
+Determine area from file paths mentioned:
+
+| Path pattern | Area |
+|--------------|------|
+| `src/api/`, `api/` | `api` |
+| `src/components/`, `src/ui/` | `ui` |
+| `src/auth/`, `auth/` | `auth` |
+| `src/db/`, `database/` | `database` |
+| `tests/`, `__tests__/`, `*.test.*` | `testing` |
+| `docs/` | `docs` |
+| `.planning/` | `planning` |
+| `scripts/`, `bin/` | `tooling` |
+| Unclear or none | `general` |
+
+## Step 4: Check for Duplicates
+
+```bash
+ls .planning/todos/pending/ 2>/dev/null
+grep -rl "[key words from title]" .planning/todos/pending/ 2>/dev/null
+```
+
+If a similar todo exists, show it and ask: "A similar todo already exists: [title]. Create anyway, or update the existing one?"
+
+## Step 5: Write Todo File
+
+Generate a date-based slug: `YYYY-MM-DD-[slug].md`
+
+Write to `.planning/todos/pending/[filename]`:
+
+```markdown
+---
+created: [ISO datetime]
+title: [title]
+area: [area]
+files:
+  - [file:line if applicable]
+---
+
+## Problem
+
+[problem description — enough context for future Cascade to understand weeks later, without re-reading the full conversation]
+
+## Solution
+
+[approach hints or "TBD — need to investigate"]
+```
+
+## Step 6: Update STATE.md
+
+If `.planning/STATE.md` exists, update the Pending Todos count under Accumulated Context:
+
+```bash
+grep -c "^" .planning/todos/pending/*.md 2>/dev/null
+```
+
+Update the `### Pending Todos` section with the new count and latest title.
+
+## Step 7: Commit
+
+```bash
+git add ".planning/todos/pending/[filename]" .planning/STATE.md
+git commit -m "docs: capture todo — [title]"
+```
+
+## Step 8: Confirm
+
+```
+Todo saved: .planning/todos/pending/[filename]
+
+  [title]
+  Area: [area]
+  Files: [count] referenced
+
+Continue with current work, or check all todos with check-todos.
+```

package/learnship/workflows/audit-milestone.md

@@ -0,0 +1,178 @@
+---
+description: Verify milestone met its definition of done — requirement coverage, integration check, stub detection
+---
+
+# Audit Milestone
+
+Pre-release audit that aggregates phase verifications, checks cross-phase integration, validates requirement coverage, and detects stubs/placeholders. Run before `/complete-milestone`.
+
+**Use when:** All phases are complete and you want to verify the milestone is actually done before archiving.
+
+## Step 1: Determine Milestone Scope
+
+Read `.planning/ROADMAP.md` and `.planning/REQUIREMENTS.md`.
+
+Find all phases in the current milestone (all phases in ROADMAP.md that aren't in a completed milestone archive).
+
+Display:
+```
+Auditing milestone: [VERSION] [Name]
+Phases in scope: [list of phase numbers and names]
+Requirements in scope: [N] requirements ([list of REQ-IDs])
+```
+
+## Step 2: Read All Phase Verifications
+
+For each phase directory, read its VERIFICATION.md:
+```bash
+for phase_dir in .planning/phases/*/; do
+  cat "${phase_dir}"*-VERIFICATION.md 2>/dev/null
+done
+```
+
+From each VERIFICATION.md, extract:
+- **Status:** `passed` | `gaps_found` | `human_needed`
+- **Gaps:** any items that failed
+- **Requirements coverage table:** which REQ-IDs were verified
+
+**If any phase is missing VERIFICATION.md:** flag as `unverified` — this is a blocker.
+
+## Step 3: Check Requirements Coverage
+
+Cross-reference three sources for each requirement:
+
+**Source A — REQUIREMENTS.md traceability:**
+```bash
+grep -E "^\|.*REQ-" .planning/REQUIREMENTS.md
+```
+
+**Source B — Phase VERIFICATION.md tables:**
+Extract per-requirement status from each phase's verification file.
+
+**Source C — Phase SUMMARY.md:**
+Check each SUMMARY.md for requirements-completed notes.
+
+For each REQ-ID, determine status:
+
+| VERIFICATION status | SUMMARY mentions it | REQUIREMENTS checkbox | → Audit status |
+|--------------------|--------------------|----------------------|----------------|
+| passed | yes | `[x]` | **satisfied** |
+| passed | yes | `[ ]` | **satisfied** (fix checkbox) |
+| gaps_found | any | any | **unsatisfied** |
+| missing | any | any | **unsatisfied** |
+
+Any `unsatisfied` requirement = milestone audit `gaps_found`.
+
+**Orphan detection:** Requirements in REQUIREMENTS.md that appear in no phase VERIFICATION.md → flag as `orphaned` (treated as unsatisfied).
+
+## Step 4: Cross-Phase Integration Check
+
+Using `@./agents/verifier.md` in integration mode, check cross-phase wiring:
+
+Read all SUMMARY.md files to understand what each phase exported (APIs, components, utilities).
+
+Check:
+1. **Import chains:** Do modules that claim to export X actually export it? Do modules that import X use the correct path and signature?
+2. **API contracts:** Do API routes match what the UI calls? Are response shapes consistent?
+3. **E2E user flows:** Pick the 3-5 most important user journeys. Trace each through the codebase — does every step have a real implementation?
+4. **Stub detection:** Scan for `// TODO`, `// FIXME`, placeholder strings, `return null`/`return undefined` in non-trivial functions, empty bodies.
+
+```bash
+grep -rn "TODO\|FIXME\|PLACEHOLDER\|return null\|return undefined" src/ --include="*.ts" --include="*.tsx" --include="*.js" 2>/dev/null | grep -v "node_modules\|\.test\." | head -30
+```
+
+## Step 5: Compile Audit Report
+
+Write `.planning/[VERSION]-MILESTONE-AUDIT.md`:
+
+```markdown
+---
+status: passed | gaps_found
+milestone: [VERSION]
+audited: [date]
+gaps:
+  requirements: [list of unsatisfied REQ-IDs]
+  integration: [list of broken cross-phase connections]
+  flows: [list of broken E2E flows]
+  stubs: [list of stub locations]
+---
+
+# Milestone Audit: [VERSION] [Name]
+
+## Requirements Coverage
+
+| REQ-ID | Description | Phase | Status |
+|--------|-------------|-------|--------|
+| AUTH-01 | [description] | 02 | ✓ satisfied |
+| DASH-01 | [description] | 03 | ✗ unsatisfied |
+
+**Total:** [X]/[Y] requirements satisfied
+
+## Phase Verification Summary
+
+| Phase | Status | Notes |
+|-------|--------|-------|
+| 01 — [Name] | ✓ passed | |
+| 02 — [Name] | ✗ gaps_found | [gap summary] |
+
+## Integration Findings
+
+### Cross-Phase Wiring
+[What's connected correctly, what's broken]
+
+### E2E Flows
+[Which flows work, which are broken and where]
+
+## Stubs Found
+
+[List of TODO/FIXME/placeholder locations, or "None found"]
+
+## Verdict
+
+[PASSED — all requirements satisfied, no critical gaps]
+OR
+[GAPS FOUND — N requirements unsatisfied, M integration issues]
+```
+
+## Step 6: Present Audit Results
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ learnship ► MILESTONE AUDIT [VERSION]
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Requirements: [X]/[Y] satisfied
+Integration: [passed | N issues found]
+Stubs: [none | N found]
+
+Status: [PASSED ✓ | GAPS FOUND ⚠️]
+```
+
+**If PASSED:**
+```
+Milestone [VERSION] is ready to ship.
+
+▶ Next: complete-milestone
+```
+
+**If GAPS FOUND:**
+```
+[N] gap(s) require attention before release:
+
+[List gaps]
+
+▶ Next: plan-milestone-gaps — create fix phases for all gaps
+    OR: complete-milestone — ship anyway (mark gaps as known issues)
+```
+
+---
+
+## Learning Checkpoint
+
+Read `learning_mode` from `.planning/config.json`.
+
+**If `auto`:** Offer:
+
+> 💡 **Learning moment:** Audit complete. Before planning fixes:
+>
+> `@agentic-learning reflect` — What were the gap patterns? Were they requirements misses, integration oversights, or execution stubs? Understanding *why* gaps happened improves the next milestone.

package/learnship/workflows/check-todos.md

@@ -0,0 +1,138 @@
+---
+description: Review and act on all pending todos captured with add-todo
+---
+
+# Check Todos
+
+List all pending todos, select one to review, and route to the appropriate action.
+
+**Usage:** `check-todos` or `check-todos [area]` to filter by area.
+
+## Step 1: Load Todos
+
+```bash
+ls .planning/todos/pending/ 2>/dev/null | sort
+```
+
+If no pending todos:
+```
+No pending todos.
+
+Todos are captured during work sessions with add-todo.
+```
+Stop.
+
+## Step 2: Apply Area Filter (if specified)
+
+If an area argument was provided (e.g., `check-todos api`), filter to only show todos matching that area:
+```bash
+grep -l "^area: api" .planning/todos/pending/*.md 2>/dev/null
+```
+
+Valid areas: `api`, `ui`, `auth`, `database`, `testing`, `docs`, `planning`, `tooling`, `general`.
+
+If filter yields no results: "No todos in area '[area]'. Showing all todos instead."
+
+## Step 3: List Todos
+
+Read frontmatter from each todo file and display as a numbered list:
+
+```
+Pending Todos ([N] total):
+
+1. [title] (area: [area], [relative age — e.g., "2d ago"])
+2. [title] (area: [area], [relative age])
+3. [title] (area: [area], [relative age])
+
+Reply with a number to view details, or 'q' to exit.
+```
+
+Wait for selection.
+
+## Step 4: Show Todo Detail
+
+Read the full todo file:
+
+```
+## [title]
+
+Area: [area]
+Created: [date] ([relative age] ago)
+Files: [list of file:line references, or "None"]
+
+### Problem
+[problem content]
+
+### Solution
+[solution content]
+```
+
+If files are listed, briefly check if they still exist and note if any were deleted or moved.
+
+## Step 5: Check Roadmap Relevance
+
+```bash
+cat .planning/ROADMAP.md 2>/dev/null
+```
+
+Check if the todo's area or files overlap with any upcoming (not yet executed) phase. If yes, note: "This todo may relate to Phase [N]: [name]."
+
+## Step 6: Offer Actions
+
+Present actions based on context:
+
+**If todo relates to a roadmap phase:**
+```
+This todo relates to Phase [N]: [name].
+
+Actions:
+1. Work on it now — move to done, start working immediately
+2. Note for Phase [N] — keep pending, bring up when planning that phase
+3. Brainstorm approach — think through the problem before deciding
+4. Back to list
+
+```
+
+**If no roadmap match:**
+```
+Actions:
+1. Work on it now — move to done, start working immediately
+2. Create a phase — add a new phase to the roadmap for this work
+3. Brainstorm approach — think through the problem before deciding
+4. Back to list
+```
+
+Wait for choice.
+
+## Step 7: Execute Action
+
+**Work on it now:**
+```bash
+mv ".planning/todos/pending/[filename]" ".planning/todos/done/"
+git add ".planning/todos/pending/[filename]" ".planning/todos/done/[filename]"
+git commit -m "docs: start work on todo — [title]"
+```
+
+Present the problem and solution context. Begin work, or ask how to proceed.
+
+**Note for Phase [N]:**
+Keep in pending. Remind at planning time. Return to list.
+
+**Create a phase:**
+Suggest: `add-phase [description from todo title]`. Keep todo in pending. User runs the command.
+
+**Brainstorm approach:**
+Keep in pending. Begin discussing the problem — what approaches exist, trade-offs, what to investigate.
+
+**Back to list:**
+Return to Step 3.
+
+## Step 8: Update STATE.md
+
+After any action that changes the todo count:
+
+```bash
+PENDING=$(ls .planning/todos/pending/*.md 2>/dev/null | wc -l)
+```
+
+Update the `### Pending Todos` section in STATE.md with the new count.