learnship 2.0.10 → 2.1.0

package/learnship/workflows/settings.md

@@ -18,11 +18,10 @@ If missing, create from template:
 ```bash
 cp templates/config.json .planning/config.json 2>/dev/null || cat > .planning/config.json << 'EOF'
 {
-  "mode": "yolo",
+  "mode": "interactive",
   "granularity": "standard",
   "model_profile": "balanced",
   "learning_mode": "auto",
-  "parallelization": false,
   "test_first": false,
   "planning": {
     "commit_docs": true,
@@ -35,7 +34,30 @@ cp templates/config.json .planning/config.json 2>/dev/null || cat > .planning/co
     "verifier": true,
     "validation": true,
     "review": true,
-    "solutions_search": 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
@@ -45,6 +67,9 @@ cp templates/config.json .planning/config.json 2>/dev/null || cat > .planning/co
     "conventional_commits": true,
     "pr_template": true
   },
+  "hooks": {
+    "context_warnings": true
+  },
   "git": {
     "branching_strategy": "none",
     "phase_branch_template": "phase-{phase}-{slug}",
@@ -84,12 +109,16 @@ Current configuration:
 [9] Test validation:   [on/off]
 [10] Review workflow:   [on/off]
 [11] Solutions search:  [on/off]
-[12] Auto-review after verify: [on/off]
-[13] Ship: auto-test:   [on/off]
-[14] Ship: conventional commits: [on/off]
-[15] Ship: PR template: [on/off]
-[16] Git branching:     [current] (none | phase | milestone)
-[17] Commit docs:       [on/off]
+[12] Security enforcement: [on/off]
+[13] Auto-review after verify: [on/off]
+[14] Ship: auto-test:   [on/off]
+[15] Ship: conventional commits: [on/off]
+[16] Ship: PR template: [on/off]
+[17] Parallelization:   [on/off] (max agents: [N])
+[18] Git branching:     [current] (none | phase | milestone)
+[19] Commit docs:       [on/off]
+[20] Safety: confirm destructive: [on/off]
+[21] Context warnings:  [on/off]
 
 Enter a number to change a setting, or 'done' to save.
 ```
@@ -222,45 +251,10 @@ Current: [current]. New value? (on/off)
 
 ## Step 5: Save Config
 
-After user types "done", write the updated config:
+After user types "done", read the current config, apply all changes, and write the complete updated JSON. Preserve any fields not shown in the menu (gates, hooks, etc.) — never drop fields the user didn't modify.
 
 ```bash
-cat > .planning/config.json << EOF
-{
-  "mode": "[value]",
-  "granularity": "[value]",
-  "model_profile": "[value]",
-  "learning_mode": "[value]",
-  "parallelization": [true/false],
-  "test_first": [true/false],
-  "planning": {
-    "commit_docs": [true/false],
-    "commit_mode": "[auto/manual]",
-    "search_gitignored": false
-  },
-  "workflow": {
-    "research": [true/false],
-    "plan_check": [true/false],
-    "verifier": [true/false],
-    "validation": [true/false],
-    "review": [true/false],
-    "solutions_search": [true/false]
-  },
-  "review": {
-    "auto_after_verify": [true/false]
-  },
-  "ship": {
-    "auto_test": [true/false],
-    "conventional_commits": [true/false],
-    "pr_template": [true/false]
-  },
-  "git": {
-    "branching_strategy": "[value]",
-    "phase_branch_template": "phase-{phase}-{slug}",
-    "milestone_branch_template": "{milestone}-{slug}"
-  }
-}
-EOF
+node -e "const fs=require('fs');const c=JSON.parse(fs.readFileSync('.planning/config.json','utf8'));/* apply changes to c */;fs.writeFileSync('.planning/config.json',JSON.stringify(c,null,2)+'\n');"
 ```
 
 ## Step 6: Commit

package/learnship/workflows/ship.md

@@ -187,6 +187,8 @@ or patterns while context is fresh.
 ▶ Next steps:
 - Review the PR and request reviews
 - /compound — capture learnings from this work
