learnship 2.0.11 → 2.1.1

package/references/solution-schema.md

@@ -0,0 +1,159 @@
+# Solution Schema Reference
+
+Canonical contract for `.planning/solutions/` frontmatter written by the `/compound` workflow.
+
+Use this file as the quick reference for:
+- Required fields
+- Enum values
+- Validation expectations
+- Category mapping
+- Track classification (bug vs knowledge)
+
+## Tracks
+
+The `problem_type` determines which **track** applies. Each track has different required and optional fields.
+
+| Track | problem_types | Description |
+|-------|--------------|-------------|
+| **Bug** | `build_error`, `test_failure`, `runtime_error`, `performance_issue`, `database_issue`, `security_issue`, `ui_bug`, `integration_issue`, `logic_error` | Defects and failures that were diagnosed and fixed |
+| **Knowledge** | `best_practice`, `documentation_gap`, `workflow_issue`, `developer_experience` | Practices, patterns, workflow improvements, and documentation |
+
+## Required Fields (both tracks)
+
+- **title**: Clear problem/learning title
+- **date**: ISO date in `YYYY-MM-DD`
+- **category**: Category directory from mapping below
+- **module**: Module or area affected
+- **problem_type**: One of the values listed in the Tracks table above
+- **severity**: One of `critical`, `high`, `medium`, `low`
+
+## Optional Fields (both tracks)
+
+- **tags**: Search keywords, lowercase and hyphen-separated
+- **last_updated**: ISO date `YYYY-MM-DD` — added when updating an existing doc
+
+## Bug Track Additional Fields
+
+Optional but recommended:
+- **symptoms**: YAML array with 1-5 observable symptoms (errors, broken behavior)
+- **root_cause**: Brief description of the underlying cause
+- **resolution_type**: One of `code_fix`, `migration`, `config_change`, `test_fix`, `dependency_update`, `environment_setup`, `workflow_improvement`, `documentation_update`, `tooling_addition`
+
+## Knowledge Track Additional Fields
+
+Optional:
+- **applies_when**: Conditions or situations where this guidance applies
+
+## Category Mapping
+
+Map from `problem_type` to `.planning/solutions/` subdirectory:
+
+- `build_error` → `.planning/solutions/build-errors/`
+- `test_failure` → `.planning/solutions/test-failures/`
+- `runtime_error` → `.planning/solutions/runtime-errors/`
+- `performance_issue` → `.planning/solutions/performance-issues/`
+- `database_issue` → `.planning/solutions/database-issues/`
+- `security_issue` → `.planning/solutions/security-issues/`
+- `ui_bug` → `.planning/solutions/ui-bugs/`
+- `integration_issue` → `.planning/solutions/integration-issues/`
+- `logic_error` → `.planning/solutions/logic-errors/`
+- `best_practice` → `.planning/solutions/best-practices/`
+- `workflow_issue` → `.planning/solutions/workflow-issues/`
+- `developer_experience` → `.planning/solutions/developer-experience/`
+- `documentation_gap` → `.planning/solutions/documentation-gaps/`
+
+## Bug Track Template
+
+```markdown
+---
+title: [Clear problem title]
+date: [YYYY-MM-DD]
+category: [category directory]
+module: [module or area]
+problem_type: [enum value]
+severity: [critical|high|medium|low]
+tags: [keyword-one, keyword-two]
+---
+
+# [Clear problem title]
+
+## Problem
+[1-2 sentence description of the issue and impact]
+
+## Symptoms
+- [Observable symptom or error]
+
+## What Didn't Work
+- [Attempted fix and why it failed]
+
+## Solution
+[The fix that worked, including code snippets]
+
+## Why This Works
+[Root cause explanation and why the fix addresses it]
+
+## Prevention
+- [Concrete practice, test, or guardrail]
+
+## Related
+- [Related docs or issues, if any]
+```
+
+## Knowledge Track Template
+
+```markdown
+---
+title: [Clear, descriptive title]
+date: [YYYY-MM-DD]
+category: [category directory]
+module: [module or area]
+problem_type: [enum value]
+severity: [critical|high|medium|low]
+tags: [keyword-one, keyword-two]
+---
+
+# [Clear, descriptive title]
+
+## Context
+[What situation, gap, or friction prompted this guidance]
+
+## Guidance
+[The practice, pattern, or recommendation with code examples]
+
+## Why This Matters
+[Rationale and impact of following or not following this guidance]
+
+## When to Apply
+- [Conditions or situations where this applies]
+
+## Examples
+[Concrete before/after or usage examples]
+
+## Related
+- [Related docs or issues, if any]
+```
+
+## Validation Rules
+
+1. Determine the track from `problem_type` using the Tracks table
+2. All required fields must be present
+3. Enum fields must match allowed values exactly
+4. `date` must match `YYYY-MM-DD`
+5. `tags` should be lowercase and hyphen-separated
+6. Filename pattern: `[sanitized-problem-slug]-[YYYY-MM-DD].md`
+
+## Overlap Assessment
+
+When existing solutions exist, assess overlap across five dimensions:
+
+1. Problem statement
+2. Root cause
+3. Solution approach
+4. Referenced files
+5. Prevention rules
+
+| Score | Dimensions | Action |
+|-------|-----------|--------|
+| **High** | 4-5 match | Update existing doc, add `last_updated` |
+| **Moderate** | 2-3 match | Create new doc, note overlap |
+| **Low** | 0-1 match | Create new doc normally |

