jettypod 4.4.118 → 4.4.121

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

@@ -30,7 +30,7 @@ When this skill is activated, you are investigating a bug to identify root cause
 **Gather from user:**
 
 ```
-🐛 Bug Investigation
+Bug Investigation
 
 I need to understand the bug before we investigate.
 
@@ -61,7 +61,7 @@ I need to understand the bug before we investigate.
 
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-📋 Bug Report
+Bug Report
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 **Symptom:** [What's happening]
@@ -105,7 +105,7 @@ git log --oneline -10 -- <relevant-files>
 **Display hypotheses:**
 
 ```
-🔍 Hypotheses
+Hypotheses
 
 Based on symptoms and codebase analysis:
 
@@ -148,12 +148,12 @@ Starting evidence gathering with H1...
 ```
 ━━━ Testing H1: [Title] ━━━
 
-📂 Reading: [file:lines]
-🔎 Looking for: [specific issue]
+Reading: [file:lines]
+Looking for: [specific issue]
 
 **Finding:** [What you discovered]
 
-**Verdict:** ✅ CONFIRMED / ❌ ELIMINATED / ⚠️ PARTIAL
+**Verdict:** CONFIRMED / ELIMINATED / PARTIAL
 ```
 
 **If ELIMINATED:** Move to next hypothesis.
@@ -163,7 +163,7 @@ Starting evidence gathering with H1...
 **If all hypotheses eliminated:**
 
 ```
-⚠️ Initial hypotheses eliminated
+Initial hypotheses eliminated
 
 What we learned:
 - H1: Eliminated because [reason]
@@ -182,11 +182,11 @@ Loop back to Phase 2 with new information.
 
 **Goal:** Confirm root cause with user before creating work item.
 
-**⚡ ASYNC BOUNDARY - Wait for user confirmation**
+**ASYNC BOUNDARY - Wait for user confirmation**
 
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-🎯 Root Cause Identified
+Root Cause Identified
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 **What's broken:** [Specific code/logic]
@@ -212,24 +212,20 @@ If user disagrees or adds context, revise understanding and confirm again.
 
 **Goal:** Create tracked bug work item with breadcrumbs for implementation.
 
-**Create bug work item with description:**
+**Create bug work item with description (using --from for truncation safety):**
 
-```bash
-jettypod work create bug "[Bug title - brief description]" "Root cause: [What's broken and why]
-Location: [file:line]
-
-Fix approach:
-- [Step 1]
-- [Step 2]
-
-Files to modify:
-- [file1]: [what to change]
-- [file2]: [what to change]
+Use the **Write** tool to create `/tmp/jettypod-create.json`:
+```json
+{
+  "type": "bug",
+  "title": "[Bug title - brief description]",
+  "description": "Root cause: [What's broken and why]\nLocation: [file:line]\n\nFix approach:\n- [Step 1]\n- [Step 2]\n\nFiles to modify:\n- [file1]: [what to change]\n- [file2]: [what to change]\n\nVerification:\n- Regression test passes\n- Original bug no longer reproduces\n- [Any other checks]"
+}
+```
 
-Verification:
-- Regression test passes
-- Original bug no longer reproduces
-- [Any other checks]"
+Then run via **Bash**:
+```bash
+jettypod work create --from=/tmp/jettypod-create.json
 ```
 
 **Capture the bug ID from output.**
@@ -252,12 +248,12 @@ jettypod ui gate work-created --data='{"id":<bug-id>,"title":"[bug title]"}'
 
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-✅ Bug Planning Complete
+Bug Planning Complete
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-📋 Bug: #<bug-id> [title]
-📍 Root cause: [file:line]
-🔧 Fix approach: [brief summary]
+Bug: #<bug-id> [title]
+Root cause: [file:line]
+Fix approach: [brief summary]
 
 Ready to implement the fix?
 ```

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

@@ -40,13 +40,14 @@ When this skill is activated, you are executing a standalone chore. The chore-pl
 | Type | Test Handling | Key Constraint |
 |------|---------------|----------------|
 | refactor | Affected tests only | Do NOT modify test assertions |
-| dependency | Full test suite | Check for deprecation warnings |
+| dependency | Affected + impacted tests | Check for deprecation warnings |
 | cleanup | Affected tests | Verify code is actually unused |
 | tooling | CI/manual verification | Focus on verification over unit tests |
+| enhancement | TDD: write tests first | RED → GREEN → REFACTOR cycle |
 
 ---
 
-## 🚨 SHELL CWD RECOVERY
+## SHELL CWD RECOVERY
 
 **If ALL bash commands start failing with "Error: Exit code 1" and no output:**
 
@@ -68,11 +69,11 @@ Your shell's working directory was likely inside a worktree that was deleted. Th
 
 **Your task:** Acknowledge the context passed from chore-planning.
 
-**🚫 FORBIDDEN: Writing Files at This Step**
+**FORBIDDEN: Writing Files at This Step**
 ```
