jettypod 4.4.118 → 4.4.121

package/lib/worktree-diagnostics.js

@@ -99,7 +99,7 @@ async function runDiagnostics(db, repoPath, options = {}) {
           count: reconcileResults.staleDbEntries.length,
           message: `Found ${reconcileResults.staleDbEntries.length} database entries with missing filesystem directories`,
           details: reconcileResults.staleDbEntries,
-          recommendation: 'Run reconciliation with cleanup=true to mark as corrupted'
+          recommendation: 'Run reconciliation with cleanup=true to mark as cleaned'
         });
       }
 
@@ -192,23 +192,23 @@ async function runDiagnostics(db, repoPath, options = {}) {
 async function checkDatabaseIntegrity(db) {
   const issues = [];
 
-  // Check for corrupted worktrees
-  const corruptedCount = await new Promise((resolve, reject) => {
-    db.get('SELECT COUNT(*) as count FROM worktrees WHERE status = ?', ['corrupted'], (err, row) => {
+  // Check for cleaned worktrees (terminal state — informational only)
+  const cleanedCount = await new Promise((resolve, reject) => {
+    db.get('SELECT COUNT(*) as count FROM worktrees WHERE status = ?', ['cleaned'], (err, row) => {
       if (err) reject(err);
       else resolve(row.count);
     });
   });
 
-  if (corruptedCount > 0) {
+  if (cleanedCount > 0) {
     issues.push({
       severity: SEVERITY.INFO,
       category: 'database',
-      type: 'corrupted_worktrees',
-      count: corruptedCount,
-      message: `Found ${corruptedCount} corrupted worktree(s) in database`,
-      details: { count: corruptedCount },
-      recommendation: 'These worktrees can be safely cleaned up or ignored'
+      type: 'cleaned_worktrees',
+      count: cleanedCount,
+      message: `Found ${cleanedCount} cleaned worktree(s) in database`,
+      details: { count: cleanedCount },
+      recommendation: 'These are historical records — no action needed'
     });
   }
 
@@ -232,7 +232,7 @@ async function checkDatabaseIntegrity(db) {
       count: orphanedWorktrees.length,
       message: `Found ${orphanedWorktrees.length} worktree(s) with missing work items`,
       details: orphanedWorktrees,
-      recommendation: 'Mark these worktrees as corrupted'
+      recommendation: 'Mark these worktrees as cleaned'
     });
   }
 
@@ -265,7 +265,7 @@ async function checkFilesystemHealth(db, repoPath) {
         type: 'missing_worktree_directory',
         message: `Active worktree directory missing: ${worktreePath}`,
         details: { worktree },
-        recommendation: 'Mark worktree as corrupted and recreate if needed'
+        recommendation: 'Mark worktree as cleaned and recreate if needed'
       });
       continue;
     }
@@ -293,7 +293,7 @@ async function checkFilesystemHealth(db, repoPath) {
         type: 'permission_issue',
         message: `Cannot read/write worktree directory: ${worktreePath}`,
         details: { worktree, error: err.message },
-        recommendation: 'Fix directory permissions or mark worktree as corrupted'
+        recommendation: 'Fix directory permissions or mark worktree as cleaned'
       });
     }
   }
@@ -344,11 +344,11 @@ function generateRecommendations(report) {
     });
   }
 
