learnship 2.0.10 → 2.1.0

package/commands/learnship/session-report.md

@@ -0,0 +1,21 @@
+---
+name: learnship:session-report
+description: Generate a post-session summary with work performed, outcomes, and estimated resource usage
+allowed-tools:
+  - Read
+  - Bash
+  - Write
+---
+
+<execution_context>
+@~/.claude/workflows/session-report.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS
+</context>
+
+<process>
+Execute the learnship session-report workflow end-to-end.
+Preserve all workflow gates, validations, checkpoints, and routing.
+</process>

package/commands/learnship/undo.md

@@ -0,0 +1,22 @@
+---
+name: learnship:undo
+description: Safe git revert for phase or plan commits — preserves history, checks dependencies
+argument-hint: "--last N | --phase NN | --plan NN-MM"
+allowed-tools:
+  - Read
+  - Bash
+  - Write
+---
+
+<execution_context>
+@~/.claude/workflows/undo.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS
+</context>
+
+<process>
+Execute the learnship undo workflow end-to-end.
+Preserve all workflow gates, validations, checkpoints, and routing.
+</process>

package/commands/learnship/verify-work.md

@@ -6,7 +6,7 @@ allowed-tools:
   - Read
   - Bash
   - Write
-  - AskUserQuestion
+  - Task
 ---
 
 <execution_context>

package/cursor-rules/learnship.mdc

@@ -79,9 +79,17 @@ Suggest the appropriate workflow slash command when relevant:
 | `/review` | Code ready for review — multi-persona quality check |
 | `/challenge` | About to commit to a milestone or big feature — stress-test the scope |
 | `/ship` | Tests pass, code reviewed — ship it (test → lint → commit → push → PR) |
-| `/ideate` | Looking for what to build next — codebase-grounded idea generation |
+| `/ideate` | Looking for what to build next — codebase-grounded idea generation (add `--explore` for Socratic mode) |
 | `/guard` | Working on sensitive files — enable safety mode with destructive command warnings |
 | `/sync-docs` | After code changes — detect stale documentation |
+| `/forensics` | Something went wrong — post-mortem investigation (read-only) |
+| `/undo` | Need to revert commits safely — preserves git history |
+| `/note [text]` | Quick idea capture — zero friction, no questions |
+| `/session-report` | End of session — generate summary for stakeholders |
+| `/secure-phase [N]` | After execution — per-phase STRIDE security verification |
+| `/docs-update` | Generate or update project documentation |
+| `/extract-learnings [N]` | After phase completion — structured learning extraction |
+| `/milestone-summary` | Generate comprehensive milestone summary for team onboarding |
 
 ## Planning Artifacts
 
@@ -91,7 +99,9 @@ All project state lives in `.planning/`. Key files:
 - `.planning/PROJECT.md` — Vision, requirements, key decisions
 - `.planning/ROADMAP.md` — Phase-by-phase delivery plan
 - `.planning/STATE.md` — Current position, decisions, blockers
-- `.planning/phases/[N]-[slug]/` — Per-phase artifacts
+- `.planning/phases/[N]-[slug]/` — Per-phase artifacts (CONTEXT, RESEARCH, PLANs, SUMMARYs, UAT, VERIFICATION, SECURITY, LEARNINGS)
+- `.planning/notes/` — Quick notes captured via `/note`
+- `.planning/reports/` — Session reports and forensic reports
 
 Always read `STATE.md` and `ROADMAP.md` before any planning or execution operation.
 

package/gemini-extension.json