package/references/thinking-models.md

@@ -0,0 +1,61 @@
+<thinking_models>
+
+Structured reasoning models for the **planner** and **plan-checker** agents. Apply these at decision points during plan creation, not continuously. Each model counters a specific failure mode.
+
+## Conflict Resolution
+
+Pre-Mortem and Constraint Analysis both analyze risk at different granularities. Run Constraint Analysis FIRST (identify the hardest constraint), then Pre-Mortem (enumerate failure modes around that constraint and the rest of the plan).
+
+## 1. Pre-Mortem Analysis
+
+**Counters:** Optimistic plan decomposition that ignores failure modes.
+
+Before finalizing this plan, assume it has already failed. List the 3 most likely reasons for failure — missing dependency, wrong decomposition, underestimated complexity — and add mitigation steps or acceptance criteria that would catch each failure early.
+
+## 2. MECE Decomposition
+
+**Counters:** Overlapping tasks (merge conflicts) or gapped tasks (missing requirements).
+
+Verify this task breakdown is MECE at the REQUIREMENT level: (1) list every requirement from the phase goal, (2) confirm each maps to exactly one task's `<done>`, (3) if two tasks modify the same file, confirm they modify DIFFERENT sections or serve DIFFERENT requirements, (4) flag any requirement not covered by any task.
+
+## 3. Constraint Analysis
+
+**Counters:** Deferring the hardest constraint to the last task, causing late-stage failures.
+
+Identify the single hardest constraint in this phase — the one thing that, if it doesn't work, makes everything else irrelevant. Schedule that constraint as Task 1 or 2, not last. If the constraint involves an external API or unfamiliar library, add a spike/proof-of-concept task before the main implementation.
+
+## 4. Reversibility Test
+
+**Counters:** Over-analyzing cheap decisions, under-analyzing costly ones.
+
+For each significant decision in this plan, classify as REVERSIBLE (can change later with low cost) or IRREVERSIBLE (changing later requires migration, breaking changes, or significant rework). Spend analysis time proportional to irreversibility. For irreversible decisions, document the rationale in the plan.
+
+## 5. Curse of Knowledge Counter
+
+**Counters:** Plan-to-executor ambiguity from compressed instructions.
+
+For each `<action>` step, re-read it as if you have NEVER seen this codebase. Is every noun unambiguous (which file? which function? which endpoint?)? Is every verb specific (add WHERE? modify HOW?)? If a step could be interpreted two ways, rewrite it. Include file paths, function names, and expected behavior in every action step.
+
+## 6. Base Rate Neglect Counter
+
+**Counters:** Planners ignoring low-confidence research caveats.
+
+Before finalizing the plan, read ALL `[NEEDS DECISION]` items and LOW-confidence recommendations from RESEARCH.md. For each: either (a) create a checkpoint task to resolve it, or (b) document why the risk is acceptable in the plan's deviation notes. Low-confidence items that are silently accepted become undocumented technical debt.
+
+## Gap Closure Mode: Root-Cause Check
+
+**Applies only when:** Planner enters gap closure mode (triggered by `gaps_found` in VERIFICATION.md).
+
+Before writing the fix plan, apply a single "why" round: Why did this gap occur? Was it a plan deficiency (wrong task), an execution miss (correct task, wrong implementation), or a changed assumption (environment/dependency shift)? The fix plan must target the root cause category, not just the symptom.
+
+---
+
+## When NOT to Think
+
+Skip structured reasoning models when the situation does not benefit from them:
+
+- **Single-task plans** — If the phase has one clear requirement and one obvious task, do not run Pre-Mortem or MECE analysis. Write the task directly.
+- **Well-researched phases** — If RESEARCH.md has HIGH-confidence recommendations for every decision and no `[NEEDS DECISION]` items, skip Base Rate Neglect Counter.
+- **Gap closure plans** — Focus on the Root-Cause Check model only. Skip all others — the original plan already went through them.
+
+</thinking_models>