-  if (report.issues.some(i => i.type === 'corrupted_worktrees')) {
+  if (report.issues.some(i => i.type === 'cleaned_worktrees')) {
     recommendations.push({
       priority: 'low',
-      action: 'Clean up corrupted worktree entries from database',
-      reason: 'Keeping database clean improves query performance'
+      action: 'Cleaned worktree entries are historical records',
+      reason: 'No action needed — these are part of the audit trail'
     });
   }
 

package/lib/worktree-facade.js

@@ -117,7 +117,7 @@ async function startWork(workItem, options = {}) {
 /**
  * Stop work on a work item with graceful degradation
  *
- * Attempts to cleanup worktree. If that fails, marks as corrupted and continues.
+ * Attempts to cleanup worktree. If that fails, marks as cleaned and continues.
  *
  * @param {number} worktreeId - Worktree ID (can be null if working in main)
  * @param {Object} options - Optional configuration

package/lib/worktree-manager.js

@@ -21,7 +21,7 @@ const config = require('./config');
 /**
  * Valid worktree statuses
  */
-const VALID_STATUSES = ['active', 'merging', 'cleanup_pending', 'corrupted'];
+const VALID_STATUSES = ['active', 'merging', 'cleanup_pending', 'cleaned'];
 
 /**
  * Create a worktree for a work item
@@ -352,7 +352,7 @@ async function getAllActiveWorktrees(options = {}) {
  * Mark worktree status
  *
  * @param {number} worktreeId - Worktree ID
- * @param {string} status - New status (active|merging|cleanup_pending|corrupted)
+ * @param {string} status - New status (active|merging|cleanup_pending|cleaned)
  * @param {Object} options - Optional configuration
  * @param {Object} options.db - Database connection (defaults to global database)
  * @returns {Promise<void>}
@@ -671,13 +671,13 @@ async function cleanupWorktree(worktreeId, options = {}) {
       }
     }
 
-    // Step 5: Mark as corrupted (we never delete DB entries)
-    // Using 'corrupted' as the final state for cleaned up worktrees
+    // Step 5: Mark as cleaned (we never delete DB entries)
+    // Using 'cleaned' as the final state for cleaned up worktrees
     // This preserves the audit trail
     await new Promise((resolve, reject) => {
       db.run(
         'UPDATE worktrees SET status = ?, updated_at = datetime(\'now\') WHERE id = ?',
-        ['corrupted', worktreeId],
+        ['cleaned', worktreeId],
         (err) => {
           if (err) reject(err);
           else resolve();
@@ -686,12 +686,12 @@ async function cleanupWorktree(worktreeId, options = {}) {
     });
 
   } catch (err) {
-    // On any failure, mark as corrupted
+    // On any failure, mark as cleaned (terminal state)
     try {
       await new Promise((resolve, reject) => {
         db.run(
           'UPDATE worktrees SET status = ?, updated_at = datetime(\'now\') WHERE id = ?',
-          ['corrupted', worktreeId],
+          ['cleaned', worktreeId],
           (err) => {
             if (err) reject(err);
             else resolve();
@@ -699,7 +699,7 @@ async function cleanupWorktree(worktreeId, options = {}) {
         );
       });
     } catch (dbErr) {
-      console.error(`Failed to mark worktree as corrupted: ${dbErr.message}`);
+      console.error(`Failed to mark worktree as cleaned: ${dbErr.message}`);
     }
 
     throw new Error(`Worktree cleanup failed: ${err.message}`);

package/lib/worktree-reconciler.js

@@ -95,7 +95,7 @@ async function reconcileState(db, repoPath, options = {}) {
     if (cleanup && staleEntries.length > 0) {
       for (const entry of staleEntries) {
         try {
-          await markWorktreeCorrupted(db, entry.id);
+          await markWorktreeCleaned(db, entry.id);
           results.cleanupAttempts.staleDbEntries++;
         } catch (err) {
           results.errors.push(`Failed to mark stale entry as corrupted: ${err.message}`);
@@ -127,7 +127,7 @@ async function reconcileState(db, repoPath, options = {}) {
           results.cleanupAttempts.gitFilesystemMismatches++;
           results.gitCommands.push(`git worktree add --force`);
         } catch (err) {
-          await markWorktreeCorrupted(db, mismatch.id);
+          await markWorktreeCleaned(db, mismatch.id);
           results.errors.push(`Failed to re-register worktree ${mismatch.path}: ${err.message}`);
         }
       }
@@ -342,13 +342,13 @@ async function detectStaleDbEntries(db, repoPath) {
 }
 
 /**
- * Mark worktree as corrupted in database
+ * Mark worktree as cleaned in database (terminal state)
  */
-async function markWorktreeCorrupted(db, worktreeId) {
+async function markWorktreeCleaned(db, worktreeId) {
   return new Promise((resolve, reject) => {
     db.run(
       'UPDATE worktrees SET status = ?, updated_at = datetime(\'now\') WHERE id = ?',
-      ['corrupted', worktreeId],
+      ['cleaned', worktreeId],
       (err) => {
         if (err) reject(err);
         else resolve();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jettypod",
-  "version": "4.4.118",
+  "version": "4.4.121",
   "description": "AI-powered development workflow manager with TDD, BDD, and automatic test generation",
   "main": "jettypod.js",
   "bin": {
@@ -34,8 +34,10 @@
     "test:unit": "NODE_ENV=test jest",
     "test:unit:watch": "NODE_ENV=test jest --watch",
     "test:cleanup": "node scripts/test-cleanup.js",
+    "version": "node -e \"const v=require('./package.json').version; const f='apps/dashboard/package.json'; const p=JSON.parse(require('fs').readFileSync(f)); p.version=v; require('fs').writeFileSync(f, JSON.stringify(p,null,2)+'\\n')\"",
     "prepublishOnly": "echo '🔄 Syncing skills to templates...' && cp -r .claude/skills/* skills-templates/ && (git diff --quiet skills-templates/ || (git add skills-templates/ && git commit -m 'chore: Sync skills-templates')) && echo '✅ Skills synced' && echo '🔨 Building dashboard...' && cd apps/dashboard && npm install && npm run build && echo '✅ Dashboard built'",
     "postpublish": "git push origin main --tags && echo '✅ Pushed version commit and tags'",
+    "postinstall": "node scripts/postinstall.js",
     "dashboard": "npm run dev --prefix apps/dashboard",
     "dashboard:build": "npm run build --prefix apps/dashboard",
     "dashboard:start": "npm run start --prefix apps/dashboard"
@@ -48,13 +50,18 @@
     "ws": "^8.18.3"
   },
   "jest": {
+    "setupFiles": [
+      "./jest.setup.js"
+    ],
     "testEnvironment": "node",
     "testMatch": [
       "**/__tests__/**/*.js",
       "**/*.test.js"
     ],
     "testPathIgnorePatterns": [
-      "/node_modules/"
+      "/node_modules/",
+      "/apps/dashboard/dist/",
+      "/.jettypod-work/"
     ],
     "collectCoverage": false,
     "coverageDirectory": "coverage"

package/scripts/ndjson-to-cucumber-json.js

@@ -0,0 +1,152 @@
+#!/usr/bin/env node
+// Convert cucumber ndjson (message format) to standard cucumber JSON format.
+// Usage: node scripts/ndjson-to-cucumber-json.js [input.ndjson] [output.json]
+// Defaults: cucumber-results.ndjson -> cucumber-results.json
+
+const fs = require('fs');
+const path = require('path');
+
+function convert(ndjsonPath, jsonPath) {
+  const raw = fs.readFileSync(ndjsonPath, 'utf-8');
+  const lines = raw.split('\n').filter(l => l.trim());
+
+  // Lookup tables
+  const gherkinDocuments = new Map(); // uri -> gherkinDocument
+  const pickles = new Map();          // pickle.id -> pickle
+  const testCases = new Map();        // testCase.id -> testCase
+  const testCaseStartedMap = new Map(); // testCaseStarted.id -> testCaseStarted
+  const stepDefinitions = new Map();  // stepDefinition.id -> stepDefinition
+
+  // Results
+  const testStepResults = new Map();  // testCaseStartedId -> [{stepId, result}]
+
+  for (const line of lines) {
+    let msg;
+    try {
+      msg = JSON.parse(line);
+    } catch {
+      continue;
+    }
+
+    if (msg.gherkinDocument) {
+      gherkinDocuments.set(msg.gherkinDocument.uri, msg.gherkinDocument);
+    }
+    if (msg.pickle) {
+      pickles.set(msg.pickle.id, msg.pickle);
+    }
+    if (msg.stepDefinition) {
+      stepDefinitions.set(msg.stepDefinition.id, msg.stepDefinition);
+    }
+    if (msg.testCase) {
+      testCases.set(msg.testCase.id, msg.testCase);
+    }
+    if (msg.testCaseStarted) {
+      testCaseStartedMap.set(msg.testCaseStarted.id, msg.testCaseStarted);
+      testStepResults.set(msg.testCaseStarted.id, []);
+    }
+    if (msg.testStepFinished) {
+      const tsf = msg.testStepFinished;
+      const arr = testStepResults.get(tsf.testCaseStartedId);
+      if (arr) {
+        arr.push({
+          testStepId: tsf.testStepId,
+          result: tsf.testStepResult,
+        });
+      }
+    }
+  }
+
+  // Build cucumber JSON structure grouped by feature URI
+  const featureMap = new Map(); // uri -> { feature data }
+
+  for (const [tcsId, tcs] of testCaseStartedMap) {
+    const testCase = testCases.get(tcs.testCaseId);
+    if (!testCase) continue;
+    const pickle = pickles.get(testCase.pickleId);
+    if (!pickle) continue;
+
+    const uri = pickle.uri;
+    if (!featureMap.has(uri)) {
+      const doc = gherkinDocuments.get(uri);
+      featureMap.set(uri, {
+        uri,
+        name: doc?.feature?.name || uri,
+        description: doc?.feature?.description || '',
+        keyword: doc?.feature?.keyword || 'Feature',
+        elements: [],
+      });
+    }
+
+    const stepResults = testStepResults.get(tcsId) || [];
+    const steps = [];
+
+    for (const testStep of testCase.testSteps) {
+      // Skip hook steps (no pickleStepId)
+      if (!testStep.pickleStepId) continue;
+
+      const pickleStep = pickle.steps.find(s => s.id === testStep.pickleStepId);
+      if (!pickleStep) continue;
+
+      // Find the result for this step
+      const stepResult = stepResults.find(r => r.testStepId === testStep.id);
+      const result = stepResult?.result;
+
+      const dur = result?.duration || { seconds: 0, nanos: 0 };
+      const durationNanos = (dur.seconds || 0) * 1e9 + (dur.nanos || 0);
+
+      // Get keyword from gherkin document
+      let keyword = '';
+      const doc = gherkinDocuments.get(uri);
+      if (doc?.feature) {
+        for (const child of doc.feature.children || []) {
+          const scenario = child.scenario;
+          if (!scenario) continue;
+          for (const gherkinStep of scenario.steps) {
+            if (pickleStep.astNodeIds?.includes(gherkinStep.id)) {
+              keyword = gherkinStep.keyword;
+              break;
+            }
+          }
+          if (keyword) break;
+        }
+      }
+
+      steps.push({
+        keyword: keyword || 'Step ',
+        name: pickleStep.text || '',
+        result: {
+          status: (result?.status || 'UNKNOWN').toLowerCase(),
+          duration: durationNanos,
+          error_message: result?.message || undefined,
+        },
+      });
+    }
+
+    featureMap.get(uri).elements.push({
+      type: 'scenario',
+      name: pickle.name,
+      steps,
+    });
+  }
+
+  const output = Array.from(featureMap.values());
+  fs.writeFileSync(jsonPath, JSON.stringify(output, null, 2));
+  return output.reduce((sum, f) => sum + f.elements.length, 0);
+}
+
+// CLI entry point
+if (require.main === module) {
+  const projectRoot = path.resolve(__dirname, '..');
+  const ndjsonPath = process.argv[2] || path.join(projectRoot, 'cucumber-results.ndjson');
+  const jsonPath = process.argv[3] || path.join(projectRoot, 'cucumber-results.json');
+
+  if (!fs.existsSync(ndjsonPath)) {
+    console.error(`No ndjson file found at ${ndjsonPath}`);
+    process.exit(1);
+  }
+
+  const count = convert(ndjsonPath, jsonPath);
+  console.log(`Converted ${count} scenarios to ${jsonPath}`);
+}
+
+module.exports = { convert };

package/scripts/postinstall.js

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+
+// Records the source directory on global install so jettypod can auto-update.
+// Writes ~/.jettypod-dev.json with the source path for staleness detection.
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+// Only run for global installs
+if (process.env.npm_config_global !== 'true') process.exit(0);
+
+const sourceDir = process.env.INIT_CWD;
+if (!sourceDir) process.exit(0);
+
+// Verify source dir looks like a jettypod repo (has jettypod.js)
+if (!fs.existsSync(path.join(sourceDir, 'jettypod.js'))) process.exit(0);
+
+try {
+  const devInfo = { sourceDir };
+  const devFile = path.join(os.homedir(), '.jettypod-dev.json');
+  fs.writeFileSync(devFile, JSON.stringify(devInfo, null, 2) + '\n');
+} catch {
+  // Non-fatal — skip silently
+}

package/skills-templates/bug-mode/SKILL.md

@@ -44,7 +44,7 @@ When this skill is activated, you are implementing a bug fix directly on the bug
 
 Your job: Implement the fix, write a regression test, and verify everything passes.
 
-## 🔑 Critical Context
+## Critical Context
 
 **You are working in an isolated git worktree:**
 - `work start [bug-id]` already created a dedicated worktree
@@ -55,7 +55,7 @@ Your job: Implement the fix, write a regression test, and verify everything pass
 
 ---
 
-## 🚨 SHELL CWD RECOVERY
+## SHELL CWD RECOVERY
 
 **If ALL bash commands start failing with "Error: Exit code 1" and no output:**
 
@@ -69,7 +69,7 @@ Your shell's working directory was likely inside a worktree that was deleted. Th
 
 ---
 
-## 🛑 PRE-FLIGHT VALIDATION (REQUIRED)
+## PRE-FLIGHT VALIDATION (REQUIRED)
 
 **Before proceeding, validate the worktree exists.**
 
@@ -81,9 +81,9 @@ sqlite3 .jettypod/work.db "SELECT wi.id, wi.title, wi.status, wt.worktree_path,
 
 | worktree_path | What it means | Action |
 |---------------|---------------|--------|
-| **Has a path** | ✅ Worktree exists, ready to proceed | Continue to Step 0 |
-| **NULL or empty** | ❌ `work start` was not called | **STOP - run `jettypod work start [bug-id]` first** |
-| **No rows returned** | ❌ No bug is in progress | **STOP - verify the bug exists and run `work start`** |
+| **Has a path** | Worktree exists, ready to proceed | Continue to Step 0 |
+| **NULL or empty** | `work start` was not called | **STOP - run `jettypod work start [bug-id]` first** |
+| **No rows returned** | No bug is in progress | **STOP - verify the bug exists and run `work start`** |
 
 **After pre-flight passes, emit gate signal:**
 
@@ -114,7 +114,7 @@ The bug-planning skill embedded implementation guidance:
 
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-🐛 BUG MODE: Fixing #[bug-id]
+BUG MODE: Fixing #[bug-id]
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 Bug: #[id] [title]
@@ -176,14 +176,14 @@ sqlite3 .jettypod/work.db "SELECT project_state FROM project_config WHERE id = 1
 
 ```
 ━━━ Iteration 1 ━━━
-📂 Reading: [file:line from breadcrumbs]
-🔧 Change: [what you're fixing]
+Reading: [file:line from breadcrumbs]
+Change: [what you're fixing]
 ```
 
 **After implementation:**
 
 ```
-🎉 Fix Implemented
+Fix Implemented
 
 Changes made:
 - [Change 1]
@@ -197,6 +197,16 @@ Now writing regression test...
 
 ---
 
+### BDD Step Definition Constraints (ENFORCED)
+
+Before writing any step definitions, read `templates/bdd-guidance.md`. BANNED in step defs: `setTimeout`/`sleep`, module-level `let`/`var`, raw SQL, assertions in Given/When, loops/branching, self-fulfilling mocks (setting state then asserting it). Steps must be 1-5 lines calling one helper via Cucumber World (`this`). Read `features/support/helpers/` and reuse before creating.
+
+**Scaffolding:** If `features/support/helpers/` does not exist in the project, scaffold it before writing step definitions. Copy `templates/bdd-scaffolding/wait.js` to `features/support/helpers/wait.js` and `templates/bdd-scaffolding/world.js` to `features/support/world.js`.
+
+**Helper Reuse:** Before writing step definitions, glob `features/support/helpers/**/*.js` and read each file. Import and call existing helpers in your steps — never duplicate functionality that already exists.
+
+---
+
 ### Step 2: Write Regression Test
 
 **Goal:** Create a test that verifies the bug is fixed and prevents regression.
@@ -239,7 +249,7 @@ npx cucumber-js features/<bug-slug>.feature
 **Confirm test passes:**
 
 ```
-✅ Regression Test Passing
+Regression Test Passing
 
 Test: features/<bug-slug>.feature
 Status: PASSING
@@ -272,7 +282,7 @@ npx cucumber-js features/<related-feature>.feature 2>/dev/null || true
 **If regressions found:**
 
 ```
-⚠️ Regression Detected
+Regression Detected
 
 Failing test: [test name]
 Error: [error message]
@@ -285,14 +295,40 @@ Fix the regression and re-run tests. Iterate until all related tests pass.
 **When all related tests pass:**
 
 ```
-✅ Related Tests Passing
+Related Tests Passing
 
-- Regression test: ✅ PASS
-- Related area tests: ✅ [X] scenarios passing
+- Regression test: PASS
+- Related area tests: [X] scenarios passing
 
 Ready to commit and merge.
 ```
 
+**Proceed to Step 3B.**
+
+**Quality Gate:** Before committing, review every `.steps.js` file you wrote or modified. Check for banlist violations: `setTimeout`/`sleep`, module-level `let`/`var`, raw SQL, assertions in Given/When, self-fulfilling mocks, steps longer than 5 lines. Fix violations before proceeding.
+
+---
+
+### Step 3B: Prove It Works
+
+**Before committing, demonstrate the fix works in practice — not just that tests pass.**
+
+1. **Run or build the actual code** — compile, start the server, execute the command, or trigger the relevant workflow
+2. **Show real output** — display console output, build result, or observable behavior
+3. **Confirm the bug is fixed** — verify the original bug scenario no longer reproduces
+
+**Display:**
+
+```
+Verifying fix in practice...
+
+[Actual output from running/building the code]
+
+Verified: [what was confirmed — original bug no longer reproduces]
+```
+
+**If the change cannot be run directly** (requires hardware, external service, or manual UI interaction), state what the user should verify manually and why you can't verify it yourself.
+
 **Proceed to Step 4.**
 
 ---
@@ -315,7 +351,7 @@ Fix: [What was changed]
 
 Closes #<bug-id>
 
-🤖 Generated with [Claude Code](https://claude.com/claude-code)
+Generated with [Claude Code](https://claude.com/claude-code)
 
 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>"
 ```
@@ -327,6 +363,8 @@ Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>"
 jettypod work merge <bug-id>
 ```
 
+**If merge fails with `Uncommitted changes detected`:** `git stash` from main repo CWD → create a work item for the stashed changes → `jettypod work start <id>` → `git stash pop` in that worktree → commit → merge → cleanup → then retry your original merge.
+
 ```bash
 # Step 2: cd to main repo
 cd <main-repo-path>
@@ -347,6 +385,22 @@ jettypod work cleanup <bug-id>
 **The merge command automatically sets the bug as ready for review.**
 It will appear with accept/reject buttons on the kanban board. Do NOT call `jettypod work status <bug-id> done` — that bypasses the review gate.
 
+**Generate QA checklist:**
+
+Based on the bug fix and regression test, generate specific QA steps to verify the fix and ensure no regressions. Write a JSON array to `/tmp/qa-steps.json`:
+```json
+[
+  {"section": "Bug Fix Verification", "text": "Reproduce the original bug scenario — it should no longer occur", "detail": "Steps to reproduce..."},
+  {"section": "Regression Check", "text": "Verify related functionality still works", "detail": "..."},
+  ...
+]
+```
+Be specific. 3-8 steps covering: original bug fixed, regression scenarios, edge cases.
+
+```bash
+jettypod work set-qa-steps <bug-id> --from=/tmp/qa-steps.json
+```
+
 **Emit gate signal:**
 
 ```bash
@@ -357,11 +411,11 @@ jettypod ui gate complete --data='{"summary":"Bug fixed: [brief description]","f
 
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-✅ Bug Fix Complete
+Bug Fix Complete
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-🐛 Bug: #[bug-id] [title]
-🧪 Regression test: ✅ features/<bug-slug>.feature
+Bug: #[bug-id] [title]
+Regression test: features/<bug-slug>.feature
 
 What was fixed:
 - Root cause: [brief description]
@@ -400,4 +454,9 @@ cd <main-repo>                   # Change to main repo
 jettypod work cleanup <bug-id>   # Clean up worktree
 ```
 
-**⚠️ Do NOT mark bug as done manually — the merge command sets the review gate automatically.**
+**Force-cleanup stale worktree** (when merge is blocked or fix was superseded):
+```bash
+jettypod work cleanup --force <bug-id>   # Bypasses merge requirement, prompts for confirmation
+```
+
+**Do NOT mark bug as done manually — the merge command sets the review gate automatically.**