learnship 2.3.5 → 2.4.0

package/learnship/workflows/review.md

@@ -1,15 +1,16 @@
 ---
-description: Multi-persona code review — correctness, testing, security, performance, maintainability
+description: Two-pass code review — spec compliance then multi-persona quality review
 ---
 
 # Review
 
-Multi-persona code review that examines changes through six lenses: correctness, testing, security, performance, maintainability, and adversarial. Produces a severity-ranked findings report with confidence scores.
+Two-pass code review. **Pass 1** confirms the change matches its spec (planned deliverables). **Pass 2** examines quality through six lenses: correctness, testing, security, performance, maintainability, and adversarial. Produces a severity-ranked findings report with confidence scores.
 
 **Usage:** `review` — review current branch changes
 **Usage:** `review [mode]` — modes: `interactive` (default), `report-only`, `autofix`
+**Usage:** `review --quality-only` — skip spec compliance pass, run quality review only
 
-**Sequencing:** Run after `verify-work` (spec compliance) and before `/ship` (deploy pipeline).
+**Sequencing:** Run after `verify-work` (acceptance testing) and before `/ship` (deploy pipeline).
 
 ## Step 1: Determine Scope
 
@@ -48,9 +49,89 @@ Combined with conversation context and any SUMMARY.md files from the current pha
 Intent: [what the changes are trying to accomplish]
 ```
 
-## Step 3: Select Personas
+## Step 3: Pass 1 — Spec Compliance
 
-Read the diff and file list. Select which review personas to activate:
+> Skip this pass entirely if `--quality-only` flag was given.
+
+Check whether the diff actually delivers what was planned. This is the "did we build the right thing?" gate — it runs before quality review because a spec failure is more important than any quality finding.
+
+### 3a. Load the Spec
+
+Try to find the spec in order of precedence:
+
+```bash
+# 1. Current phase PLAN.md files
+find .planning/phases -name "*-PLAN.md" -newer .git/refs/heads/$(git rev-parse --abbrev-ref HEAD 2>/dev/null) 2>/dev/null | head -5
+
+# 2. Most recently modified phase
+ls -t .planning/phases/ 2>/dev/null | head -3
+
+# 3. Commit messages as fallback spec
+git log --oneline ${BASE}..HEAD
+```
+
+If PLAN.md files found: read their `must_haves` frontmatter fields — these are the spec.
+If no PLAN.md: use commit message summaries as a lightweight spec.
+If no commits at all: spec compliance is N/A — skip to Pass 2.
+
+### 3b. Check Spec Coverage
+
+For each must-have deliverable or commit-described feature:
+
+1. Does the diff contain files that plausibly implement it?
+2. Are there test files covering it?
+3. Is it mentioned in any SUMMARY.md for the current phase?
+
+Classify each item as:
+- **COVERED** — evidence in diff matches the deliverable
+- **PARTIAL** — diff touches the right area but coverage seems incomplete
+- **MISSING** — no evidence in diff that this was implemented
+
+### 3c. Report Spec Compliance
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ learnship ► PASS 1: SPEC COMPLIANCE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Spec source: [PLAN.md path | commit messages]
+
+| Deliverable | Status | Evidence |
+|-------------|--------|----------|
+| [item 1]    | COVERED | [file/lines] |
+| [item 2]    | PARTIAL | [what's missing] |
+| [item 3]    | MISSING | — |
+
+Result: PASS | PARTIAL | FAIL
+```
+
+**If FAIL or PARTIAL:**
+```
+AskUserQuestion([
+  {
+    header: "Spec Gap",
+    question: "[N] planned deliverable(s) not found in this diff. Continue to quality review anyway?",
+    multiSelect: false,
+    options: [
+      { label: "Continue anyway", description: "Run quality review on what exists — spec gaps noted in report" },
+      { label: "Stop — fix spec gaps first", description: "Come back and re-run /review after completing missing deliverables" }
+    ]
+  }
+])
+```
+
+> 🛑 STOP. Wait for reply before continuing.
+
+If "Stop": output the missing items as a task list and stop.
+If "Continue": add spec gap findings to the final report as P1 items.
+
+**If PASS:** continue directly to Pass 2.
+
+---
+
+## Step 4: Pass 2 — Select Quality Personas
+
+Read the diff and file list. Select which quality review personas to activate:
 
 **Always-on (every review):**
 