package/references/universal-anti-patterns.md

@@ -0,0 +1,51 @@
+<universal_anti_patterns>
+
+Rules that apply to ALL workflows and agents. Individual workflows may have additional specific anti-patterns.
+
+---
+
+## Context Budget Rules
+
+1. **Never** read agent definition files (`agents/*.md`) when spawning subagents — `subagent_type` auto-loads them. Reading agent definitions into the orchestrator wastes context for content automatically injected into subagent sessions.
+2. **Never** inline large files into subagent prompts — tell agents to read files from disk instead. Agents have their own context windows.
+3. **Read depth scales with context window** — check `context_window` in `.planning/config.json`. At < 500000: read only frontmatter, status fields, or summaries. At >= 500000: full body reads permitted when content is needed for inline decisions. See `references/context-budget.md` for the complete table.
+4. **Delegate** heavy work to subagents — the orchestrator routes, it does not build, analyze, research, investigate, or verify.
+5. **Proactive pause warning**: If you have already consumed significant context (large file reads, multiple subagent results), warn the user: "Context budget is getting heavy. Consider checkpointing progress."
+
+## File Reading Rules
+
+6. **SUMMARY.md read depth scales with context window** — at context_window < 500000: read frontmatter only from prior phase SUMMARYs. At >= 500000: full body reads permitted for direct-dependency phases. Transitive dependencies (2+ phases back) remain frontmatter-only regardless.
+7. **Never** read full PLAN.md files from other phases — only current phase plans.
+8. **Do not** re-read full file contents when frontmatter is sufficient — frontmatter contains status, key_files, commits, and provides fields.
+
+## Subagent Rules
+
+9. **Always use learnship agent types** (`learnship-executor`, `learnship-planner`, `learnship-phase-researcher`, etc.) — never fall back to generic or built-in agent types. Learnship agents have project-aware prompts and workflow context.
+10. **Do not** re-litigate decisions that are already locked in CONTEXT.md — respect locked decisions unconditionally.
+
+## Questioning Anti-Patterns
+
+11. **Do not** walk through checklists — checklist walking (asking items one by one from a list) is the #1 anti-pattern. Instead, use progressive depth: start broad, dig where interesting.
+12. **Do not** use corporate speak — avoid jargon like "stakeholder alignment", "synergize", "deliverables". Use plain language.
+13. **Do not** apply premature constraints — don't narrow the solution space before understanding the problem. Ask about the problem first, then constrain.
+
+## State Management Anti-Patterns
+
+14. **Always use atomic file writes for STATE.md and ROADMAP.md.** Read the current content, modify, write the whole file. Do not use append-only operations that could corrupt the file on interruption.
+15. **Never** skip STATE.md updates after completing work — downstream workflows depend on accurate state.
+
+## Behavioral Rules
+
+16. **Do not** create artifacts the user did not approve — always confirm before writing new planning documents.
+17. **Do not** modify files outside the workflow's stated scope — check the plan's files_modified list.
+18. **Do not** suggest multiple next actions without clear priority — one primary suggestion, alternatives listed secondary.
+19. **Do not** use `git add .` or `git add -A` — stage specific files only.
+20. **Do not** include sensitive information (API keys, passwords, tokens) in planning documents or commits.
+
+## Error Recovery Rules
+
+21. **Git lock detection**: Before any git operation, if it fails with "Unable to create lock file", check for stale `.git/index.lock` and advise the user to remove it (do not remove automatically).
+22. **Config fallback awareness**: Config loading returns `null` silently on invalid JSON. If your workflow depends on config values, check for null and warn the user: "config.json is invalid or missing — running with defaults."
+23. **Partial state recovery**: If STATE.md references a phase directory that doesn't exist, do not proceed silently. Warn the user and suggest diagnosing the mismatch.
+
+</universal_anti_patterns>

