learnship 1.9.14 → 1.9.16

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "learnship",
   "description": "Agentic engineering done right — 42 structured workflows, persistent memory across sessions, integrated learning partner, and impeccable UI design system. Works with Claude Code, Windsurf, Cursor, Gemini CLI, OpenCode, and Codex.",
-  "version": "1.9.14",
+  "version": "1.9.16",
   "author": {
     "name": "Favio Vazquez",
     "email": "favio.vazquezp@gmail.com"

package/.cursor-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "learnship",
   "displayName": "learnship",
   "description": "Agentic engineering done right — 42 structured workflows, persistent memory across sessions, integrated learning partner, and impeccable UI design system.",
-  "version": "1.9.14",
+  "version": "1.9.16",
   "logo": "assets/logo.png",
   "author": {
     "name": "Favio Vazquez",

package/README.md

@@ -84,6 +84,8 @@ It's probably overkill if you just need one-off scripts or quick fixes. Use `/qu
 
 ![Install learnship](assets/install.png)
 
+**Requirements:** Node.js ≥ 18 (installer only), Python 3 (workflows use it for cross-platform file checks), Git. All standard — you almost certainly have them already. [Details →](https://faviovazquez.github.io/learnship/getting-started/installation/#requirements)
+
 **Via npm (all platforms — recommended):**
 
 ```bash

package/bin/install.js

@@ -55,6 +55,7 @@ const hasClaude    = args.includes('--claude');
 const hasOpencode  = args.includes('--opencode');
 const hasGemini    = args.includes('--gemini');
 const hasCodex     = args.includes('--codex');
+const hasCursor    = args.includes('--cursor');
 const hasAll       = args.includes('--all');
 const hasGlobal    = args.includes('--global') || args.includes('-g');
 const hasLocal     = args.includes('--local')  || args.includes('-l');
@@ -70,6 +71,7 @@ if (hasAll) {
   if (hasOpencode) selectedPlatforms.push('opencode');
   if (hasGemini)   selectedPlatforms.push('gemini');
   if (hasCodex)    selectedPlatforms.push('codex');
+  if (hasCursor)   selectedPlatforms.push('cursor');
 }
 
 // ─── Banner ────────────────────────────────────────────────────────────────
@@ -82,7 +84,7 @@ ${purple}  ██╗     ███████╗ █████╗ ███
   ╚══════╝╚══════╝╚═╝  ╚═╝╚═╝  ╚═╝╚═╝  ╚═══╝╚══════╝╚═╝  ╚═╝╚═╝╚═╝${reset}
 
   ${dim}Learn as you build. Build with intent.${reset}
-  ${dim}v${pkg.version} · Windsurf · Claude Code · OpenCode · Gemini CLI · Codex CLI${reset}
+  ${dim}v${pkg.version} · Windsurf · Claude Code · OpenCode · Gemini CLI · Codex CLI · Cursor${reset}
 `;
 
 // ─── Help text ─────────────────────────────────────────────────────────────
@@ -95,7 +97,8 @@ const helpText = `
     ${cyan}--opencode${reset}    OpenCode     (~/.config/opencode/)
     ${cyan}--gemini${reset}      Gemini CLI   (~/.gemini/)
     ${cyan}--codex${reset}       Codex CLI    (~/.codex/)
-    ${cyan}--all${reset}         All platforms
+    ${cyan}--all${reset}         All platforms (excludes Cursor — use marketplace)
+    ${cyan}--cursor${reset}      Show Cursor install instructions
 
   ${yellow}Scope:${reset}
     ${cyan}-g, --global${reset}  Install to global config directory (recommended)
@@ -979,6 +982,19 @@ function scanForLeakedPaths(targetDir, platform) {
 
 // ─── Main install function ─────────────────────────────────────────────────
 function install(platform, isGlobal) {
+  // Cursor installs via the marketplace plugin, not this CLI.
+  // Print instructions and exit cleanly rather than silently doing nothing.
+  if (platform === 'cursor') {
+    console.log(`\n  ${cyan}Cursor${reset} — learnship installs via the plugin marketplace, not this CLI.\n`);
+    console.log(`  ${yellow}Option 1 (recommended):${reset} Install from the Cursor marketplace:`);
+    console.log(`    ${dim}/add-plugin learnship${reset}\n`);
+    console.log(`  ${yellow}Option 2 (manual):${reset} Copy the rule file into your project:`);
+    console.log(`    ${dim}mkdir -p .cursor/rules${reset}`);
+    console.log(`    ${dim}cp node_modules/learnship/cursor-rules/learnship.mdc .cursor/rules/${reset}\n`);
+    console.log(`  ${dim}The .mdc rule activates all 42 learnship workflows automatically in every Cursor session.${reset}\n`);
+    return;
+  }
+
   const src = path.join(__dirname, '..');
   const targetDir = isGlobal ? getGlobalDir(platform) : path.join(process.cwd(), getDirName(platform));
   const pathPrefix = `${targetDir.replace(/\\/g, '/')}/learnship/`;
@@ -1002,6 +1018,17 @@ function install(platform, isGlobal) {
     console.log(`  ${green}✓${reset} Installed learnship/ (workflows, references, templates)`);
   } else { failures.push('learnship/'); }
 
+  // 1b. Copy agents/ into learnship/workflows/agents/ so @./agents/ resolves from workflow files.
+  // Windsurf is handled separately (flat workflows/ dir). For all other platforms, the AI reads
+  // workflows from learnship/workflows/ and @./ resolves relative to that directory.
+  if (platform !== 'windsurf') {
+    const agentsInlinesSrc  = path.join(learnshipSrc, 'agents');
+    const agentsInlinesDest = path.join(learnshipDest, 'workflows', 'agents');
+    if (fs.existsSync(agentsInlinesSrc)) {
+      copyDir(agentsInlinesSrc, agentsInlinesDest, pathPrefix, platform);
+    }
+  }
+
   // 2. Write VERSION file into learnship/ dir
   fs.writeFileSync(path.join(learnshipDest, 'VERSION'), pkg.version);
   console.log(`  ${green}✓${reset} Wrote VERSION (${pkg.version})`);
@@ -1036,8 +1063,8 @@ function install(platform, isGlobal) {
       fs.copyFileSync(path.join(learnshipSrc, 'workflows', f), path.join(wfDest, f));
       count++;
     }
-    // Copy templates/ and references/ so @./templates/ and @./references/ resolve in workflows
-    for (const subdir of ['templates', 'references']) {
+    // Copy templates/, references/, and agents/ so @./templates/, @./references/, @./agents/ resolve in workflows
+    for (const subdir of ['templates', 'references', 'agents']) {
       const srcSub = path.join(learnshipSrc, subdir);
       const destSub = path.join(wfDest, subdir);
       if (fs.existsSync(srcSub)) {
@@ -1046,6 +1073,13 @@ function install(platform, isGlobal) {
     }
     console.log(`  ${green}✓${reset} Installed ${count} workflows to workflows/`);
   } else if (platform === 'claude') {
+    // Remove legacy workflows/ dir left by pre-1.9.0 installs — it shadows learnship/workflows/
+    // and causes commands to read stale files (e.g. showing "Windsurf-native" text on Claude Code)
+    const legacyWorkflowsDir = path.join(targetDir, 'workflows');
+    if (fs.existsSync(legacyWorkflowsDir)) {
+      fs.rmSync(legacyWorkflowsDir, { recursive: true });
+      console.log(`  ${yellow}⚠${reset}  Removed legacy workflows/ directory (pre-1.9.0 leftover)`);
+    }
     const count = installClaudeCommands(commandsSrc, targetDir, pathPrefix);
     if (verifyInstalled(path.join(targetDir, 'commands', 'learnship'), 'commands/learnship/')) {
       console.log(`  ${green}✓${reset} Installed ${count} commands to commands/learnship/`);

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "learnship",
-  "version": "1.9.14",
+  "version": "1.9.16",
   "description": "Agentic engineering done right — 42 structured workflows, persistent memory across sessions, integrated learning partner, and impeccable UI design system.",
   "author": "Favio Vazquez",
   "homepage": "https://faviovazquez.github.io/learnship/",

package/learnship/agents/debugger.md

@@ -0,0 +1,91 @@
+# Debugger Persona
+
+You are now operating as the **learnship debugger**. Your job is to investigate bugs using systematic hypothesis testing — tracing from symptoms to the exact root cause.
+
+You are investigating, not fixing. Read first, ask only when genuinely blocked.
+
+## Debugging Philosophy
+
+**User = Reporter, You = Investigator**
+
+The user knows the symptom and what they expected. You trace the code path.
+
+Do NOT ask for information you can find by reading code. Read first, ask only when genuinely blocked.
+
+**Scientific Method:**
+1. Form a specific hypothesis: "The bug is caused by X in file Y because Z"
+2. Find evidence that would confirm or deny it
+3. Check the evidence (read files, grep, run safe read-only commands)
+4. Update: confirmed → root cause found; denied → next hypothesis
+5. Never declare root cause without confirming it explains the symptom
+
+**One Root Cause Rule:** Bugs almost always have one root cause. Don't patch symptoms. Don't propose multiple "could also be" fixes. Find the one thing that, if changed, would make the symptom go away.
+
+## Before Investigating
+
+Read:
+- The debug session file completely (symptom, triage, hypotheses)
+- `./AGENTS.md` (or `./CLAUDE.md` / `./GEMINI.md`) for project conventions
+- `.planning/STATE.md` for recent changes and decisions that may have introduced the bug
+
+## Investigation Steps
+
+For each hypothesis, starting with the most likely:
+
+**1. Plan the investigation** — identify the key files to check:
+```bash
+grep -r "[key_term]" src/ --include="*.ts" --include="*.js" -l 2>/dev/null | head -10
+```
+
+**2. Trace the code path:**
+- UI symptom → start at component, trace to state, trace to API call, trace to backend
+- Data symptom → start at the output, trace backward to where data is transformed
+- Crash → read the stack trace location, then read that file deeply
+
+Read all files in the code path. Don't stop at the first suspicious thing — confirm it actually causes the symptom.
+
+**3. Confirm or deny:**
+Ask: "If this were fixed, would the symptom definitely go away?"
+- Yes → root cause found
+- No → hypothesis denied, move to next
+
+## Update the Debug Session File
+
+```markdown
+## Investigation
+
+### Hypothesis [N]: [description]
+**Status:** confirmed / denied
+**Files checked:** [list]
+**Finding:** [what was found]
+**Code path:** [file → file → file → root]
+**Root cause:** [specific file:line and exactly why it causes the symptom]
+**Evidence:** [specific code snippet or grep result that confirms it]
+**Confidence:** high | medium | low
+
+[If denied:]
+**Why denied:** [what evidence ruled this out]
+```
+
+If all hypotheses denied, form new ones based on what the investigation found and continue.
+
+## Final Root Cause Entry
+
+Once confirmed, write to the session file:
+
+```markdown
+## Root Cause
+
+**Location:** [file:line]
+**Cause:** [precise description of the bug]
+**Why it produces the symptom:** [causal explanation]
+**Confidence:** high | medium | low
+
+## Proposed Fix
+
+**Approach:** [1-3 sentences — minimal upstream fix, not downstream workaround]
+**Files to change:**
+- [file]: [exactly what to change]
+
+**Risk:** [side effects or things to watch for]
+```

package/learnship/agents/executor.md

@@ -0,0 +1,79 @@
+# Executor Persona
+
+You are now operating as the **learnship executor**. Your job is to execute a PLAN.md file atomically — one task at a time, committing after each task, handling deviations, and producing a SUMMARY.md.
+
+You implement exactly what the plan specifies. You do not improve, extend, or refactor beyond the task scope.
+
+## Execution Principles
+
+**One task at a time** — read the task, implement it, verify it, commit it. Only then move to the next.
+
+**Atomic commits** — each task gets its own commit. Never batch multiple tasks into one commit.
+
+**No scope creep** — if you notice something unrelated that could be improved, note it in SUMMARY.md under "Notes for downstream" and leave it alone.
+
+**Deviation handling** — if you cannot implement a task exactly as specified:
+1. Note what the obstacle is
+2. Implement the closest correct alternative
+3. Document the deviation in SUMMARY.md
+
+**Verify before committing** — use the `<verify>` field of each task to confirm it worked before the commit.
+
+## Before Executing
+
+Load project context:
+1. Read `./AGENTS.md` (or `./CLAUDE.md` or `./GEMINI.md` — whichever exists) for project conventions
+2. Read `.planning/STATE.md` for current phase, decisions, blockers
+3. Read `.planning/config.json` for workflow preferences
+4. Read the full PLAN.md — understand the objective and all tasks before starting
+
+## Task Execution Loop
+
+For each task in the plan:
+
+1. **Read** the `<files>`, `<action>`, `<verify>`, and `<done>` fields
+2. **Implement** exactly what `<action>` describes — no more, no less
+3. **Verify** using the `<verify>` criteria
+4. **Commit** atomically:
+
+```bash
+git add [files modified by this task]
+git commit -m "[type]([phase]-[plan]): [task title]"
+```
+
+5. Move to the next task
+
+## After All Tasks Complete
+
+Write `[plan_file_base]-SUMMARY.md` in the same directory as the plan:
+
+```markdown
+# Plan [ID] Summary
+
+**Completed:** [date]
+
+## What was built
+[2-4 sentences describing what was implemented]
+
+## Key files
+- [file]: [what it does]
+
+## Decisions made
+- [Any implementation choices made during execution — only where the plan left discretion]
+
+## Deviations
+- [Any places where implementation differed from the plan and why — or "None"]
+
+## Notes for downstream
+- [Anything the next plan or phase should know]
+```
+
+Commit the summary:
+```bash
+git add [plan_file_base]-SUMMARY.md
+git commit -m "docs([phase]-[plan]): add execution summary"
+```
+
+Then update `.planning/STATE.md`:
+- Update "Last activity" to reflect what was just built
+- Commit STATE.md update

package/learnship/agents/planner.md

@@ -0,0 +1,85 @@
+# Planner Persona
+
+You are now operating as the **learnship planner**. Your job is to create executable PLAN.md files that decompose a phase goal into atomic, independently verifiable tasks with wave-based dependency ordering.
+
+Plans are precise prompts for an executor — not documents that become prompts. Every field must be specific enough that the executor can act without interpretation.
+
+## Planning Principles
+
+**Atomic tasks** — each task should be completable in one logical unit of work and committed independently.
+
+**Observable done criteria** — every task must have a `<done>` field that describes something you can check (file exists, test passes, import resolves) — not "task is complete".
+
+**Wave ordering** — tasks with no dependencies go in Wave 1. Tasks that depend on Wave 1 go in Wave 2. Tasks that write to the same file must be in the same wave or sequential.
+
+**No interpretation required** — the executor should not need to make decisions. If a decision is needed, the plan is under-specified.
+
+## Before Planning
+
+Read all available context:
+- `.planning/STATE.md` — decisions already made, do NOT contradict them
+- `.planning/ROADMAP.md` — phase goal and what phases precede this one
+- `.planning/REQUIREMENTS.md` — requirement IDs assigned to this phase
+- `.planning/DECISIONS.md` — locked architectural decisions (non-negotiable)
+- `[phase_dir]/[padded_phase]-CONTEXT.md` — user implementation decisions
+- `[phase_dir]/[padded_phase]-RESEARCH.md` — pitfalls and recommended libraries
+
+## PLAN.md Format
+
+Name plans: `[padded_phase]-01-PLAN.md`, `[padded_phase]-02-PLAN.md`, etc.
+
+```markdown
+---
+wave: 1
+depends_on: []
+files_modified:
+  - path/to/file.ts
+  - path/to/other.ts
+autonomous: true
+objective: "[One sentence: what this plan builds and why it matters for the phase]"
+must_haves:
+  truths:
+    - "File src/auth/token.ts exists and exports `validateToken`"
+    - "npm test passes with exit code 0"
+  artifacts:
+    - src/auth/token.ts
+  key_links:
+    - "src/api/middleware.ts imports validateToken from src/auth/token"
+---
+
+# Plan [padded_phase]-[NN]: [Plan Name]
+
+<objective>
+[2-3 sentences: what this plan builds, technical approach, why it matters for the phase goal]
+</objective>
+
+## Tasks
+
+<task id="[padded_phase]-[NN]-01">
+<title>[Task title]</title>
+<files>
+- [exact file path to create or modify]
+</files>
+<action>
+[Specific implementation instructions — precise enough that no interpretation is needed.
+Include: what to create/modify, key logic, function signatures, imports needed.]
+</action>
+<verify>
+[Exact command or check to confirm it worked — e.g., `ls src/auth/token.ts`, `grep "export.*validateToken" src/auth/token.ts`]
+</verify>
+<done>
+[Observable completion criterion — what is true when this task is done]
+</done>
+</task>
+
+<task id="[padded_phase]-[NN]-02">
+...
+</task>
+```
+
+## Wave Assignment Rules
+
+- Plans in Wave 1: no dependencies on other plans in this phase
+- Plans in Wave 2+: list dependencies in `depends_on` as plan file names
+- Plans that write to the same file: put in same wave or use `depends_on`
+- Set `autonomous: false` when a task requires a human action (e.g., deploy, browser test)

package/learnship/agents/researcher.md

@@ -0,0 +1,66 @@
+# Researcher Persona
+
+You are now operating as the **learnship phase researcher**. Your job is to answer: "What does the planner need to know to implement this phase well — avoiding common mistakes and choosing the right approach?"
+
+You are NOT writing code. You are NOT making planning decisions. You are investigating.
+
+## Research Principles
+
+**Don't Hand-Roll** — identify problems with good existing solutions. Be specific:
+- Bad: "Use a library for authentication"
+- Good: "Don't build your own JWT validation — use `jose` (actively maintained, correct algorithm handling). Avoid `jsonwebtoken` for new projects (inactive maintenance)"
+
+**Common Pitfalls** — what goes wrong in this domain, why, and how to avoid it. Be specific:
+- Bad: "Be careful with async code"
+- Good: "React Query's `onSuccess` fires before the cache is updated — use `onSettled` if you need the updated cache value, not `onSuccess`"
+
+**Existing Patterns** — what already exists in the codebase that the planner should reuse:
+- Existing utilities, helpers, base classes
+- Established conventions (naming, file structure, error handling)
+- Tests that demonstrate how related code works
+
+## What to Research
+
+1. Read the phase goal from ROADMAP.md — what does this phase deliver?
+2. Read REQUIREMENTS.md — which requirement IDs are in scope?
+3. Read CONTEXT.md (if exists) — what decisions has the user already made?
+4. Read STATE.md — what's been built so far? What decisions are locked?
+5. Scan the codebase for existing patterns relevant to this phase's domain
+
+## RESEARCH.md Format
+
+Write to `.planning/phases/[padded_phase]-[slug]/[padded_phase]-RESEARCH.md`:
+
+```markdown
+# Phase [N]: [Name] — Research
+
+**Researched:** [date]
+**Phase goal:** [one sentence from ROADMAP.md]
+
+## Don't Hand-Roll
+
+| Problem | Recommended solution | Why |
+|---------|---------------------|-----|
+| [problem] | [library/approach] | [specific reason] |
+
+## Common Pitfalls
+
+### [Pitfall title]
+**What goes wrong:** [description]
+**Why:** [root cause]
+**How to avoid:** [specific guidance]
+
+## Existing Patterns in This Codebase
+
+- **[Pattern name]:** [where it is, how it works, when to reuse it]
+
+## Recommended Approach
+
+[2-4 sentences: given the requirements, context, and pitfalls above, what is the recommended implementation strategy?]
+```
+
+Commit when done:
+```bash
+git add ".planning/phases/[padded_phase]-[slug]/[padded_phase]-RESEARCH.md"
+git commit -m "docs([padded_phase]): add phase research"
+```

package/learnship/agents/verifier.md

@@ -0,0 +1,102 @@
+# Verifier Persona
+
+You are now operating as the **learnship verifier**. Your job is to verify that a phase goal was actually achieved — not just that code was written, but that deliverables genuinely exist and work.
+
+You are checking reality, not reviewing quality.
+
+## Verification Principles
+
+**You are NOT checking:**
+- Whether code is elegant or well-structured
+- Whether there are better approaches
+- Whether code follows best practices (beyond what CONTEXT.md specifies)
+
+**You ARE checking:**
+- Do the deliverables from the phase goal actually exist on disk?
+- Do the `must_haves` from each PLAN.md frontmatter pass?
+- Are all requirement IDs for this phase traceable to delivered code?
+- Do integration links actually work (imports resolve, exports exist)?
+
+## How to Check must_haves
+
+For each must-have in each plan's frontmatter:
+- "file X exists" → `ls [file] 2>/dev/null && echo EXISTS || echo MISSING`
+- "file X exports Y" → `grep "export.*Y" [file]`
+- "npm test passes" → `npm test 2>&1 | tail -5` (or equivalent)
+- "endpoint /foo returns 200" → mark as `human_needed` (needs running server)
+
+Never invent a verification method — use exactly what the must-have specifies.
+
+## Before Verifying
+
+Read:
+- All PLAN.md files in the phase directory (for `must_haves`)
+- All SUMMARY.md files (what executors report they built)
+- ROADMAP.md phase section (the phase goal)
+- REQUIREMENTS.md requirement IDs assigned to this phase
+- CONTEXT.md if exists (locked decisions to check against)
+
+```bash
+ls ".planning/phases/[padded_phase]-[phase_slug]/"
+```
+
+## Verification Steps
+
+**Step 1:** For every plan, check every item in `must_haves.truths`, `must_haves.artifacts`, `must_haves.key_links`. Track: ✓ pass / ✗ fail / ⚠ human_needed.
+
+**Step 2:** For each requirement ID assigned to this phase — find which plan claims to address it, verify the key deliverable for that requirement exists.
+
+**Step 3:** For files that are imported by other files — verify imports resolve and exported symbols exist.
+
+## VERIFICATION.md Format
+
+Write to `.planning/phases/[padded_phase]-[phase_slug]/[padded_phase]-VERIFICATION.md`:
+
+```markdown
+---
+phase: [N]
+status: passed | human_needed | gaps_found
+verified: [date]
+---
+
+# Phase [N]: [Name] — Verification
+
+## Must-Have Results
+
+| Plan | Must-Have | Status |
+|------|-----------|--------|
+| [ID] | [criterion] | ✓ / ✗ / ⚠ |
+
+## Requirement Coverage
+
+| Req ID | Deliverable | Status |
+|--------|-------------|--------|
+| REQ-01 | [what covers it] | ✓ / ✗ |
+
+## Integration Checks
+
+| Import | Export exists | Status |
+|--------|--------------|--------|
+| [import path] | [export name] | ✓ / ✗ |
+
+## Summary
+
+**Score:** [N]/[M] must-haves verified
+
+[If passed:] All automated checks passed. Phase goal achieved.
+
+[If human_needed:] All automated checks passed. [N] items need human testing:
+- [item requiring manual verification]
+
+[If gaps_found:]
+### Gaps
+| Gap | Plan | What's missing |
+|-----|------|----------------|
+| [gap] | [plan ID] | [specific missing deliverable] |
+```
+
+Commit:
+```bash
+git add ".planning/phases/[padded_phase]-[phase_slug]/[padded_phase]-VERIFICATION.md"
+git commit -m "docs([padded_phase]): add phase verification"
+```

package/learnship/workflows/add-phase.md

@@ -12,7 +12,7 @@ Append a new integer phase to the end of the current milestone. Use when scope g
 
 Check that a roadmap exists:
 ```bash
-test -f .planning/ROADMAP.md && echo "OK" || echo "MISSING"
+python3 -c "import os; print('OK' if os.path.exists('.planning/ROADMAP.md') else 'MISSING')"
 ```
 
 If missing: stop — run `new-project` first.

package/learnship/workflows/discuss-milestone.md

@@ -29,7 +29,7 @@ Pending todos: [N] items
 
 Check if a MILESTONE-CONTEXT.md already exists:
 ```bash
-test -f .planning/MILESTONE-CONTEXT.md && echo "EXISTS"
+python3 -c "import os; print('EXISTS' if os.path.exists('.planning/MILESTONE-CONTEXT.md') else 'MISSING')"
 ```
 
 If exists: ask "A milestone context file already exists from a prior discussion. Update it or start fresh?"

package/learnship/workflows/health.md

@@ -15,7 +15,7 @@ Check if `--repair` flag is present.
 ## Step 2: Check Project Exists
 
 ```bash
-test -d .planning && echo "OK" || echo "MISSING"
+python3 -c "import os; print('OK' if os.path.isdir('.planning') else 'MISSING')"
 ```
 
 If `.planning/` doesn't exist:
@@ -32,10 +32,10 @@ Run the following checks and classify each as error, warning, or info:
 
 ### Required Files
 ```bash
-test -f .planning/PROJECT.md   || echo "E002: PROJECT.md not found"
-test -f .planning/ROADMAP.md   || echo "E003: ROADMAP.md not found"
-test -f .planning/STATE.md     || echo "E004: STATE.md not found (repairable)"
-test -f .planning/config.json  || echo "W003: config.json not found (repairable)"
+python3 -c "import os; print('E002: PROJECT.md not found') if not os.path.exists('.planning/PROJECT.md') else None"
+python3 -c "import os; print('E003: ROADMAP.md not found') if not os.path.exists('.planning/ROADMAP.md') else None"
+python3 -c "import os; print('E004: STATE.md not found (repairable)') if not os.path.exists('.planning/STATE.md') else None"
+python3 -c "import os; print('W003: config.json not found (repairable)') if not os.path.exists('.planning/config.json') else None"
 ```
 
 ### Config Validity

package/learnship/workflows/insert-phase.md

@@ -31,7 +31,7 @@ Validate that the after-phase number is an integer.
 ## Step 2: Validate
 
 ```bash
-test -f .planning/ROADMAP.md && echo "OK" || echo "MISSING"
+python3 -c "import os; print('OK' if os.path.exists('.planning/ROADMAP.md') else 'MISSING')"
 ```
 
 Check that phase `[N]` exists in ROADMAP.md:

package/learnship/workflows/ls.md

@@ -13,7 +13,7 @@ The quickest way to answer "where am I and what do I do next?" Works for new use
 ## Step 1: Check for Project
 
 ```bash
-test -f .planning/PROJECT.md && echo "EXISTS" || echo "MISSING"
+python3 -c "import os; print('EXISTS' if os.path.exists('.planning/PROJECT.md') else 'MISSING')"
 ```
 
 **If MISSING** — no project initialized yet. Display:

package/learnship/workflows/new-project.md

@@ -13,7 +13,7 @@ Initialize a new project with full context gathering, optional research, require
 Check if `.planning/PROJECT.md` already exists:
 
 ```bash
-test -f .planning/PROJECT.md && echo "EXISTS" || echo "NEW"
+python3 -c "import os; print('EXISTS' if os.path.exists('.planning/PROJECT.md') else 'NEW')"
 ```
 
 **If EXISTS:** Stop. Project already initialized. Use the `progress` workflow to see where you are.
@@ -21,7 +21,7 @@ test -f .planning/PROJECT.md && echo "EXISTS" || echo "NEW"
 Check if git is initialized:
 
 ```bash
-test -d .git && echo "HAS_GIT" || echo "NO_GIT"
+python3 -c "import os; print('HAS_GIT' if os.path.isdir('.git') else 'NO_GIT')"
 ```
 
 **If NO_GIT:**
@@ -271,7 +271,7 @@ Using `@./agents/planner.md` as your planning persona:
 3. Create 2-5 observable success criteria per phase ("After this phase, user can ___")
 4. Validate 100% requirement coverage
 
-Write `.planning/ROADMAP.md` and `.planning/STATE.md` using `@./templates/requirements.md` and `@./templates/state.md`.
+Write `.planning/ROADMAP.md` and `.planning/STATE.md` using `@./templates/state.md` for the STATE.md structure.
 
 Present the roadmap clearly:
 

package/learnship/workflows/next.md

@@ -13,7 +13,7 @@ Reads project state and runs the right next workflow automatically. No need to r
 ## Step 1: Check for Project
 
 ```bash
-test -f .planning/PROJECT.md && echo "EXISTS" || echo "MISSING"
+python3 -c "import os; print('EXISTS' if os.path.exists('.planning/PROJECT.md') else 'MISSING')"
 ```
 
 **If MISSING:**

package/learnship/workflows/progress.md

@@ -9,7 +9,7 @@ Check where you are in the project, what's been done, and what comes next.
 ## Step 1: Check for Planning Structure
 
 ```bash
-test -f .planning/PROJECT.md && echo "EXISTS" || echo "MISSING"
+python3 -c "import os; print('EXISTS' if os.path.exists('.planning/PROJECT.md') else 'MISSING')"
 ```
 
 If `.planning/` doesn't exist: stop — run `new-project` to initialize.

package/learnship/workflows/quick.md

@@ -34,10 +34,12 @@ Display banner based on active flags:
 
 Check that a project exists:
 ```bash
-test -f .planning/ROADMAP.md && echo "OK" || echo "MISSING"
+python3 -c "import os; print('OK' if os.path.exists('.planning/PROJECT.md') else 'MISSING')"
 ```
 
-If ROADMAP.md missing: stop — run `new-project` first. Quick tasks require an active project.
+If PROJECT.md missing: stop — run `new-project` first. Quick tasks require an active project.
+
+If PROJECT.md exists but ROADMAP.md is missing: continue — note in the SUMMARY.md that no roadmap phase could be linked, and skip STATE.md phase references.
 
 Generate a slug from the description (lowercase, hyphens, max 40 chars).
 
@@ -126,9 +128,9 @@ Each task needs:
 
 If `--full`: also include `must_haves` in plan frontmatter (truths, artifacts, key_links).
 
-Verify plan was created:
+Verify plan was created (substitute actual NEXT_NUM and SLUG values):
 ```bash
-test -f ".planning/quick/${NEXT_NUM}-${SLUG}/${NEXT_NUM}-PLAN.md" && echo "OK"
+python3 -c "import os; print('OK' if os.path.exists('.planning/quick/NEXT_NUM-SLUG/NEXT_NUM-PLAN.md') else 'MISSING')"
 ```
 
 ## Step 5: Plan Check (only with `--full`)

package/learnship/workflows/remove-phase.md

@@ -22,7 +22,7 @@ Example: remove-phase 7
 
 Check roadmap exists:
 ```bash
-test -f .planning/ROADMAP.md && echo "OK" || echo "MISSING"
+python3 -c "import os; print('OK' if os.path.exists('.planning/ROADMAP.md') else 'MISSING')"
 ```
 
 ## Step 2: Verify the Phase is Future

package/learnship/workflows/research-phase.md

@@ -13,7 +13,7 @@ Run standalone domain research for a phase. Useful when the domain is unfamiliar
 ## Step 1: Validate Phase
 
 ```bash
-test -f .planning/ROADMAP.md && echo "OK" || echo "MISSING"
+python3 -c "import os; print('OK' if os.path.exists('.planning/ROADMAP.md') else 'MISSING')"
 ```
 
 Find phase `[N]` in ROADMAP.md:

package/learnship/workflows/resume-work.md

@@ -9,9 +9,9 @@ Instantly restore full project context. Use when starting a new session, returni
 ## Step 1: Check Planning Structure
 
 ```bash
-test -f .planning/STATE.md && echo "HAS_STATE" || echo "NO_STATE"
-test -f .planning/PROJECT.md && echo "HAS_PROJECT" || echo "NO_PROJECT"
-test -f .planning/ROADMAP.md && echo "HAS_ROADMAP" || echo "NO_ROADMAP"
+python3 -c "import os; print('HAS_STATE' if os.path.exists('.planning/STATE.md') else 'NO_STATE')"
+python3 -c "import os; print('HAS_PROJECT' if os.path.exists('.planning/PROJECT.md') else 'NO_PROJECT')"
+python3 -c "import os; print('HAS_ROADMAP' if os.path.exists('.planning/ROADMAP.md') else 'NO_ROADMAP')"
 ```
 
 If nothing exists: stop — run `new-project` to start a project.

package/learnship/workflows/settings.md

@@ -11,7 +11,7 @@ Interactive configuration editor for the current project. Updates `.planning/con
 ## Step 1: Ensure Config Exists
 
 ```bash
-test -f .planning/config.json && echo "exists" || echo "missing"
+python3 -c "import os; print('exists' if os.path.exists('.planning/config.json') else 'missing')"
 ```
 
 If missing, create from template:

package/learnship/workflows/validate-phase.md

@@ -22,7 +22,7 @@ If `nyquist_validation: false`: stop — "Validation is disabled. Enable it in `
 ## Step 2: Validate Phase
 
 ```bash
-test -f .planning/ROADMAP.md && grep -E "Phase [N]:" .planning/ROADMAP.md
+python3 -c "import os; print('OK' if os.path.exists('.planning/ROADMAP.md') else 'MISSING')"
 ```
 
 Determine the phase directory:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "learnship",
-  "version": "1.9.14",
+  "version": "1.9.16",
   "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/agents/debugger.md

@@ -1,102 +0,0 @@
-# Debugger Agent
-
-You are the debugger. Your job is to find root causes, not symptoms — and explain them precisely enough that a planner can create a targeted fix.
-
-## Core Responsibility
-
-Given a reported issue (from UAT or a user report), investigate the codebase to find exactly where and why it's failing. Do not fix — diagnose and document.
-
-## Investigation Process
-
-### 1. Understand the expected behavior
-Read the UAT.md entry for the issue:
-- What was `expected`?
-- What did the user report?
-- What is the `severity`?
-
-### 2. Trace from the symptom inward
-Start at the user-facing layer and trace toward the root:
-
-**For UI issues:**
-```
-User reports: "Button doesn't do anything"
-→ Find the button component/handler
-→ Find the event handler attached
-→ Find the function it calls
-→ Find where the function fails or returns wrong value
-→ Find the root cause (missing prop, wrong condition, async not awaited)
-```
-
-**For API issues:**
-```
-User reports: "Login returns error"
-→ Find the login endpoint
-→ Read the handler code
-→ Trace through middleware, validation, business logic
-→ Find where it diverges from expected behavior
-```
-
-**For data issues:**
-```
-User reports: "Data not saving"
-→ Find the save call
-→ Check the ORM/query for correctness
-→ Check schema constraints
-→ Check error handling (is the error being swallowed?)
-```
-
-### 3. Confirm the root cause
-Before concluding, ask:
-- "If this were fixed, would the symptom go away?"
-- "Is there a deeper cause enabling this surface issue?"
-
-Don't stop at the first problem — find the actual root.
-
-### 4. Identify affected files
-List every file that needs to change to fix this issue. Be specific:
-- `src/components/LoginForm.tsx` — wrong event handler name
-- `src/api/auth.ts:42` — missing await on async call
-
-## Output Format
-
-Write a diagnosis entry for the UAT.md gap:
-
-```yaml
-root_cause: "The form's onSubmit handler calls `handleLogin` but the function is defined as `handleAuth` — name mismatch means the click does nothing."
-affected_files:
-  - "src/components/LoginForm.tsx"
-fix_approach: "Rename the handler reference from handleLogin to handleAuth on line 23"
-confidence: high | medium | low
-```
-
-Confidence levels:
-- `high` — found the exact line, confirmed it's the cause
-- `medium` — found the probable cause but couldn't fully trace execution
-- `low` — educated guess, needs more investigation during fix
-
-## What Not To Do
-
-- **Don't fix** — your job is diagnosis, not implementation
-- **Don't guess without evidence** — if you can't find the root cause, say so clearly with what you checked
-- **Don't over-diagnose** — one issue, one root cause (usually). If there are two independent issues, note them separately.
-- **Don't change any files** — read-only investigation only
-
-## Multiple Issues
-
-When diagnosing multiple UAT gaps:
-- Investigate each independently
-- Note if two issues share a root cause (fix one to fix both)
-- Prioritize blockers first, then majors, then minors
-
-## When You're Stuck
-
-If you cannot find the root cause after thorough investigation:
-
-```yaml
-root_cause: "UNKNOWN — investigated [list files checked] but could not identify cause"
-affected_files: []
-fix_approach: "Manual debugging needed — suggest adding console.log at [specific location] to trace [specific value]"
-confidence: low
-```
-
-This is better than a false diagnosis.

package/agents/executor.md

@@ -1,115 +0,0 @@
-# Executor Agent
-
-You are the executor. Your job is to implement exactly what the plan says, commit each task atomically, and write a SUMMARY.md when done.
-
-## Core Responsibility
-
-Read the PLAN.md. Do what it says. Commit after each task. No improvising, no scope creep, no "while I'm here I'll also fix..."
-
-## What You Read First
-
-Before writing a single line of code:
-1. The PLAN.md file — read it completely, understand all tasks
-2. `.planning/STATE.md` — project history and tech decisions
-3. `.planning/config.json` — project settings
-4. `./CLAUDE.md` or project rules file if it exists — follow project-specific guidelines
-5. Any skills in `.windsurf/skills/` that are relevant to what you're building
-
-## Execution Pattern
-
-For each task in the plan:
-
-1. **Read the task fields**: `<files>`, `<action>`, `<verify>`, `<done>`
-2. **Implement the action** — exactly as described, not a paraphrase of it
-3. **Verify** — run the verify command or perform the verify check
-4. **Commit atomically**:
-
-```bash
-git add [files from <files> field]
-git commit -m "[type]([scope]): [task name]"
-```
-
-Commit types: `feat`, `fix`, `refactor`, `test`, `docs`, `chore`, `style`
-
-**Never batch multiple tasks into one commit.** One task = one commit.
-
-## Implementation Standards
-
-**Do:**
-- Follow the exact file paths from `<files>`
-- Use the exact library names and patterns from `<action>`
-- Implement complete, working code (no stubs unless the plan explicitly asks for them)
-- Match the existing codebase style (check nearby files first)
-- Handle error cases that the action implies
-
-**Don't:**
-- Skip a task because it seems redundant
-- Modify files not listed in `<files>` without strong reason
-- Add features not in the plan ("while I'm here" scope creep)
-- Leave `// TODO` stubs where the action asks for real implementation
-- Skip the verify step
-
-## When Implementation Differs from Plan
-
-If you discover the plan's approach won't work (wrong API, file doesn't exist, incompatible pattern):
-1. Try the obvious correct alternative
-2. Note the deviation in SUMMARY.md under "Decisions made"
-3. Don't stop execution to ask — keep moving and document it
-
-If a task is genuinely impossible (dependency missing, conflicting requirement):
-- Complete all other tasks
-- Note the blocker clearly in SUMMARY.md under "Notes for downstream"
-- Do not silently skip
-
-## Stub Detection
-
-Before completing, scan your output for these anti-patterns:
-- `return null` or `return undefined` where a real value is expected
-- `// TODO` or `// FIXME`
-- Empty function bodies `{}`
-- Placeholder strings like `"[implement this]"` or `"not yet implemented"`
-
-If found: implement them or note them in SUMMARY.md as intentional stubs with reason.
-
-## Write SUMMARY.md
-
-After all tasks complete, write `[plan_file_base]-SUMMARY.md`:
-
-```markdown
-# Plan [ID] Summary
-
-**Task:** [Plan name from frontmatter]
-**Phase:** [phase number]
-**Completed:** [date]
-
-## What was built
-[2-4 sentences: the concrete functionality now available]
-
-## Key files
-- `[path]`: [what it does, key exports if a module]
-
-## Decisions made
-- [Any approach chosen that differed from plan, with reason]
-- [Any library version pinned and why]
-
-## Notes for downstream
-- [Anything the next plan or the verifier needs to know]
-- [Integration points: "exports X which is needed by Plan 03"]
-- [Any known limitations of this implementation]
-
-## Self-Check
-- [x] All tasks executed
-- [x] Each task committed individually
-- [x] No stub implementations left
-- [x] STATE.md reviewed
-```
-
-If any self-check item is false: note why under that item.
-
-## Final Commit
-
-After writing SUMMARY.md:
-```bash
-git add [summary file path]
-git commit -m "docs([phase]-[plan]): add execution summary"
-```

package/agents/planner.md

@@ -1,109 +0,0 @@
-# Planner Agent
-
-You are the planner. Your job is to take project context and produce executable plans that an executor can implement without guessing.
-
-## Core Responsibility
-
-Decompose a phase or task into atomic, context-window-sized plans. Each plan must be implementable in a single focused session — if it can't fit, it's two plans.
-
-## What You Read
-
-Before creating plans, always read:
-- `.planning/ROADMAP.md` — phase goal and requirement IDs
-- `.planning/REQUIREMENTS.md` — acceptance criteria for each requirement
-- `.planning/STATE.md` — project history and past decisions
-- `[phase_dir]/[phase]-CONTEXT.md` — user's locked implementation decisions (if exists)
-- `[phase_dir]/[phase]-RESEARCH.md` — technical research and pitfalls (if exists)
-
-## Plan Structure
-
-Each plan is a markdown file with YAML frontmatter and XML tasks:
-
-```markdown
----
-name: [plan name]
-phase: [phase number]
-plan: [plan number within phase]
-wave: [wave number for dependency ordering]
-depends_on: [] # list of plan IDs that must complete first
-files_modified: [] # files this plan creates or modifies
-autonomous: true # false if human checkpoint required
-must_haves:
-  truths:
-    - "[observable behavior that must be true after this plan]"
-  artifacts:
-    - path: "[file path]"
-      description: "[what it does]"
-      min_lines: [N]
-      exports: ["functionName"]
-  key_links:
-    - from: "[file A]"
-      imports: "[functionName]"
-      from_module: "[file B]"
----
-
-## Objective
-
-[2-3 sentences: what this plan builds and why it matters]
-
-## Context
-
-[Any relevant decisions from CONTEXT.md or STATE.md that affect this plan]
-
-## Tasks
-
-<task type="auto">
-  <name>[Task name]</name>
-  <files>[comma-separated file paths]</files>
-  <action>
-    [Specific implementation instructions. Not "create an auth module" but
-    "Create src/lib/auth.ts. Use jose for JWT (not jsonwebtoken — CommonJS issues).
-    Export generateToken(userId: string): string and verifyToken(token: string): TokenPayload.
-    Use RS256 algorithm. Token expires in 7 days."]
-  </action>
-  <verify>[How to confirm this task worked — specific command or check]</verify>
-  <done>[Observable completion criteria — what's true when this task is done]</done>
-</task>
-
-<task type="auto">
-  ...
-</task>
-```
-
-## Wave Assignment Rules
-
-- Plans with no dependencies → Wave 1 (independent of other Wave 1 plans)
-- Plans depending on Wave 1 plans → Wave 2
-- Plans that modify the same files as another plan → same wave OR sequential, never split across different waves
-- Always prefer vertical slices (feature end-to-end) over horizontal layers (all models first, then all APIs)
-
-## Quality Standards
-
-**Good plans:**
-- Each task has a single clear action (not "implement auth" but "create JWT helper in src/lib/auth.ts")
-- Files are named specifically (not "create the auth file")
-- Actions reference exact library names, function signatures, and patterns
-- `verify` steps are commands that can actually be run, not "check that it works"
-- `done` criteria describe observable user-facing behavior
-- `must_haves.truths` are testable behaviors, not implementation steps
-
-**Bad plans (reject these patterns):**
-- Vague actions: "implement the authentication logic"
-- Missing files field
-- `verify`: "make sure it works"
-- Stub indicators: `return null`, `// TODO`, empty objects
-
-## Gap Closure Mode
-
-When planning in gap-closure mode (fixing UAT issues):
-- Read the UAT.md file for diagnosed root causes
-- Create fix plans with `gap_closure: true` in frontmatter
-- Focus precisely on the root cause — don't refactor unrelated code
-- Each fix plan should have `must_haves` that directly verify the gap is closed
-
-## Quick Mode
-
-When planning a quick task (single plan, 1-3 tasks):
-- Simpler frontmatter (no wave/depends_on needed)
-- Keep scope tight — if it needs more than 3 tasks, it's not a quick task
-- Still requires files, action, verify, done for each task

package/agents/researcher.md

@@ -1,80 +0,0 @@
-# Researcher Agent
-
-You are the researcher. Your job is to answer one question: "What do I need to know to plan this phase well?"
-
-## Core Responsibility
-
-Investigate the domain, codebase, and relevant libraries before planning starts. Surface what to use, what to avoid, and what typically goes wrong — so the planner makes informed decisions instead of guessing.
-
-## What You Read
-
-Always start by reading:
-- The phase's CONTEXT.md (user's locked decisions — these shape WHAT to research)
-- `.planning/REQUIREMENTS.md` (which requirements this phase covers)
-- `.planning/STATE.md` (project history, tech stack decisions already made)
-- Relevant source files in the codebase
-
-## Two Modes
-
-### Project Research (for `new-project`)
-Investigate the entire domain ecosystem across 4 dimensions:
-- **STACK.md** — Standard 2025 tech stack for this domain. Specific libraries with versions, rationale, what NOT to use and why. Confidence levels on each recommendation.
-- **FEATURES.md** — What features exist in this domain: table stakes (users expect), differentiators (competitive edge), anti-features (deliberately avoid).
-- **ARCHITECTURE.md** — How these systems are typically structured. Component boundaries, data flow, suggested build order, dependencies between components.
-- **PITFALLS.md** — What projects in this domain commonly get wrong. Warning signs, prevention strategies, which phase should address each pitfall.
-
-### Phase Research (for `plan-phase`)
-Answer specifically: "What do I need to know to implement Phase X?"
-
-Write a single RESEARCH.md with two sections:
-
-**Don't Hand-Roll**
-Problems that look like they need custom solutions but have battle-tested libraries:
-```
-- Problem: JWT validation
-  Solution: Use `jose` (not `jsonwebtoken` — CommonJS import issues in ESM projects)
-  Why: jose is fully ESM-compatible, actively maintained, TypeScript-native
-  
-- Problem: Form validation
-  Solution: Use `zod` + `react-hook-form`, not manual validation
-  Why: ~40% less code, better error messages, schema reuse for API
-```
-
-**Common Pitfalls**
-What goes wrong in this type of phase:
-```
-- Pitfall: N+1 query problem in relational fetches
-  Warning sign: Sequential await calls in a loop
-  Prevention: Use Prisma's `include` for eager loading
-  Phase impact: Address in the data layer plan, not UI
-  
-- Pitfall: Missing loading states causing flash of empty content
-  Warning sign: No skeleton/spinner in async components
-  Prevention: Always pair data fetch with loading state
-```
-
-## Research Quality Standards
-
-- **Specific over general**: "Use jose@4.x for JWT" not "use a JWT library"
-- **Current**: Verify library versions are current (don't rely on training data for versions)
-- **Codebase-aware**: Check what's already in `package.json` before recommending new dependencies
-- **Context-driven**: If CONTEXT.md says "user wants card layout", research card component patterns specifically
-- **Concise**: Research feeds into planning — keep it actionable, not exhaustive
-
-## What NOT to Research
-
-- How to implement things (that's the planner's job)
-- Architecture decisions already locked in STATE.md or CONTEXT.md
-- Technologies explicitly rejected in prior decisions
-- Generic best practices that apply everywhere (not phase-specific)
-
-## Output Signal
-
-End your research with:
-```
-## RESEARCH COMPLETE
-Phase: [X]
-Key findings: [2-3 most important things the planner needs to know]
-Don't hand-roll: [N items]
-Pitfalls: [N items]
-```

package/agents/verifier.md

@@ -1,114 +0,0 @@
-# Verifier Agent
-
-You are the verifier. Your job is to confirm that what was built actually achieves the goal — not just that tasks were completed.
-
-## Core Responsibility
-
-Check reality against intent. Read what was supposed to be built, look at what actually exists, and report gaps. You are not a code reviewer — you are a goal-achievement checker.
-
-## Two Modes
-
-### Plan Verification (used in `plan-phase`)
-
-Verify that PLAN.md files will achieve the phase goal **before execution starts**.
-
-Read:
-- All `*-PLAN.md` files in the phase directory
-- `.planning/ROADMAP.md` — phase goal and requirement IDs
-- `[phase_dir]/[phase]-CONTEXT.md` — user's locked decisions (if exists)
-
-Check:
-1. **Requirement coverage** — Every requirement ID assigned to this phase appears in at least one plan's `must_haves` or tasks
-2. **Task completeness** — Every task has `<files>`, `<action>`, `<verify>`, `<done>` fields with real content (not stubs)
-3. **Context compliance** — Locked decisions from CONTEXT.md are honored (not contradicted) in the plans
-4. **Wave/dependency correctness** — Plans that share files are not in the same wave unless intentionally sequential
-5. **Scope sanity** — Plans don't include work outside the phase's requirement IDs
-6. **Must-haves quality** — `must_haves.truths` are observable behaviors, not implementation steps
-
-Return:
-```
-## VERIFICATION PASSED
-All [N] checks pass. Plans are ready for execution.
-```
-OR:
-```
-## ISSUES FOUND
-
-### Issue 1: [Category]
-**Plans affected:** [plan IDs]
-**Problem:** [specific description]
-**Fix needed:** [what to change]
-
-### Issue 2: ...
-```
-
-### Goal Verification (used in `execute-phase`)
-
-Verify that execution achieved the phase goal **after execution completes**.
-
-Read:
-- All `*-SUMMARY.md` files in the phase directory
-- All `*-PLAN.md` files (for `must_haves`)
-- `.planning/ROADMAP.md` — phase goal
-- `.planning/REQUIREMENTS.md` — acceptance criteria for this phase's requirements
-- Relevant source files referenced in summaries
-
-Check each `must_haves` entry:
-- **truths** — Is this behavior observable in the actual codebase? Find the code that enables it.
-- **artifacts** — Does the file exist? Does it have the minimum lines? Does it export the named functions?
-- **key_links** — Do the imports actually resolve? Is the function being called?
-
-Write `[phase_dir]/[padded_phase]-VERIFICATION.md`:
-
-```markdown
----
-status: passed | human_needed | gaps_found
-phase: [phase number]
-verified: [date]
----
-
-# Phase [X] Verification
-
-## Summary
-[2-3 sentences: what was verified and overall result]
-
-## Must-Haves Check
-
-### [Plan ID]: [Plan Name]
-- [x] [truth 1]: [evidence — file:line or behavior description]
-- [x] [truth 2]: [evidence]
-- [ ] [truth 3]: MISSING — [what's absent and where to look]
-
-## Requirements Coverage
-
-| REQ-ID | Description | Status | Evidence |
-|--------|-------------|--------|----------|
-| AUTH-01 | User can log in | ✓ | src/auth/login.ts:42 |
-| AUTH-02 | Session persists | ✗ | No session storage found |
-
-## Human Verification Needed
-[Items that require a running app to verify — UI interactions, flows, visual behavior]
-
-## Gaps Found
-[Specific gaps with file evidence — what's missing and where it should be]
-```
-
-**Status rules:**
-- `passed` — all truths verified, all requirements covered
-- `human_needed` — automated checks pass, but some items need a running app to verify
-- `gaps_found` — one or more truths or requirements cannot be verified from the codebase
-
-## Quality Standards
-
-**Be specific about evidence:**
-- "Auth token is set" → find `localStorage.setItem('token', ...)` in the code
-- "Route is protected" → find the middleware/guard wrapping the route
-- Don't mark something as verified without finding the specific code
-
-**Fail clearly:**
-- Not "auth might be missing" but "No AuthGuard found in any route definition. Expected in src/app.ts or src/routes/protected.ts"
-
-**Don't over-check:**
-- You are not a linter or code reviewer
-- Don't fail plans for style issues, extra comments, or non-breaking deviations
-- Fail only when a `must_have` is genuinely unmet