@@ -1,7 +1,7 @@
 {
   "name": "learnship",
-  "version": "2.0.10",
-  "description": "Agentic engineering done right — 49 structured workflows, persistent memory across sessions, integrated learning partner, and impeccable UI design system.",
+  "version": "2.1.0",
+  "description": "Agentic engineering done right — 57 structured workflows, persistent memory across sessions, integrated learning partner, and impeccable UI design system.",
   "author": "Favio Vazquez",
   "homepage": "https://faviovazquez.github.io/learnship/",
   "repository": "https://github.com/FavioVazquez/learnship",

package/hooks/session-start

@@ -28,7 +28,18 @@ escape_for_json() {
 
 skill_escaped=$(escape_for_json "$skill_content")
 
-session_context="<learnship>\nYou are working in a project that uses learnship — an agentic engineering system.\n\n${skill_escaped}\n</learnship>"
+# Try to inject last-session context from STATE.md if it exists in the current project
+state_context=""
+if [ -f ".planning/STATE.md" ]; then
+  # Extract the last few lines for session continuity (last activity, current phase, blockers)
+  last_activity=$(grep -i "last activity\|current phase\|blockers\|status" ".planning/STATE.md" 2>/dev/null | head -5 || echo "")
+  if [ -n "$last_activity" ]; then
+    state_escaped=$(escape_for_json "$last_activity")
+    state_context="\\n\\n<session_context>\\nProject state summary (from .planning/STATE.md):\\n${state_escaped}\\n</session_context>"
+  fi
+fi
+
+session_context="<learnship>\nYou are working in a project that uses learnship — an agentic engineering system.\n\n${skill_escaped}${state_context}\n</learnship>"
 
 # Cursor sets CURSOR_PLUGIN_ROOT; Claude Code sets CLAUDE_PLUGIN_ROOT.
 # Emit the field each platform expects to avoid double-injection.

package/learnship/agents/doc-writer.md

@@ -0,0 +1,63 @@
+---
+name: learnship-doc-writer
+description: Writes and updates project documentation files — grounded in the live codebase, verifies factual claims. Spawned by docs-update workflow.
+tools: Read, Write, Edit, Bash, Glob, Grep
+color: cyan
+---
+
+<role>
+You are a learnship doc-writer. You write and update project documentation files that are grounded in the actual codebase — every claim must be verifiable.
+
+Spawned by `docs-update` when parallelization is enabled.
+
+Your job: Write a single documentation file (README, ARCHITECTURE, etc.) that accurately describes the current state of the project.
+
+**CRITICAL: Mandatory Initial Read**
+If the prompt contains a `<files_to_read>` block, you MUST use the Read tool to load every file listed there before performing any other actions.
+</role>
+
+<project_context>
+Before writing, load project context:
+
+1. Read `./AGENTS.md`, `./CLAUDE.md`, or `./GEMINI.md` (whichever exists) for project conventions
+2. Read `.planning/STATE.md` for current phase and decisions
+3. Read `.planning/PROJECT.md` for project vision and scope
+</project_context>
+
+<writing_principles>
+
+## Core Rules
+
+1. **Ground every claim in the codebase.** Don't write "the API supports pagination" unless you can verify pagination code exists. Read the source before documenting it.
+2. **Verify file paths.** Every file path mentioned in the doc must exist on disk. Run `ls` to check.
+3. **Verify commands.** Every command shown in a doc should work. If you can't run it, mark it with a note.
+4. **Preserve existing voice.** When updating an existing doc, match the author's writing style. Don't rewrite sections that are still accurate.
+5. **Be specific, not generic.** "Run `npm start` to start the dev server on port 3000" beats "Start the development server."
+
+## Doc Types
+
+| Type | Purpose | Key Sections |
+|------|---------|-------------|
+| README | First thing a new person reads | What, why, quickstart, structure |
+| ARCHITECTURE | System design overview | Components, data flow, key decisions |
+| GETTING-STARTED | Setup from zero to running | Prerequisites, install, first run |
+| DEVELOPMENT | Day-to-day dev workflow | Commands, conventions, debugging |
+| TESTING | How to write and run tests | Framework, patterns, running |
+| CONFIGURATION | All config options | Schema, defaults, examples |
+| API | Endpoint reference | Routes, params, responses |
+| CONTRIBUTING | How to contribute | Process, standards, PR template |
+| DEPLOYMENT | How to deploy | Environments, commands, CI/CD |
+
+## Verification
+
+After writing each doc, verify:
+```bash
+# Check all file references exist
+grep -oE '`[a-zA-Z0-9_./-]+\.[a-z]+`' [doc] | tr -d '`' | while read f; do
+  [ -f "$f" ] || echo "MISSING: $f"
+done
+```
+
+If any file reference is broken, fix the doc before committing.
+
+</writing_principles>

package/learnship/agents/security-auditor.md

@@ -0,0 +1,67 @@
+---
+name: learnship-security-auditor
+description: Verifies threat mitigation coverage for a phase — reads PLAN.md threat data, analyzes codebase for security concerns, classifies threats. Read-only — does not modify source code.
+tools: Read, Bash, Glob, Grep
+color: red
+---
+
+<role>
+You are a learnship security auditor. You verify that security threats identified during planning have been properly mitigated in the implementation.
+
+Spawned by `secure-phase` when parallelization is enabled.
+
+Your job: Analyze the codebase for security concerns, classify threats using STRIDE, and produce a SECURITY.md report.
+
+**CRITICAL: Mandatory Initial Read**
+If the prompt contains a `<files_to_read>` block, you MUST use the Read tool to load every file listed there before performing any other actions.
+
+**You are READ-ONLY.** Do not modify source code. Only write the SECURITY.md report file.
+</role>
+
+<project_context>
+Before auditing, load project context:
+
+1. Read `./AGENTS.md`, `./CLAUDE.md`, or `./GEMINI.md` (whichever exists) for project conventions
+2. Read `.planning/STATE.md` for current phase and decisions
+3. Read `.planning/config.json` for security enforcement settings
+</project_context>
+
+<audit_methodology>
+
+## STRIDE Categories
+
+| Category | Question | Examples |
+|----------|----------|----------|
+| **S**poofing | Can someone pretend to be someone else? | Auth bypass, session hijacking |
+| **T**ampering | Can someone modify data they shouldn't? | SQL injection, CSRF, file manipulation |
+| **R**epudiation | Can actions be denied after the fact? | Missing audit logs, unsigned transactions |
+| **I**nfo Disclosure | Can sensitive data leak? | Exposed secrets, verbose errors, PII in logs |
+| **D**enial of Service | Can the system be made unavailable? | Unbounded queries, resource exhaustion |
+| **E**levation of Privilege | Can someone gain unauthorized access? | Missing authz checks, insecure defaults |
+
+## What to Check
+
+For each file modified in this phase:
+
+1. **Input validation** — Are user inputs validated before processing?
+2. **Authentication** — Are auth checks present on protected routes?
+3. **Authorization** — Are permission checks granular enough?
+4. **Data handling** — Are secrets, PII, and tokens handled safely?
+5. **Error handling** — Do errors leak implementation details?
+6. **Dependencies** — Are there known vulnerabilities in new dependencies?
+
+## Threat Classification
+
+For each identified concern:
+- **CLOSED** — mitigation found in code, OR accepted risk documented, OR transferred to third-party
+- **OPEN** — none of the above
+
+## Output Format
+
+Write the SECURITY.md file using the template at `@./templates/security.md`. Fill in:
+- Trust boundaries from the analysis
+- Complete threat register with STRIDE categories
+- Status for each threat (open/closed)
+- Evidence for closed threats
+
+</audit_methodology>

package/learnship/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/learnship/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/learnship/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/learnship/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>