package/templates/agents.md

@@ -21,6 +21,9 @@ collaborators with different strengths.
   The "why" matters more than the "what."
 - **Domain-aware, not domain-faking.** Know the domain of this project. When uncertain about
   domain concepts, say so rather than hallucinate. Getting it wrong here has real consequences.
+- **Stop when confused, not after.** If something is ambiguous, surface it immediately. Present
+  the interpretations. Ask which one. Don't pick silently and run with it — that's how wrong
+  assumptions become wrong code.
 - **Learnings are first-class.** Every significant fix gets a "why it broke" and "what we
   learned." This is non-negotiable.
 - **Swearing is allowed when it lands.** Don't force it. Don't avoid it.
@@ -46,9 +49,13 @@ Decision-making heuristics for navigating ambiguity.
 When something is hard to implement, that's information about the design — not just an
 obstacle to power through. Investigate the resistance before routing around it.
 
-### 2. Minimal Upstream Fix Over Downstream Workaround
+### 2. Minimal Fix, Surgical Change
 
-Fix the root cause. Don't patch symptoms. One fix, one place.
+Fix the root cause, not the symptoms. One fix, one place. Touch only what you must — don't
+"improve" adjacent code, comments, or formatting. Don't refactor things that aren't broken.
+Match existing style, even if you'd do it differently. Every changed line should trace directly
+to the request. When your changes create orphans (unused imports, dead variables), clean those
+up — but don't remove pre-existing dead code unless asked.
 
 ### 3. Preserve Real-World Signal
 
@@ -70,15 +77,19 @@ future guardrails.
 
 When we disagree, the motivation is wanting the project to succeed — not being right.
 
-### 7. One Moving Part at a Time
+### 7. One Thing at a Time, Nothing Extra
 
 When debugging or adding features, change one thing, verify, then move to the next.
-Multi-variable changes obscure what actually fixed the problem.
+Multi-variable changes obscure what actually fixed the problem. Write the minimum code
+that solves the stated problem — no speculative features, no abstractions for single-use
+cases, no "flexibility" that wasn't requested. If 200 lines could be 50, rewrite.
 
-### 8. Code Reads > Code Writes
+### 8. Understand First, Then Change
 
 Read existing code thoroughly before editing. Understand the current design before proposing
-changes. Most bugs come from not understanding what's already there. Read first, always.
+changes. Most bugs come from not understanding what's already there. When something is
+ambiguous and multiple interpretations exist, present them and ask — don't silently pick one.
+If you're confused, stop. Name what's unclear. Ask.
 
 ### 9. Keep Copies in Sync
 
@@ -92,14 +103,61 @@ follow. The map should become territory.
 
 ---
 
+## Request Routing Protocol
+
+**This section is mandatory. Apply it before responding to ANY user message.**
+
+When a user sends a message — whether it's a vague idea, a specific bug report, a feature request, or a detailed technical prompt — you MUST route it through the correct learnship workflow. **Do not make code changes, fix bugs, or implement anything in direct response to a user message.** Every task goes through a workflow.
+
+### Decision tree — apply in order:
+
+**0. Is `/new-project` currently in progress?**
+
+If `.planning/PROJECT.md` does NOT exist but you are currently running `/new-project` (i.e., you have asked "What do you want to build?" and are waiting for answers, or you are in any step of the new-project ceremony): **the user's message is an answer to your workflow question, not a task to route.** Do NOT apply the routing protocol. Continue the `/new-project` ceremony from where you left off.
+
+**1. Is there a `.planning/PROJECT.md`?**
+- **No** → Stop. Tell the user: "No project found. Run `/new-project` to initialize." Do nothing else.
+- **Yes** → Continue to step 2.
+
+**2. Does the user message look like a task, problem, bug, or feature request?**
+(Anything that would result in a code change, file edit, config change, or new capability)
+- **Yes** → Route to step 3. Do NOT start implementing.
+- **No** (pure question, status check, discussion) → Answer normally.
+
+**3. How large/complex is the task?**
+- **Small, self-contained** (estimated < 1 hour, touches ≤ 3 files, no design decisions needed):
+  → Tell the user: "This looks like a quick task. I'll run `/quick` for this — it gives us atomic commits and state tracking without full planning ceremony. Proceed?"
+  → Wait for confirmation, then invoke `/quick "[description]"`.
+- **Medium or uncertain** (design decisions needed, multiple files, touches active phase work):
+  → Tell the user: "This touches phase [N] work. I'll run `/discuss-phase [N]` to capture your intent before planning. Proceed?"
+  → Wait for confirmation, then invoke `discuss-phase`.
+- **Large or cross-cutting** (new capability, affects multiple phases, architectural):
+  → Tell the user: "This is significant scope. Let me check where we are first."
+  → Run `/ls` to show current status, then recommend the right workflow (plan-phase, new-milestone, etc).
+
+**4. Never self-route silently.**
+Always tell the user which workflow you're about to invoke and why, then wait for a "yes" before proceeding. Do not assume consent from a detailed prompt.
+
+### Examples of what NOT to do:
+- User says "the login button is broken" → ❌ Don't fix it directly → ✅ Route to `/quick`
+- User says "I want to add dark mode" → ❌ Don't start implementing → ✅ Route to `discuss-phase`
+- User pastes a detailed spec → ❌ Don't treat it as a command to execute → ✅ Classify size, propose workflow, wait for yes
+- `/new-project` asked "What do you want to build?" and user replies with a detailed description → ❌ Don't treat as a task to route → ✅ It is ANSWER_1. Record it and ask Exchange 2.
+
+---
+
 ## Platform Context
 
 This project uses **learnship**. Key facts:
 
 - All planning artifacts live in `.planning/` — read STATE.md and ROADMAP.md first when unsure where we are