-❌ Write tool to any path
-❌ Edit tool to any path
-❌ Any file creation or modification
+Write tool to any path
+Edit tool to any path
+Any file creation or modification
 ```
 **This is a CONTEXT step.** File writes happen in Step 5.
 
@@ -89,7 +90,7 @@ You will receive:
 
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-🔧 Chore Mode: [Chore Title]
+Chore Mode: [Chore Title]
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 Type: [TYPE] (confidence: [high/medium/low])
@@ -104,12 +105,12 @@ Implementation Plan:
 
 Add this line after Chore ID:
 ```
-⚡ Technical Epic Chore - no mode progression
+Technical Epic Chore - no mode progression
 ```
 
 This confirms the chore belongs to a technical epic and will execute directly without any speed→stable→production phases (which is the default for all chores anyway).
 
-**🔄 WORKFLOW INTEGRATION: Start workflow tracking**
+**WORKFLOW INTEGRATION: Start workflow tracking**
 
 After receiving context, register this skill execution:
 
@@ -125,11 +126,11 @@ This validates that `chore_planning_complete` gate is passed (if applicable) and
 
 **Your task:** Create an isolated worktree for this chore.
 
-**🚫 FORBIDDEN: Manual Git Worktree Commands**
+**FORBIDDEN: Manual Git Worktree Commands**
 ```
-❌ git worktree add ...
-❌ git checkout -b feature/...
-❌ git branch feature/...
+git worktree add ...
+git checkout -b feature/...
+git branch feature/...
 ```
 **ALWAYS use `jettypod work start`** - it handles branch naming, path conventions, database tracking, and cleanup. Manual git commands will create orphaned worktrees that break the merge workflow.
 
@@ -139,7 +140,7 @@ jettypod work start [chore-id]
 
 This creates a worktree at `.jettypod-work/[id]-[title-slug]` and switches to a new branch.
 
-**🛑 VALIDATION REQUIRED:** After running `work start`, verify the worktree was created:
+**VALIDATION REQUIRED:** After running `work start`, verify the worktree was created:
 
 ```bash
 sqlite3 .jettypod/work.db "SELECT worktree_path FROM worktrees WHERE work_item_id = [chore-id] AND status = 'active'"
@@ -147,20 +148,20 @@ sqlite3 .jettypod/work.db "SELECT worktree_path FROM worktrees WHERE work_item_i
 
 | Result | What it means | Action |
 |--------|---------------|--------|
-| **Has a path** | ✅ Worktree created successfully | Continue to Step 3 |
-| **Empty/no rows** | ❌ Worktree creation failed | **STOP - check the error output from `work start` and resolve before continuing** |
+| **Has a path** | Worktree created successfully | Continue to Step 3 |
+| **Empty/no rows** | Worktree creation failed | **STOP - check the error output from `work start` and resolve before continuing** |
 
 **Display (on success):**
 
 ```
-📁 Worktree created: .jettypod-work/[id]-[title-slug]
+Worktree created: .jettypod-work/[id]-[title-slug]
 Branch: chore-[id]-[title-slug]
 ```
 
 **Display (on failure):**
 
 ```
-❌ Worktree creation failed. Check:
+Worktree creation failed. Check:
   - Are there uncommitted changes? Run: git status
   - Does the branch already exist? Run: git branch -a | grep [chore-id]
   - Is there a worktree conflict? Run: git worktree list
@@ -170,7 +171,7 @@ Resolve the issue before continuing.
 
 **Move to Step 3 only if worktree was created successfully.**
 
-**🔒 WORKTREE PATH LOCK**
+**WORKTREE PATH LOCK**
 
 After worktree validation passes, capture and lock the path:
 - `WORKTREE_PATH` - the absolute path from the query result
@@ -178,7 +179,7 @@ After worktree validation passes, capture and lock the path:
 **Display:**
 
 ```