+- /session-report — generate a session summary for stakeholders
+- /extract-learnings [N] — capture decisions, lessons, patterns from this phase
 ```
 
 ---

package/learnship/workflows/undo.md

@@ -0,0 +1,151 @@
+---
+description: Safe git revert for phase or plan commits — preserves history, checks dependencies
+---
+
+# Undo
+
+Safe git revert workflow. Rolls back phase or plan commits using git revert (NEVER git reset) to preserve history. Includes dependency checks and a confirmation gate.
+
+**Usage:**
+- `undo --last N` — show last N commits for interactive selection
+- `undo --phase NN` — revert all commits for phase NN
+- `undo --plan NN-MM` — revert all commits for plan NN-MM
+
+## Step 1: Parse Arguments
+
+Parse for the undo mode:
+
+- `--last N` — MODE=last, COUNT=N (default 10 if N missing)
+- `--phase NN` — MODE=phase, TARGET_PHASE=NN
+- `--plan NN-MM` — MODE=plan, TARGET_PLAN=NN-MM
+
+If no valid argument, display usage and exit.
+
+## Step 2: Gather Commits
+
+**MODE=last:**
+
+```bash
+git log --oneline --no-merges -${COUNT}
+```
+
+Filter for conventional commits matching `type(scope): message` pattern. Display numbered list. Ask user to select which commits to revert (numbers or "all").
+
+**MODE=phase:**
+
+```bash
+git log --oneline --no-merges --all --grep="(${TARGET_PHASE})" | head -30
+git log --oneline --no-merges --all --grep="phase-${TARGET_PHASE}" | head -30
+```
+
+Collect all commits whose scope references the target phase.
+
+**MODE=plan:**
+
+```bash
+git log --oneline --no-merges --all --grep="(${TARGET_PLAN})" | head -20
+```
+
+Collect all commits whose scope references the target plan.
+
+If no commits found: "No commits found for [target]. Check the phase/plan number."
+
+## Step 3: Dependency Check
+
+For each commit to be reverted, check if later commits depend on the files it modified:
+
+```bash
+for COMMIT in $COMMITS; do
+  FILES=$(git diff-tree --no-commit-id --name-only -r $COMMIT)
+  for FILE in $FILES; do
+    LATER=$(git log --oneline ${COMMIT}..HEAD -- "$FILE" | head -5)
+    if [ -n "$LATER" ]; then
+      echo "WARNING: $FILE was modified in later commits:"
+      echo "$LATER"
+    fi
+  done
+done
+```
+
+If dependencies found, warn:
+```
+WARNING: These commits have downstream dependencies.
+Reverting may break later work. Files affected:
+
+- [file]: modified in [N] later commits
+
+Proceed anyway? [Yes, revert] / [No, cancel]
+```
+
+## Step 4: Confirmation Gate
+
+Display the revert plan:
+```
+Commits to revert ([N] total):
+
+  [hash] [message]
+  [hash] [message]
+
+This will create [N] new revert commits preserving full history.
+
+[Confirm revert] / [Cancel]
+```
+
+Wait for explicit confirmation.
+
+## Step 5: Execute Revert
+
+For each commit in reverse chronological order:
+
+```bash
+git revert --no-commit [hash]
+```
+
+After all reverts staged:
+
+```bash
+git commit -m "revert([scope]): undo [description]
+
+Reverted commits:
+- [hash]: [message]
+- [hash]: [message]"
+```
+
+## Step 6: Update State
+
+If `.planning/STATE.md` exists, add a note about the revert:
+
+```markdown
+### Revert Log
+- [date]: Reverted [N] commits for [target] — [reason if provided]
+```
+
+```bash
+git add .planning/STATE.md
+git commit -m "docs(state): record revert"
+```
+
+## Step 7: Report
+
+```
+learnship > UNDO COMPLETE
+
+Reverted [N] commits for [target].
+New revert commit: [hash]
+
+All original commits preserved in history.
+```
+
+---
+
+## Learning Checkpoint
+
+Read `learning_mode` from `.planning/config.json`.
+
+**If `auto`:**
+
+> **Learning moment:** Needing to undo is a signal worth examining:
+>
+> `@agentic-learning either-or` — What led to needing the undo? Was it a plan deficiency, an execution error, or a changed requirement? Log the reasoning so the pattern is visible next time.
+
+**If `manual`:** Add quietly: *"Tip: `@agentic-learning either-or` to log why the undo was needed."*

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.10",
+  "version": "2.1.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: 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>