@@ -81,7 +162,7 @@ Review team:
 - adversarial — [justification if selected]
 ```
 
-## Step 4: Run Review
+## Step 5: Run Quality Review
 
 Read `parallelization` from `.planning/config.json` (defaults to `false`).
 
@@ -138,7 +219,7 @@ Read `@./agents/code-reviewer.md` for the full persona definition. Run each sele
 2. Read the diff through that lens
 3. Record findings with severity and confidence
 
-## Step 5: Merge & Deduplicate Findings
+## Step 6: Merge & Deduplicate Findings
 
 Combine findings from all personas:
 
@@ -147,7 +228,7 @@ Combine findings from all personas:
 3. **Cross-persona agreement** — when 2+ personas flag the same issue, boost confidence by 0.10 (capped at 1.0).
 4. **Sort** — order by severity (P0 first) → confidence (descending) → file path → line number.
 
-## Step 6: Present Report
+## Step 7: Present Report
 
 ### Severity Scale
 
@@ -165,6 +246,7 @@ Display:
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 Intent: [intent summary]
+Spec compliance: PASS | PARTIAL ([N] gaps carried as P1) | SKIPPED (--quality-only)
 Reviewers: [list]
 Mode: [interactive | report-only | autofix]
 
@@ -195,7 +277,7 @@ Mode: [interactive | report-only | autofix]
 Total: [N] findings ([P0 count] critical, [P1 count] high, [P2 count] moderate, [P3 count] low)
 ```
 
-## Step 7: Handle Mode
+## Step 8: Handle Mode
 
 **Interactive (default):**
 For each P0/P1 finding, ask: "Fix this now, or defer?"
@@ -212,7 +294,7 @@ git add [files]
 git commit -m "fix([scope]): [description from finding]"
 ```
 
-## Step 8: Suggest Next Steps
+## Step 9: Suggest Next Steps
 
 ```
 ▶ Next steps:
@@ -230,6 +312,20 @@ git commit -m "fix([scope]): [description from finding]"
 
 ---
 
+## Design Quality Gate (UI changes only)
+
+If the review touched any user-facing UI files (frontend components, templates, stylesheets, public HTML), suggest running a design pass as a final lens — code correctness does not catch design regressions:
+
+> 🎨 **Design pass:** This review touched UI files. Run one of these `impeccable` actions on the changed views to catch issues code review misses (visual hierarchy, accessibility, motion, copy):
+>
+> - `@impeccable critique [component or view]` — Multi-frame critique (typography, color, spatial, motion, copy)
+> - `@impeccable polish [component or view]` — Apply small refinements before shipping
+> - `@impeccable audit [view]` — Scan for accessibility, contrast, and layout issues
+>
+> Skip if no UI files changed.
+
+---
+
 ## Learning Checkpoint
 
 Read `learning_mode` from `.planning/config.json`.

package/learnship/workflows/secure-phase.md

@@ -55,6 +55,8 @@ For each file, check for:
 - Hardcoded credentials
 - Insecure defaults
 
+**OWASP Top 10 surface scan:** As part of codebase analysis, note which OWASP categories are relevant to this phase's changes (see security-auditor agent for the full checklist). The SECURITY.md output must include an OWASP coverage table — marking each category as Relevant/N/A/Found. This makes the audit exhaustive and audit-trail-friendly.
+
 ## Step 3: Build Threat Register
 
 For each identified concern, create a threat entry:

package/learnship/workflows/ship.md

@@ -208,6 +208,49 @@ or patterns while context is fresh.
 
 ---
 