-🔒 WORKTREE LOCK ACTIVE
+WORKTREE LOCK ACTIVE
 Path: ${WORKTREE_PATH}
 
 All file writes will use this path.
@@ -196,11 +197,11 @@ jettypod ui gate worktree-started --data='{"path":"${WORKTREE_PATH}"}'
 
 **Your task:** Run tests to establish baseline before making changes.
 
-**🚫 FORBIDDEN: Writing Files at This Step**
+**FORBIDDEN: Writing Files at This Step**
 ```
-❌ Write tool to any path
-❌ Edit tool to any path
-❌ Any file creation or modification
+Write tool to any path
+Edit tool to any path
+Any file creation or modification
 ```
 **This is a TESTING step.** File writes happen in Step 5.
 
@@ -214,8 +215,8 @@ npm test -- [affected-test-patterns]
 
 **For DEPENDENCY:**
 ```bash
-# Run full test suite
-npm test
+# Run tests for affected and potentially impacted modules
+npm test -- [affected-test-patterns]
 ```
 
 **For CLEANUP:**
@@ -230,21 +231,28 @@ npm test -- [affected-test-patterns]
 # (may not have unit tests)
 ```
 
+**For ENHANCEMENT:**
+```bash
+# Run existing affected tests to establish baseline (these must keep passing)
+npm test -- [affected-test-patterns]
+# Note: No new tests exist yet - they will be written in Step 5 (TDD RED phase)
+```
+
 **Display:**
 
 ```
-🧪 Establishing test baseline...
+Establishing test baseline...
 
 Baseline Result:
   Tests: [X] passing / [Y] total
   Execution time: [Z]s
 
-✅ Baseline established - all tests passing
+Baseline established - affected tests passing
 ```
 
 **CRITICAL:** If baseline tests fail, STOP. Fix existing failures before proceeding with chore work.
 
-**🔄 WORKFLOW CHECKPOINT: Test baseline established**
+**WORKFLOW CHECKPOINT: Test baseline established**
 
 ```bash
 jettypod workflow checkpoint <chore-id> --step=3
@@ -256,11 +264,11 @@ jettypod workflow checkpoint <chore-id> --step=3
 
 **Your task:** Display warnings and constraints based on chore type.
 
-**🚫 FORBIDDEN: Writing Files at This Step**
+**FORBIDDEN: Writing Files at This Step**
 ```
-❌ Write tool to any path
-❌ Edit tool to any path
-❌ Any file creation or modification
+Write tool to any path
+Edit tool to any path
+Any file creation or modification
 ```
 **This is a GUIDANCE step.** File writes happen in Step 5.
 
@@ -275,9 +283,9 @@ const guidance = getGuidance('[chore-type]');
 
 **For REFACTOR:**
 ```
-⚠️  REFACTOR CONSTRAINTS:
+ REFACTOR CONSTRAINTS:
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-• All existing tests MUST pass WITHOUT modification
+• Affected tests MUST pass WITHOUT modification
 • If tests fail, the refactor broke behavior - FIX THE CODE, not the tests
 • No new functionality - this is restructuring only
 • Behavior must be preserved exactly
@@ -285,9 +293,9 @@ const guidance = getGuidance('[chore-type]');
 
 **For DEPENDENCY:**
 ```
-⚠️  DEPENDENCY CONSTRAINTS:
+ DEPENDENCY CONSTRAINTS:
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-• Run FULL test suite to catch regressions
+• Run tests for affected and potentially impacted modules to catch regressions
 • Check for deprecation warnings after update
 • Review changelog for breaking changes
 • Update code if API changed
@@ -295,7 +303,7 @@ const guidance = getGuidance('[chore-type]');
 
 **For CLEANUP:**
 ```
-⚠️  CLEANUP CONSTRAINTS:
+ CLEANUP CONSTRAINTS:
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 • VERIFY code is actually unused before deleting
 • Search for all references (grep for function names)
@@ -305,7 +313,7 @@ const guidance = getGuidance('[chore-type]');
 
 **For TOOLING:**
 ```
-⚠️  TOOLING CONSTRAINTS:
+ TOOLING CONSTRAINTS:
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 • Verify via CI run or manual testing
 • Focus on verification over unit testing
