learnship 2.0.11 → 2.1.1

package/learnship/workflows/verify-work.md

@@ -10,6 +10,20 @@ Validate built features through conversational testing. Walk through each delive
 
 **Philosophy:** Show expected, ask if reality matches. No pass/fail buttons. No severity questions. Just: "Here's what should happen. Does it?"
 
+<core_principle>
+**Task completion ≠ Goal achievement**
+
+A task "create chat component" can be marked complete when the component is a placeholder. The task was done — but the goal "working chat interface" was not achieved.
+
+Goal-backward verification:
+1. What must be TRUE for the goal to be achieved?
+2. What must EXIST for those truths to hold?
+3. What must be WIRED for those artifacts to function?
+4. What must TESTS PROVE for those truths to be evidenced?
+
+Then verify each level against the actual codebase.
+</core_principle>
+
 ## Step 1: Initialize
 
 Check for existing UAT sessions:
@@ -41,7 +55,21 @@ No active UAT sessions.
 Provide a phase number to start testing (e.g., verify-work 4)
 ```
 
-## Step 2: Find Deliverables
+## Step 2: Extract Must-Haves
+
+First, extract must-haves from plan frontmatter:
+```bash
+for plan in .planning/phases/[padded_phase]-[phase_slug]/*-PLAN.md; do
+  echo "=== $plan ==="
+  head -30 "$plan"
+done
+```
+
+Look for `must_haves` in each plan's frontmatter — these are the primary verification targets. If plans have must_haves, use them as the backbone of the test list.
+
+Also check ROADMAP.md for Success Criteria for this phase — these override plan-level must_haves when both exist.
+
+## Step 2b: Find Deliverables
 
 Read all SUMMARY.md files for the phase:
 ```bash
@@ -55,6 +83,8 @@ Extract testable deliverables from each SUMMARY.md — focus on **user-observabl
 
 Skip internal changes (refactors, type changes, test additions).
 
+**Stub detection:** Before presenting tests, do a quick scan for placeholder code using patterns from `@./references/verification-patterns.md` (if it exists). Flag any files that look like stubs — these should be tested more carefully.
+
 **Cold-start smoke test:** If any SUMMARY.md mentions server entry points, database files, migrations, or docker files — prepend a "Cold Start Smoke Test" as the first test:
 ```
 Expected: Kill any running server. Clear ephemeral state. Start from scratch.
@@ -198,9 +228,11 @@ Immediately run the `review` workflow for this phase's changes.
 All tests passed. ✓
 
 ▶ Recommended next steps:
-  `/review`   — multi-persona code review (6 lenses: correctness, testing, security, performance, maintainability, adversarial)
-  `/ship`     — test → lint → commit → push → PR
-  `/compound` — capture notable solutions or patterns while context is fresh
+  `/review`            — multi-persona code review (6 lenses)
+  `/secure-phase [X]`  — STRIDE security verification for this phase
+  `/ship`              — test → lint → commit → push → PR
+  `/compound`          — capture notable solutions or patterns while context is fresh
+  `/extract-learnings [X]` — capture decisions, lessons, patterns, surprises
 
 ▶ Or continue: discuss-phase [X+1]
 ```

package/package.json

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

package/references/common-bug-patterns.md

@@ -0,0 +1,92 @@
+<common_bug_patterns>
+
+Patterns for detecting common bugs in AI-generated code. Used by the verifier agent and verify-work workflow to catch issues that pass basic existence checks but fail in practice.
+
+---
+
+## Stub Detection
+
+These patterns indicate placeholder code regardless of file type:
+
+### Comment-based stubs
+```bash
+grep -E "(TODO|FIXME|XXX|HACK|PLACEHOLDER)" "$file"
+grep -E "implement|add later|coming soon|will be" "$file" -i
+grep -E "// \.\.\.|/\* \.\.\. \*/|# \.\.\." "$file"
+```
+
+### Placeholder text in output
+```bash
+grep -E "placeholder|lorem ipsum|coming soon|under construction" "$file" -i
+grep -E "sample|example|test data|dummy" "$file" -i
+```
+
+### Empty or trivial implementations
+```bash
+grep -E "return null|return undefined|return \{\}|return \[\]" "$file"
+grep -E "pass$|\.\.\.|\bnothing\b" "$file"
+grep -E "console\.(log|warn|error).*only" "$file"
+```
+
+### Hardcoded values where dynamic expected
+```bash
+grep -E "id.*=.*['\"].*['\"]" "$file"
+grep -E "count.*=.*\d+|length.*=.*\d+" "$file"
+```
+
+---
+
+## Wiring Gaps
+
+Code exists but isn't connected to the rest of the system:
+
+### Unregistered routes
+- Route handler file exists but not imported in the router/app entry
+- API endpoint defined but not added to the route table
+
+### Unused exports
+- Component exported but never imported anywhere
+- Utility function exported but no consumers
+
+### Missing environment variables
+- Code references `process.env.X` but `.env.example` doesn't list it
+- Config reads a key that's not in the defaults
+
+### Broken imports
+- Import path doesn't match actual file location (case sensitivity on Linux)
+- Circular dependency that works in dev but fails in production build
+
+---
+
+## State Drift
+
+State management issues that cause subtle bugs:
+
+### Stale state references
+- React component reads state that was updated in a different render cycle
+- Cache not invalidated after mutation
+
+### Race conditions
+- Multiple async operations writing to the same resource
+- Optimistic UI update without rollback on failure
+
+### Schema mismatch
+- Database migration changes column type but API response type not updated
+- Frontend expects field that backend stopped sending
+
+---
+
+## Verification Levels
+
+For each artifact, verify at the appropriate level:
+
+| Level | Check | Method |
+|-------|-------|--------|
+| 1. Exists | File is present at expected path | `ls [file]` |
+| 2. Substantive | Content is real implementation, not placeholder | Stub detection patterns above |
+| 3. Wired | Connected to the rest of the system | Import/route check |
+| 4. Functional | Actually works when invoked | Run command or manual test |
+
+Levels 1-3 can be checked programmatically. Level 4 often requires human verification (verify-work UAT).
+
+</common_bug_patterns>

package/references/context-budget.md

@@ -0,0 +1,49 @@
+<context_budget>
+
+Standard rules for keeping orchestrator context lean. Reference this in workflows that spawn subagents or read significant content.
+
+---
+
+## Universal Rules
+
+Every workflow that spawns agents or reads significant content must follow these rules:
+
+1. **Never** read agent definition files (`agents/*.md`) — `subagent_type` auto-loads them
+2. **Never** inline large files into subagent prompts — tell agents to read files from disk instead
+3. **Read depth scales with context window** — check `context_window` in `.planning/config.json`:
+   - At < 500000 tokens (default 200k): read only frontmatter, status fields, or summaries
+   - At >= 500000 tokens (1M model): MAY read full subagent output bodies when needed for inline decisions
+4. **Delegate** heavy work to subagents — the orchestrator routes, it doesn't execute
+5. **Proactive warning**: If you've already consumed significant context (large file reads, multiple subagent results), warn the user: "Context budget is getting heavy. Consider checkpointing progress."
+
+## Read Depth by Context Window
+
+| Context Window | Subagent Output Reading | SUMMARY.md | VERIFICATION.md | PLAN.md (other phases) |
+|---------------|------------------------|------------|-----------------|------------------------|
+| < 500k (200k model) | Frontmatter only | Frontmatter only | Frontmatter only | Current phase only |
+| >= 500k (1M model) | Full body permitted | Full body permitted | Full body permitted | Current phase only |
+
+**How to check:** Read `.planning/config.json` and inspect `context_window`. If the field is absent, treat as 200000 (conservative default).
+
+## Context Degradation Tiers
+
+Monitor context usage and adjust behavior accordingly:
+
+| Tier | Usage | Behavior |
+|------|-------|----------|
+| PEAK | 0-30% | Full operations. Read bodies, spawn multiple agents, inline results. |
+| GOOD | 30-50% | Normal operations. Prefer frontmatter reads, delegate aggressively. |
+| DEGRADING | 50-70% | Economize. Frontmatter-only reads, minimal inlining, warn user about budget. |
+| POOR | 70%+ | Emergency mode. Checkpoint progress immediately. No new reads unless critical. |
+
+## Context Degradation Warning Signs
+
+Quality degrades gradually before panic thresholds fire. Watch for these early signals:
+
+- **Silent partial completion** — agent claims task is done but implementation is incomplete. Always verify agent output meets the plan's must_haves, not just that files exist.
+- **Increasing vagueness** — agent starts using phrases like "appropriate handling" or "standard patterns" instead of specific code. This indicates context pressure.
+- **Skipped steps** — agent omits protocol steps it would normally follow. If an agent's success criteria has 8 items but it only reports 5, suspect context pressure.
+
+When delegating to agents, the orchestrator cannot verify semantic correctness of agent output — only structural completeness. Mitigate with must_haves and spot-check verification.
+
+</context_budget>

package/references/domain-probes.md

@@ -0,0 +1,133 @@
+<domain_probes>
+
+Domain-aware probing patterns for `/new-project` deep questioning and `/discuss-phase` gray area identification.
+
+When the user mentions a technology area, use these probes to ask insightful follow-up questions. Don't run through them as a checklist — pick the 2-3 most relevant based on context. The goal is to surface hidden assumptions and trade-offs the user may not have considered yet.
+
+---
+
+## Authentication
+
+| User mentions | Probe with domain knowledge |
+|---|---|
+| "login" or "auth" | OAuth (which providers?), JWT, or session-based? Social login or just email/password? |
+| "users" or "accounts" | MFA required? Password reset flow? Email verification? |
+| "sessions" | Session duration and refresh strategy? Server-side sessions or stateless tokens? |
+| "roles" or "permissions" | RBAC, ABAC, or simple role checks? How many distinct roles? |
+| "API keys" | Key rotation strategy? Scoped permissions per key? Rate limiting per key? |
+
+---
+
+## Real-Time Updates
+
+| User mentions | Probe with domain knowledge |
+|---|---|
+| "real-time" or "live updates" | WebSockets, SSE, or polling? What specifically needs to be real-time vs. eventual? |
+| "notifications" | Push notifications (browser/mobile), in-app only, or both? Persistence and read receipts? |
+| "collaboration" or "multiplayer" | Conflict resolution strategy? Operational transforms or CRDTs? Expected concurrent users? |
+| "chat" or "messaging" | Message history and search? Typing indicators? Read receipts? |
+| "streaming" | Reconnection strategy? What happens when the connection drops — queue or discard? |
+
+---
+
+## Dashboard
+
+| User mentions | Probe with domain knowledge |
+|---|---|
+| "dashboard" | What data sources feed it? How many distinct views? |
+| "charts" or "graphs" | Interactive or static? Drill-down capability? Export to CSV/PDF? |
+| "metrics" or "KPIs" | Refresh strategy — real-time, periodic polling, or on-demand? Acceptable staleness? |
+| "admin panel" | Role-based visibility? Which actions beyond viewing (edit, delete, approve)? |
+| "mobile" or "responsive" | Simplified mobile view or full parity? Touch interactions for charts? |
+
+---
+
+## API Design
+
+| User mentions | Probe with domain knowledge |
+|---|---|
+| "API" | REST, GraphQL, or RPC-style? Internal only or public-facing? |
+| "endpoints" or "routes" | Versioning strategy (URL path, header, query param)? Breaking change policy? |
+| "pagination" | Cursor-based or offset? Expected result set sizes? Stable ordering guarantee? |
+| "rate limiting" | Per-user, per-IP, or per-API-key? Burst allowance? How to communicate limits to clients? |
+| "errors" | Structured error format? Error codes vs. messages? How much detail in production errors? |
+
+---
+
+## Database
+
+| User mentions | Probe with domain knowledge |
+|---|---|
+| "database" or "storage" | SQL or NoSQL? What drives the choice — relational integrity, flexibility, scale? |
+| "ORM" or "queries" | ORM (which one?) or raw queries? Query builder as middle ground? |
+| "migrations" | Migration tool? Rollback strategy? How to handle data migrations vs. schema migrations? |
+| "seeding" or "test data" | Seed data for development? Realistic fake data or minimal fixtures? |
+| "scale" or "performance" | Read/write ratio? Read replicas? Connection pooling strategy? |
+
+---
+
+## Search
+
+| User mentions | Probe with domain knowledge |
+|---|---|
+| "search" | Full-text or exact match? Dedicated search engine (Elasticsearch, Meilisearch) or database-level? |
+| "filtering" or "facets" | Faceted filtering? How many filter dimensions? Combined filters (AND/OR)? |
+| "autocomplete" or "typeahead" | Debounce strategy? Minimum character threshold? Result ranking? |
+| "indexing" | Index size and update frequency? Real-time indexing or batch? Acceptable index lag? |
+
+---
+
+## File Upload/Storage
+
+| User mentions | Probe with domain knowledge |
+|---|---|
+| "upload" or "file upload" | Local filesystem or cloud (S3, GCS, Azure Blob)? Direct upload or through server? |
+| "images" or "media" | Processing pipeline — resize, compress, thumbnail generation? Format conversion? |
+| "size limits" | Max file size? Max total storage per user? What happens when limits are hit? |
+| "documents" or "attachments" | Virus scanning? Preview generation? Versioning of uploaded files? |
+
+---
+
+## Caching
+
+| User mentions | Probe with domain knowledge |
+|---|---|
+| "caching" or "performance" | Where to cache — browser, CDN, application layer, database query cache? |
+| "invalidation" | Invalidation strategy — TTL, event-driven, or manual? Cache-aside vs. write-through? |
+| "stale data" | Acceptable staleness window? Stale-while-revalidate pattern? |
+
+---
+
+## Testing
+
+| User mentions | Probe with domain knowledge |
+|---|---|
+| "testing" or "tests" | Unit, integration, and E2E balance? Where to invest most testing effort? |
+| "CI" or "pipeline" | Tests in CI? Parallel test execution? Test-on-PR or test-on-push? |
+| "E2E" or "browser testing" | Playwright, Cypress, or other? Headed vs. headless? Visual regression testing? |
+
+---
+
+## Deployment
+
+| User mentions | Probe with domain knowledge |
+|---|---|
+| "deploy" or "hosting" | Container, serverless, or traditional VM/VPS? Managed platform (Vercel, Railway) or self-hosted? |
+| "CI/CD" or "pipeline" | GitHub Actions, GitLab CI, or other? Deploy on merge to main or manual trigger? |
+| "environments" | How many environments (dev, staging, prod)? Environment parity strategy? |
+| "rollback" | Rollback strategy? Blue-green, canary, or instant rollback? |
+| "secrets" or "config" | Secret management — env vars, vault, or platform-native? Per-environment config strategy? |
+
+---
+
+## AI/ML Integration
+
+| User mentions | Probe with domain knowledge |
+|---|---|
+| "AI" or "LLM" or "model" | Which provider/model? Streaming responses or batch? Fallback strategy? |
+| "embeddings" or "RAG" | Vector store choice? Chunking strategy? Retrieval pipeline? |
+| "fine-tuning" or "training" | Training data pipeline? Evaluation metrics? A/B testing new models? |
+| "prompts" | Prompt versioning? Temperature/parameter management? Cost tracking? |
+| "agents" or "tools" | Tool calling strategy? Human-in-the-loop? Safety guardrails? |
+
+</domain_probes>

package/references/gates.md

@@ -0,0 +1,72 @@
+<gates>
+
+Canonical gate types used across learnship workflows. Every validation checkpoint maps to one of these four types.
+
+---
+
+## Gate Types
+
+### Pre-flight Gate
+**Purpose:** Validates preconditions before starting an operation.
+**Behavior:** Blocks entry if conditions unmet. No partial work created.
+**Recovery:** Fix the missing precondition, then retry.
+**Examples:**
+- plan-phase checks for REQUIREMENTS.md before planning
+- execute-phase validates PLAN.md exists before execution
+- discuss-phase confirms phase exists in ROADMAP.md
+
+### Revision Gate
+**Purpose:** Evaluates output quality and routes to revision if insufficient.
+**Behavior:** Loops back to producer with specific feedback. Bounded by iteration cap.
+**Recovery:** Producer addresses feedback; checker re-evaluates. The loop also escalates early if issue count does not decrease between consecutive iterations (stall detection). After max iterations, escalates unconditionally.
+**Examples:**
+- Plan-checker reviewing PLAN.md (max 3 iterations)
+- Verifier checking phase deliverables against success criteria
+
+### Escalation Gate
+**Purpose:** Surfaces unresolvable issues to the developer for a decision.
+**Behavior:** Pauses workflow, presents options, waits for human input.
+**Recovery:** Developer chooses action; workflow resumes on selected path.
+**Examples:**
+- Revision loop exhausted after 3 iterations
+- Ambiguous requirement needing clarification
+- Security threat requiring human risk acceptance
+
+### Abort Gate
+**Purpose:** Terminates the operation to prevent damage or waste.
+**Behavior:** Stops immediately, preserves state, reports reason.
+**Recovery:** Developer investigates root cause, fixes, restarts from checkpoint.
+**Examples:**
+- Context window critically low during execution
+- STATE.md in error state
+- Verification finds critical missing deliverables
+
+---
+
+## Gate Matrix
+
+| Workflow | Phase | Gate Type | Artifacts Checked | Failure Behavior |
+|----------|-------|-----------|-------------------|------------------|
+| plan-phase | Entry | Pre-flight | REQUIREMENTS.md, ROADMAP.md | Block with missing-file message |
+| plan-phase | Step 6 | Revision | PLAN.md quality | Loop to planner (max 3) |
+| plan-phase | Post-revision | Escalation | Unresolved issues | Surface to developer |
+| execute-phase | Entry | Pre-flight | PLAN.md | Block with missing-plan message |
+| execute-phase | Completion | Revision | SUMMARY.md completeness | Re-run incomplete tasks |
+| verify-work | Entry | Pre-flight | SUMMARY.md | Block with missing-summary |
+| verify-work | Evaluation | Escalation | Failed criteria | Surface gaps to developer |
+| secure-phase | Entry | Pre-flight | SUMMARY.md | Block until phase executed |
+| secure-phase | Threats | Escalation | Open threats | Present to developer for decision |
+| quick | Plan check | Revision | PLAN.md quality | Loop (max 2) |
+
+---
+
+## Applying Gates in Custom Workflows
+
+When creating new workflows:
+
+1. **Every workflow needs at least one pre-flight gate** — check that required inputs exist before starting work
+2. **Any AI-generated output needs a revision gate** — bounded loops prevent infinite regeneration
+3. **Decisions the AI cannot make need escalation gates** — risk acceptance, ambiguous requirements, conflicting constraints
+4. **Resource exhaustion needs abort gates** — context budget, time limits, repeated failures
+
+</gates>

package/references/planning-config.md

@@ -181,4 +181,143 @@ Squash merge is recommended — keeps main branch history clean while preserving
 
 </branching_strategy_behavior>
 
+<v2_config_options>
+
+## v2.0.0 Configuration Options
+
+These options were added in v2.0.0 to support the new compounding, review, ship, and safety workflows.
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `test_first` | `false` | Enable TDD mode — red-green-refactor cycle in executor |
+| `workflow.review` | `true` | Enable the `/review` code review workflow |
+| `workflow.solutions_search` | `true` | Search `.planning/solutions/` for prior art during plan-phase |
+| `review.auto_after_verify` | `false` | Automatically run `/review` after verify-work passes |
+| `ship.auto_test` | `true` | Run tests before shipping |
+| `ship.conventional_commits` | `true` | Use conventional commit format in `/ship` |
+| `ship.pr_template` | `true` | Auto-generate PR description in `/ship` |
+
+</v2_config_options>
+
+<v21_config_options>
+
+## v2.1.0 Configuration Options
+
+New sections and fields added in v2.1.0 for security, parallelization control, gates, and safety.
+
+### Workflow Section (new fields)
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `workflow.security_enforcement` | `true` | Enable per-phase security verification via `/secure-phase` |
+| `workflow.discuss_mode` | `"discuss"` | Discussion mode for discuss-phase |
+| `workflow.tdd_mode` | `false` | Instruct planner to apply `type: tdd` to eligible tasks |
+
+### Parallelization Section (replaces flat boolean)
+
+The `parallelization` field is now an object. Legacy flat `"parallelization": true` is still honored for backward compatibility.
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `parallelization.enabled` | `false` | Enable parallel subagent execution on supported platforms |
+| `parallelization.plan_level` | `true` | Parallelize at plan level (each plan gets its own agent) |
+| `parallelization.task_level` | `false` | Parallelize at task level within a plan (experimental) |
+| `parallelization.max_concurrent_agents` | `5` | Maximum number of concurrent subagents per wave |
+| `parallelization.min_plans_for_parallel` | `2` | Minimum plans in a wave before parallelization activates |
+
+**Why default 5?** Each subagent gets its own context window (~200k tokens). 5 agents is the sweet spot for cost vs. speed — most phases have 2-5 plans per wave. Going higher risks git lock contention and significant cost spikes without proportional speed gains. Configurable for power users.
+
+### Gates Section
+
+Controls which confirmation prompts are shown during workflows. Set to `false` to skip specific confirmations (useful for experienced users in yolo mode).
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `gates.confirm_project` | `true` | Confirm PROJECT.md before proceeding |
+| `gates.confirm_phases` | `true` | Confirm phase breakdown |
+| `gates.confirm_roadmap` | `true` | Confirm roadmap before proceeding |
+| `gates.confirm_plan` | `true` | Confirm plans before execution |
+| `gates.execute_next_plan` | `true` | Confirm before executing each plan |
+| `gates.issues_review` | `true` | Confirm issue resolution approach |
+| `gates.confirm_transition` | `true` | Confirm before phase transitions |
+
+### Safety Section
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `safety.always_confirm_destructive` | `true` | Always confirm before destructive operations (file deletion, git reset) |
+| `safety.always_confirm_external_services` | `true` | Always confirm before calling external APIs or services |
+
+### Hooks Section
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `hooks.context_warnings` | `true` | Show context budget warnings when usage is high |
+
+### Example config.json with all v2.1 options
+
+```json
+{
+  "mode": "interactive",
+  "granularity": "standard",
+  "model_profile": "balanced",
+  "learning_mode": "auto",
+  "test_first": false,
+  "planning": {
+    "commit_docs": true,
+    "commit_mode": "auto",
+    "search_gitignored": false
+  },
+  "workflow": {
+    "research": true,
+    "plan_check": true,
+    "verifier": true,
+    "validation": true,
+    "review": true,
+    "solutions_search": true,
+    "security_enforcement": true,
+    "discuss_mode": "discuss",
+    "tdd_mode": false
+  },
+  "parallelization": {
+    "enabled": false,
+    "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
+  },
+  "ship": {
+    "auto_test": true,
+    "conventional_commits": true,
+    "pr_template": true
+  },
+  "hooks": {
+    "context_warnings": true
+  },
+  "git": {
+    "branching_strategy": "none",
+    "phase_branch_template": "phase-{phase}-{slug}",
+    "milestone_branch_template": "{milestone}-{slug}"
+  }
+}
+```
+
+</v21_config_options>
+
 </planning_config>