-- The phase loop: `discuss-phase` → `plan-phase` → `execute-phase` → `verify-work` → `review` → `ship` → `compound`
+- The phase loop: `discuss-phase` → `plan-phase` → `execute-phase` → `verify-work` → `/review` → `/ship` → `/compound`
+- Optional per-phase: `/secure-phase` (security verification), `/extract-learnings` (capture meta-knowledge)
+- Recovery: `/forensics` (post-mortem), `/undo` (safe revert)
 - Current status is always in `.planning/STATE.md`
 - Decisions are tracked in `.planning/DECISIONS.md` — read it before proposing approaches that may conflict
+- Compounded solutions live in `.planning/solutions/` — organized by category with YAML frontmatter (module, problem_type, severity, tags). Search these before planning to avoid reinventing known solutions
+- Quick ideas: `/note [text]` for zero-friction capture, `/session-report` for end-of-session summaries
 - Run `/ls` if context is unclear about what phase we're on or what to do next — it shows status and offers to run the next step
 
 ---
@@ -143,6 +201,8 @@ This project uses **learnship**. Key facts:
 
 ## Skills — Operational Knowledge
 
+<!-- LEARNSHIP_SKILLS_BLOCK -->
+
 ### CHANGELOG Discipline
 
 Every significant change gets a dated entry in `CHANGELOG.md` with:
@@ -156,6 +216,19 @@ Architectural and scope decisions are tracked in `.planning/DECISIONS.md`.
 Read it before proposing an approach that has been previously considered.
 When a new decision is made during a session, capture it with `/decision-log`.
 
+### Solutions Store
+
+Compounded solutions live in `.planning/solutions/` — organized by category (build-errors, runtime-errors, best-practices, etc.) with YAML frontmatter for searchability. The `/plan-phase` workflow automatically searches these before planning.
+
+**Run `/compound` after any of these events — do not skip:**
+- Fixing a bug (especially root-cause discoveries)
+- Completing a phase (`execute-phase` → `verify-work` → `/compound`)
+- Shipping a feature (`/ship` → `/compound`)
+- Any aha moment or pattern discovery during development
+- Resolving a debugging session (`/debug` → `/compound`)
+
+Context fades fast. If a solution was worth finding, it's worth capturing.
+
 ---
 
 ## Regressions — What Broke and What We Learned

package/templates/config.json

@@ -1,9 +1,8 @@
 {
-  "mode": "yolo",
+  "mode": "interactive",
   "granularity": "standard",
   "model_profile": "balanced",
   "learning_mode": "auto",
-  "parallelization": false,
   "test_first": false,
   "planning": {
     "commit_docs": true,
@@ -16,7 +15,30 @@
     "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
@@ -26,6 +48,9 @@
     "conventional_commits": true,
     "pr_template": true
   },
+  "hooks": {
+    "context_warnings": true
+  },
   "git": {
     "branching_strategy": "none",
     "phase_branch_template": "phase-{phase}-{slug}",