@@ -313,13 +321,28 @@ const guidance = getGuidance('[chore-type]');
 • Plan rollback strategy
 ```
 
+**For ENHANCEMENT:**
+```
+ ENHANCEMENT CONSTRAINTS (TDD):
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+• RED: Write failing tests FIRST that define the new behavior
+• GREEN: Write MINIMUM code to make tests pass
+• REFACTOR: Clean up code while keeping tests green
+• Existing affected tests MUST still pass after implementation
+• Do NOT write implementation before tests
+```
+
 **Move to Step 5 automatically.**
 
+### BDD Step Definition Constraints (ENFORCED)
+
+If this chore involves writing step definitions, read `templates/bdd-guidance.md` first. 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.
+
 ### Step 5: Execute with Iteration
 
-**🔒 WORKTREE PATH REQUIRED:** All file writes MUST use the `WORKTREE_PATH` captured in Step 2.
+**WORKTREE PATH REQUIRED:** All file writes MUST use the `WORKTREE_PATH` captured in Step 2.
 
-**✅ NOW you may write files** - worktree is locked, guidance is displayed.
+**NOW you may write files** - worktree is locked, guidance is displayed.
 
 **Emit gate signal:**
 
@@ -329,13 +352,40 @@ jettypod ui gate implementing --data='{"description":"[chore implementation]","f
 
 **Your task:** Make changes and iterate until tests pass. Max 5 iterations.
 
+**For ENHANCEMENT type, follow TDD cycle instead of the standard iteration:**
+
+```
+━━━ TDD RED Phase ━━━
+Writing tests that define the new behavior...
+[Write test files that assert expected behavior - these MUST FAIL initially]
+
+Running new tests (expecting failures)...
+[Confirm tests fail - this validates the tests are meaningful]
+
+━━━ TDD GREEN Phase ━━━
+Implementing minimum code to pass tests...
+[Write the simplest implementation that makes tests pass]
+
+Running tests...
+[Confirm new tests pass + existing affected tests still pass]
+
+━━━ TDD REFACTOR Phase ━━━
+Cleaning up implementation...
+[Refactor for clarity, remove duplication, improve naming]
+
+Running tests (confirming still green)...
+[All tests must still pass after refactoring]
+```
+
+**For behavior-preserving types (refactor, dependency, cleanup, tooling), use standard iteration:**
+
 ```
 ━━━ Iteration [N]/5 ━━━
 