+## Pre-Ship Design Pass (UI changes only)
+
+Before opening the PR, if the staged changes touch any user-facing UI files, run a final design pass — this catches issues that tests and code review don't:
+
+```bash
+git diff --name-only --cached | grep -E '\.(tsx?|jsx?|vue|svelte|html|css|scss|less)$' | head -5
+```
+
+If UI files appear in the diff, suggest:
+
+> 🎨 **Design pass before ship:** Staged changes include UI files. Run one of these to catch design regressions before opening the PR:
+>
+> - `@impeccable polish [view]` — Quick refinement pass: typography, spacing, color, copy
+> - `@impeccable audit [view]` — Accessibility + contrast + layout scan
+> - `@impeccable harden [view]` — Edge-case resilience (small viewport, RTL, screen reader)
+>
+> Skip on non-UI changes.
+
+---
+
+## Live Smoke Test Before PR (when Playwright MCP is available)
+
+**Supported on:** Any platform with MCP support configured (Claude Code, OpenCode, Cursor, Windsurf, Codex CLI, Gemini CLI).
+
+If `mcp__playwright__*` tools are available and the staged changes touch a web UI, run a quick smoke test before creating the PR — catches rendering failures that tests don't:
+
+```bash
+# Check server is running
+curl -s -o /dev/null -w "%{http_code}" http://localhost:3000 2>/dev/null || echo "not-running"
+```
+
+If the server is running and Playwright is available:
+1. Navigate to the primary page
+2. Walk the changed flow once (the golden path for this change)
+3. Take a screenshot — verify it matches expectations
+4. Check the browser console — zero JS errors required
+
+**If smoke test fails:** Stop the ship pipeline. Fix before pushing.
+
+If Playwright is not configured or the server is not running: skip this step and note it in the PR description. To configure: see the `verify-work` workflow for Playwright MCP setup instructions per platform.
+
+---
+
 ## Learning Checkpoint
 
 Read `learning_mode` from `.planning/config.json`.

package/learnship/workflows/verify-work.md

@@ -351,6 +351,39 @@ Present when ready:
 
 ---
 
+## Live UI Smoke Test (when Playwright MCP is available)
+
+**Supported on:** Any platform with MCP support configured (Claude Code, OpenCode, Cursor, Windsurf, Codex CLI, Gemini CLI). Optional enhancement layer — the conversational UAT above is the primary mechanism on all platforms.
+
+After UAT passes, if the tested deliverables include any user-facing UI **and** your tool list includes `mcp__playwright__*` tools (or equivalents), run a quick live smoke test before committing the UAT as complete:
+
+**1. Find the entry point:**
+```bash
+# Check common dev server patterns
+grep -E '"(dev|start|serve)"' package.json 2>/dev/null | head -3
+cat README.md 2>/dev/null | grep -i "http://localhost" | head -3
+```
+
+**2. Verify the server is running:**
+```bash
+curl -s -o /dev/null -w "%{http_code}" http://localhost:3000 2>/dev/null || \
+curl -s -o /dev/null -w "%{http_code}" http://localhost:8080 2>/dev/null || \
+echo "not-running"
+```
+
+**3. Walk the golden path via Playwright:**
+- Navigate to the primary entry point
+- Walk through each UI deliverable from the UAT list once
+- Take a screenshot at each key step
+- Check the browser console for JS errors
+
+**4. Record the result:**
+If any Playwright step fails (HTTP error, JS exception, visual regression), treat it as a UAT issue with severity `blocker` and add it to the Gaps section.
+
+> **Platform note:** Playwright MCP is supported wherever MCP is available — Claude Code, OpenCode, Cursor, Windsurf, Codex CLI, and Gemini CLI all support MCP servers. To enable it: install `@playwright/mcp` and add it to your platform's MCP config. On Claude Code: `claude mcp add playwright npx @playwright/mcp`. On Cursor/Windsurf: add `@playwright/mcp` as an MCP server in your IDE settings. Once configured, learnship workflows detect and use it automatically.
+
+---
+
 ## Learning Checkpoint
 
 Read `learning_mode` from `.planning/config.json`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "learnship",
-  "version": "2.3.5",
+  "version": "2.4.0",
   "description": "Learn as you build. Build with intent. — A multi-platform agentic engineering system for Windsurf, Claude Code, Cursor, OpenCode, Gemini CLI, and Codex: 57 spec-driven workflows, 17 specialist agent personas, integrated learning, and production-grade design.",
   "keywords": [
     "agentic",