-✍️  Making changes...
+ Making changes...
 [Describe what you're changing]
 
-🧪 Running tests...
+Running tests...
 ```
 
 **On each iteration:**
@@ -346,22 +396,22 @@ jettypod ui gate implementing --data='{"description":"[chore implementation]","f
 **Display progress:**
 
 ```
-📊 Progress: [X]/[Y] tests passing
+Progress: [X]/[Y] tests passing
 
-✅ Newly passing:
+Newly passing:
   • [test name]
 
-❌ Still failing:
+Still failing:
   • [test name]: [brief error]
 
-🔧 Next: [what you'll fix]
+Next: [what you'll fix]
 ```
 
 **Exit conditions:**
-- ✅ All tests pass → Move to Step 6
-- ❌ Max iterations reached → Display failure, ask user for guidance
+- Affected tests pass → Move to Step 6
+- Max iterations reached → Display failure, ask user for guidance
 
-**🔄 WORKFLOW CHECKPOINT: Execution complete** (when all tests pass)
+**WORKFLOW CHECKPOINT: Execution complete** (when affected tests pass)
 
 ```bash
 jettypod workflow checkpoint <chore-id> --step=5
@@ -370,7 +420,7 @@ jettypod workflow checkpoint <chore-id> --step=5
 **On max iterations:**
 
 ```
-⚠️  Maximum iterations (5) reached
+ Maximum iterations (5) reached
 
 Final Progress: [X]/[Y] tests passing
 
@@ -403,17 +453,17 @@ const guidance = getGuidance('[chore-type]');
 
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-🔍 Verification Checklist
+Verification Checklist
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-[✅/❌] All existing tests pass without modification
-[✅/❌] No new functionality added
-[✅/❌] Code review confirms behavior preservation
-[✅/❌] Performance is not degraded
+[/] Affected tests pass without modification
+[/] No new functionality added
+[/] Code review confirms behavior preservation
+[/] Performance is not degraded
 ```
 
 **Verification methods:**
-- **Tests pass**: Run `npm test` and check exit code
+- **Tests pass**: Run `npm test -- [affected-test-patterns]` and check exit code
 - **No new functionality**: Review diff for new features
 - **Behavior preservation**: Compare before/after behavior
 - **Performance**: Run benchmarks if applicable
@@ -421,7 +471,7 @@ const guidance = getGuidance('[chore-type]');
 **If any verification fails:**
 
 ```
-❌ Verification failed:
+Verification failed:
   • [failed item]: [reason]
 
 Returning to iteration loop...
@@ -429,7 +479,29 @@ Returning to iteration loop...
 
 Go back to Step 5 to fix issues.
 
-**If all verification passes → Move to Step 7.**
+**If all verification passes → Move to Step 6B.**
+
+### Step 6B: Prove It Works
+
+**Before committing, demonstrate the change 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 it matches expectations** — verify the output is what was requested
+
+**Display:**
+
+```
+Verifying in practice...
+
+[Actual output from running/building the code]
+
+Verified: [what was confirmed]
+```
+
+**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.
+
+**Move to Step 7.**
 
 ### Step 7: Complete and Merge
 
@@ -455,6 +527,8 @@ git push
 jettypod work merge [chore-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 /path/to/main/repo
@@ -466,11 +540,26 @@ pwd && ls .jettypod  # verify
 jettypod work cleanup [chore-id]
 ```
 
+**Generate QA checklist:**
+
+Based on the chore work completed, generate specific QA steps. Write a JSON array to `/tmp/qa-steps.json`:
+```json
+[
+  {"section": "Section Name", "text": "Action to perform and expected result", "detail": "Additional context"},
+  ...
+]
+```
+Be specific. 3-8 steps covering what was changed and how to verify it works.
+
+```bash
+jettypod work set-qa-steps [chore-id] --from=/tmp/qa-steps.json
+```
+
 **Display:**
 
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-✅ Chore Complete
+Chore Complete
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 Type: [TYPE]
@@ -478,15 +567,15 @@ Iterations: [N]/5
 Tests: [X]/[Y] passing
 
 Verification:
-✅ All existing tests pass without modification
-✅ No new functionality added
-✅ Code review confirms behavior preservation
-✅ Performance is not degraded
+Affected tests pass without modification
+No new functionality added
+Code review confirms behavior preservation
+Performance is not degraded
 
 Merged to main. Chore #[id] marked done.
 ```
 
-**🔄 WORKFLOW INTEGRATION: Complete workflow**
+**WORKFLOW INTEGRATION: Complete workflow**
 
 ```bash
 jettypod workflow complete chore-mode <chore-id>
@@ -508,7 +597,7 @@ This marks the `chore_mode_complete` gate as passed. The standalone chore is now
 
 ### Baseline Tests Fail
 ```
-❌ Cannot proceed - baseline tests failing
+Cannot proceed - baseline tests failing
 
 [X] tests failing before chore work started.
 Fix existing test failures before proceeding.
@@ -520,7 +609,7 @@ Failing tests:
 ### Verification Loop
 If verification fails repeatedly (3+ times on same item):
 ```
-⚠️  Verification stuck on: [item]
+ Verification stuck on: [item]
 
 This has failed [N] times. Options:
 1. Review the implementation approach
@@ -530,7 +619,7 @@ This has failed [N] times. Options:
 
 ### Worktree Issues
 ```
-❌ Worktree creation failed
+Worktree creation failed
 
 Error: [message]
 
@@ -539,6 +628,13 @@ Try:
   jettypod work start [chore-id]
 ```
 
+### Stale/Orphaned Worktree
+If a worktree is stuck active (e.g., fix was superseded, merge conflicts with main, or work was abandoned):
+```bash
+jettypod work cleanup --force <id>   # Bypasses merge requirement, prompts for confirmation
+```
+This checks for unmerged commits and uncommitted changes, warns you, and marks the work item as cancelled.
+
 ---
 
 ## Type Reference
@@ -551,7 +647,7 @@ Try:
 
 ### DEPENDENCY
 - **Goal:** Update packages safely
-- **Tests:** Full suite
+- **Tests:** Affected + impacted modules
 - **Key rule:** Check changelogs for breaking changes
 - **Verification:** Tests pass, no deprecation warnings
 
@@ -566,3 +662,9 @@ Try:
 - **Tests:** CI pipeline or manual
 - **Key rule:** Plan rollback strategy
 - **Verification:** CI passes, workflows work
+
+### ENHANCEMENT
+- **Goal:** Add new behavior with TDD
+- **Tests:** Write new tests FIRST (TDD), then implement
+- **Key rule:** RED → GREEN → REFACTOR - never implement before tests
+- **Verification:** New tests written and passing, existing tests unbroken