jettypod 4.4.116 → 4.4.120

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

@@ -18,7 +18,7 @@ description: Guide implementation of stable mode chores with comprehensive testi
 └─────────────────────────────────────────────────────────────────────┘
 ```
 
-## 🛑 CRITICAL HANDOFF REQUIREMENT
+## CRITICAL HANDOFF REQUIREMENT
 
 **After completing ALL stable mode chores:**
 
@@ -30,7 +30,7 @@ description: Guide implementation of stable mode chores with comprehensive testi
 1. Set feature mode to production
 2. **IMMEDIATELY invoke production-mode using the Skill tool**
 
-**🛑 STOP GATE:** For external projects, DO NOT end this skill without invoking production-mode. Stable mode makes it robust - production mode makes it ready for real users at scale.
+**STOP GATE:** For external projects, DO NOT end this skill without invoking production-mode. Stable mode makes it robust - production mode makes it ready for real users at scale.
 
 ---
 
@@ -40,7 +40,7 @@ Guides Claude Code through stable mode implementation with comprehensive testing
 
 When this skill is activated, you are helping implement a stable mode chore to add comprehensive testing and error handling. Follow this structured approach:
 
-## 🔑 Critical Context
+## Critical Context
 
 **You are working in an isolated git worktree:**
 - `work start [chore-id]` created a dedicated worktree for this chore
@@ -52,7 +52,7 @@ When this skill is activated, you are helping implement a stable mode chore to a
 
 ---
 
-## 🚨 SHELL CWD RECOVERY
+## SHELL CWD RECOVERY
 
 **If ALL bash commands start failing with "Error: Exit code 1" and no output:**
 
@@ -68,7 +68,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 with ANY implementation, you MUST validate the worktree exists.**
 
@@ -82,17 +82,17 @@ sqlite3 .jettypod/work.db "SELECT wi.id, wi.title, wi.status, wt.worktree_path,
 
 | worktree_path | What it means | Action |
 |---------------|---------------|--------|
-| **Has a path** (e.g., `/path/to/.jettypod-work/...`) | ✅ Worktree exists, ready to proceed | Continue to Step 0 |
-| **NULL or empty** | ❌ `work start` was not called | **STOP - run `jettypod work start [chore-id]` first** |
-| **No rows returned** | ❌ No chore is in progress | **STOP - verify the chore exists and run `work start`** |
+| **Has a path** (e.g., `/path/to/.jettypod-work/...`) | Worktree exists, ready to proceed | Continue to Step 0 |
+| **NULL or empty** | `work start` was not called | **STOP - run `jettypod work start [chore-id]` first** |
+| **No rows returned** | No chore is in progress | **STOP - verify the chore exists and run `work start`** |
 
-**🛑 STOP GATE:** If `worktree_path` is NULL or no rows returned, you MUST run `jettypod work start [chore-id]` before continuing. DO NOT proceed without a valid worktree.
+**STOP GATE:** If `worktree_path` is NULL or no rows returned, you MUST run `jettypod work start [chore-id]` before continuing. DO NOT proceed without a valid worktree.
 
-**🚫 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.
 
@@ -109,7 +109,7 @@ sqlite3 .jettypod/work.db "SELECT wi.id, wi.title, wi.status, wt.worktree_path,
 
 ---
 
-## 🔒 WORKTREE PATH LOCK
+## WORKTREE PATH LOCK
 
 **After pre-flight validation passes, capture and lock the worktree path:**
 
@@ -119,7 +119,7 @@ From the pre-flight query output, extract and store:
 **Display:**
 
 ```
-🔒 WORKTREE LOCK ACTIVE
+WORKTREE LOCK ACTIVE
 Path: ${WORKTREE_PATH}
 
 All file writes will use this path.
@@ -154,7 +154,7 @@ jettypod ui gate worktree-started --data='{"path":"${WORKTREE_PATH}"}'
 **User Profile:** May not know how to code - Claude Code does the implementation autonomously.
 
 <details>
-<summary><strong>📋 What Stable Mode Includes (click to expand)</strong></summary>
+<summary><strong>What Stable Mode Includes (click to expand)</strong></summary>
 
 **Stable Mode is NOT just error handling. It includes:**
 
@@ -194,7 +194,7 @@ jettypod ui gate worktree-started --data='{"path":"${WORKTREE_PATH}"}'
 
 ---
 
-## 🧪 Unit Testing in Stable Mode - True TDD
+## Unit Testing in Stable Mode - True TDD
 
 **Unit tests are written DURING implementation, not after.**
 
@@ -214,10 +214,10 @@ jettypod ui gate worktree-started --data='{"path":"${WORKTREE_PATH}"}'
 - State consistency (transaction rollback, cleanup on failure)
 
 <details>
-<summary><strong>📋 Unit Test Examples (click to expand)</strong></summary>
+<summary><strong>Unit Test Examples (click to expand)</strong></summary>
 
 ```javascript
-// ✅ Stable mode unit tests (error paths and edge cases)
+// Stable mode unit tests (error paths and edge cases)
 test('createUser throws ValidationError for null email', () => {
   expect(() => createUser('John', null)).toThrow(ValidationError);
   expect(() => createUser('John', null)).toThrow('Email is required');
@@ -266,7 +266,7 @@ test('getUserById returns null for non-existent user', () => {
 sqlite3 .jettypod/work.db "SELECT wi.id, wi.title, wi.parent_id, parent.title as parent_title, parent.scenario_file, wt.worktree_path, wt.branch_name FROM work_items wi LEFT JOIN work_items parent ON wi.parent_id = parent.id LEFT JOIN worktrees wt ON wi.id = wt.work_item_id WHERE wi.status = 'in_progress' AND wi.type = 'chore'"
 ```
 
-**🔄 WORKFLOW INTEGRATION: Start workflow tracking**
+**WORKFLOW INTEGRATION: Start workflow tracking**
 
 After getting the work context, register this skill execution:
 
@@ -280,7 +280,7 @@ This validates that `speed_mode_complete` gate is passed and creates an executio
 
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-🛡️  STABLE MODE: Implementing Chore #[id]
+ STABLE MODE: Implementing Chore #[id]
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 Chore: [title]
@@ -299,11 +299,11 @@ Analyzing stable mode BDD scenarios to determine what error handling and validat
 
 **CRITICAL:** Claude Code executes this autonomously - no user permission needed.
 
-**🚫 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 an ANALYSIS step.** File writes happen in Step 5.
 
@@ -331,15 +331,15 @@ sqlite3 .jettypod/work.db "SELECT wi.id, wi.title, wi.description, wi.parent_id,
 4. If no match found, list available scenarios and ask which one to implement
 
 **Handle errors gracefully:**
-- If no current work: "❌ No current work found. Run: jettypod work start <chore-id>"
-- If no parent feature: "❌ Current work has no parent feature."
-- If no scenario_file: "❌ Feature has no scenario_file."
+- If no current work: "No current work found. Run: jettypod work start <chore-id>"
+- If no parent feature: "Current work has no parent feature."
+- If no scenario_file: "Feature has no scenario_file."
 - If can't match chore to scenario: List available scenarios and ask user
 
 **Display to user:**
 
 ```
-🧪 Stable Mode: [Feature Name]
+Stable Mode: [Feature Name]
 
 Target Scenario:
 [Scenario title]
@@ -364,11 +364,11 @@ Now reviewing speed mode implementation...
 
 **CRITICAL:** Claude Code executes this autonomously - no user permission needed.
 
-**🚫 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 an ANALYSIS step.** File writes happen in Step 5.
 
@@ -399,14 +399,14 @@ Then use the Read tool to examine the implementation files.
 **Display analysis:**
 
 ```
-📊 Code Analysis Complete
+Code Analysis Complete
 
 Current Implementation:
 • Files: [list]
-• Success scenarios: ✅ Working (from speed mode)
-• Error handling: ❌ Missing [specific gaps]
-• Validation: ❌ Missing [specific gaps]
-• Edge cases: ❌ Not handled [specific gaps]
+• Success scenarios: Working (from speed mode)
+• Error handling: Missing [specific gaps]
+• Validation: Missing [specific gaps]
+• Edge cases: Not handled [specific gaps]
 
 To pass the target scenario, I need to:
 1. [Specific change]
@@ -416,7 +416,7 @@ To pass the target scenario, I need to:
 Now proposing comprehensive implementation...
 ```
 
-**🔄 WORKFLOW CHECKPOINT: Code analysis complete**
+**WORKFLOW CHECKPOINT: Code analysis complete**
 
 ```bash
 jettypod workflow checkpoint <feature-id> --step=2
@@ -424,11 +424,11 @@ jettypod workflow checkpoint <feature-id> --step=2
 
 ### Step 3: Decide if Confirmation Needed
 
-**🚫 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 DECISION step.** File writes happen in Step 5.
 
@@ -448,20 +448,20 @@ jettypod workflow checkpoint <feature-id> --step=2
 
 ### Step 3A: Propose Implementation Approach (Conditional)
 
-**⚡ ASYNC BOUNDARY - Only execute this if confirmation needed**
+**ASYNC BOUNDARY - Only execute this if confirmation needed**
 
-**🚫 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 PROPOSAL step.** File writes happen in Step 5.
 
 **Present your analysis and proposal to the user:**
 
 ```
-💡 Implementation Proposal
+Implementation Proposal
 
 I see multiple ways to approach this error handling. Here's what I'm thinking:
 
@@ -476,7 +476,7 @@ I see multiple ways to approach this error handling. Here's what I'm thinking:
 Sound good, or would you prefer a different approach?
 ```
 
-**⚡ WAIT for user confirmation or adjustments.**
+**WAIT for user confirmation or adjustments.**
 
 If user adjusts: revise proposal and confirm again before proceeding.
 
@@ -484,6 +484,16 @@ If user adjusts: revise proposal and confirm again before proceeding.
 
 ---
 
+### 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 4: Establish RED Baseline
 
 **CRITICAL:** After user confirms (or skips confirmation), execute autonomously - no permission needed for code changes.
@@ -528,25 +538,25 @@ Parse the output to identify:
 
 **Display RED baseline:**
 ```
-🔴 Establishing RED baseline...
+Establishing RED baseline...
 
 RED Baseline: 3 of 11 steps failing (stable mode scenarios)
 
 Failing steps:
-  ✖ Then it should throw a validation error
-  ✖ And the error message should be "Email is required"
-  ✖ When I provide an empty string as input
+  Then it should throw a validation error
+  And the error message should be "Email is required"
+  When I provide an empty string as input
 
 First error:
   Step: Then it should throw a validation error
   Error: Error: Expected function to throw but it didn't
 
-🎯 Goal: Make all stable mode scenarios pass
+Goal: Make all stable mode scenarios pass
 
 Now implementing...
 ```
 
-**🔄 WORKFLOW CHECKPOINT: RED baseline established**
+**WORKFLOW CHECKPOINT: RED baseline established**
 
 ```bash
 jettypod workflow checkpoint <feature-id> --step=4
@@ -556,9 +566,9 @@ jettypod workflow checkpoint <feature-id> --step=4
 
 ### Step 5: RED→GREEN→REFACTOR Loop
 
-**🔒 WORKTREE PATH REQUIRED:** All file writes MUST use the `WORKTREE_PATH` captured after pre-flight validation.
+**WORKTREE PATH REQUIRED:** All file writes MUST use the `WORKTREE_PATH` captured after pre-flight validation.
 
-**✅ NOW you may write files** - worktree is locked, approach is confirmed.
+**NOW you may write files** - worktree is locked, approach is confirmed.
 
 **Emit gate signal:**
 
@@ -581,23 +591,23 @@ jettypod ui gate implementing --data='{"description":"[stable mode error handlin
 **Show progress each iteration:**
 ```
 ━━━ Iteration 3/10 ━━━
-📝 Unit test: test/user.test.js - validates email format
+Unit test: test/user.test.js - validates email format
    RED: Test fails - no validation exists yet
-✍️  Implementation: src/user.js - added email format validation
+ Implementation: src/user.js - added email format validation
    GREEN: Unit test passes
-🧪 Running BDD scenarios...
-📊 Progress: 9/11 BDD steps passing
-✅ Newly passing: Then it should throw a validation error
-🔧 Next failure: And the error message should be user-friendly
+Running BDD scenarios...
+Progress: 9/11 BDD steps passing
+Newly passing: Then it should throw a validation error
+Next failure: And the error message should be user-friendly
     BDD step: Then the error message should be "Email format is invalid"
 ```
 
 **When GREEN achieved:**
 ```
-🎉 GREEN: All stable mode scenarios passing!
+GREEN: All stable mode scenarios passing!
 ```
 
-**🔄 WORKFLOW CHECKPOINT: GREEN achieved**
+**WORKFLOW CHECKPOINT: GREEN achieved**
 
 ```bash
 jettypod workflow checkpoint <feature-id> --step=5
@@ -612,7 +622,7 @@ jettypod workflow checkpoint <feature-id> --step=5
 **Re-run tests after refactor** to ensure nothing broke.
 
 <details>
-<summary><strong>📋 TDD Loop Guidelines (click to expand)</strong></summary>
+<summary><strong>TDD Loop Guidelines (click to expand)</strong></summary>
 
 **Iteration strategy:**
 - Start with first failing stable mode step
@@ -632,6 +642,8 @@ jettypod workflow checkpoint <feature-id> --step=5
 
 </details>
 
+**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 6: Route After Chore Completion
@@ -654,10 +666,10 @@ sqlite3 .jettypod/work.db "SELECT id, title FROM work_items WHERE parent_id = <f
 
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-🎯 Stable Mode Chore Complete
+Stable Mode Chore Complete
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-✅ Error handling and validation scenarios pass for this chore
+Error handling and validation scenarios pass for this chore
 
 More stable mode chores remain. Starting next chore:
 #[next-chore-id]: [next-chore-title]
@@ -699,7 +711,7 @@ If the query returns no remaining chores, proceed to Step 7.
 
 ### Step 7: Complete Feature or Transition to Production Mode
 
-**🛑 CRITICAL: This step ONLY runs after ALL stable chores are complete.**
+**CRITICAL: This step ONLY runs after ALL stable chores are complete.**
 
 **First, merge the final stable chore:**
 
@@ -741,27 +753,26 @@ sqlite3 .jettypod/work.db "SELECT project_state FROM project_config WHERE id = 1
 
 **If project_state = 'internal':**
 
-```bash
-jettypod work status <feature-id> done
-```
+**The merge command automatically sets the feature as ready for review.**
+It will appear with accept/reject buttons on the kanban board. Do NOT call `jettypod work status <feature-id> done` — that bypasses the review gate.
 
 **Display:**
 
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-✅ FEATURE COMPLETE!
+FEATURE COMPLETE!
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 Feature: #[id] [Feature Title]
-Status: ✅ DONE
+Status: DONE
 
 What we accomplished:
-✅ All BDD scenarios passing (success + error handling + edge cases)
-✅ Comprehensive error handling and validation
-✅ Input validation and edge case coverage
-✅ State consistency and data integrity
+All BDD scenarios passing (success + error handling + edge cases)
+Comprehensive error handling and validation
+Input validation and edge case coverage
+State consistency and data integrity
 
-📝 INTERNAL PROJECT - STABLE MODE IS COMPLETE
+INTERNAL PROJECT - STABLE MODE IS COMPLETE
 
 This is an internal project - stable mode is the end state.
 Feature is complete and ready to use!
@@ -770,7 +781,7 @@ Note: If you later transition to external (accepting real users),
 run the external-transition skill to generate production chores.
 ```
 
-**🔄 WORKFLOW INTEGRATION: Complete workflow (internal project)**
+**WORKFLOW INTEGRATION: Complete workflow (internal project)**
 
 ```bash
 jettypod workflow complete stable-mode <feature-id>
@@ -792,7 +803,7 @@ This marks the `stable_mode_complete` gate as passed. For internal projects, thi
 
 **If project_state = 'external':**
 
-**🛑 CRITICAL HANDOFF - You MUST invoke production-mode using the Skill tool.**
+**CRITICAL HANDOFF - You MUST invoke production-mode using the Skill tool.**
 
 **Set feature mode to production:**
 
@@ -804,21 +815,21 @@ jettypod work set-mode <feature-id> production
 
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-🎯 Stable Mode Complete! Transitioning to Production Mode
+Stable Mode Complete! Transitioning to Production Mode
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-⚠️  CRITICAL: This is an EXTERNAL project.
+ CRITICAL: This is an EXTERNAL project.
 Stable mode makes it robust - production mode makes it ready for real users.
 
 What we accomplished:
-✅ All BDD scenarios passing (success + error handling + edge cases)
-✅ Comprehensive error handling and validation
-✅ Feature stable and ready for production hardening
+All BDD scenarios passing (success + error handling + edge cases)
+Comprehensive error handling and validation
+Feature stable and ready for production hardening
 
-🚀 Now invoking production-mode skill...
+Now invoking production-mode skill...
 ```
 
-**🔄 WORKFLOW INTEGRATION: Complete workflow (external project)**
+**WORKFLOW INTEGRATION: Complete workflow (external project)**
 
 ```bash
 jettypod workflow complete stable-mode <feature-id>
@@ -854,7 +865,7 @@ Before ending stable-mode skill, ensure:
 - [ ] Integration scenario still passes (feature remains reachable after error handling added)
 - [ ] Final chore merged to main
 - [ ] Project state checked (internal vs external)
-- [ ] **INTERNAL:** Feature marked as done
+- [ ] **INTERNAL:** Feature merged (review gate set automatically by merge command)
 - [ ] **EXTERNAL:** Feature mode set to production AND production-mode skill invoked
 
 ---
@@ -878,17 +889,17 @@ jettypod work start <chore-id>   # Create worktree and start chore
 
 **Set feature status/mode:**
 ```bash
-jettypod work status <feature-id> done      # Mark feature complete (internal only)
-jettypod work set-mode <feature-id> production  # Set feature to production mode
+# Do NOT call `work status done` — merge sets the review gate automatically
+jettypod work set-mode <feature-id> production  # Set feature to production mode (external only)
 ```
 
-**❌ DO NOT use these to complete chores:**
+**DO NOT use these to complete chores:**
 - `jettypod work status <chore-id> done`
 - `jettypod work complete <id>`
 
 ---
 
-## ⚠️ Important: Sequential Workflow
+## Important: Sequential Workflow
 
 **Stable mode chores MUST be completed sequentially, not in parallel.**
 

package/templates/bdd-guidance.md

@@ -0,0 +1,139 @@
+# BDD Reference for Skills
+
+Read this before writing scenarios or step definitions. Every rule here is enforced — not advisory.
+
+## Scenario Formulation
+
+**Feature files describe "what" and "why." Step definitions implement "how."**
+
+Each scenario: one behavior, one reason to fail.
+
+### Rules
+
+- **Declarative** — describe intent, not UI clicks. "When the user retries payment" not "When I click the third button."
+- **Stable** — no brittle details (pixel positions, timing, CSS selectors).
+- **Deterministic** — use factories with known data. Never depend on ambient/existing data.
+- **No implementation leakage** — no "Given the database has..." in feature files. Use intentful language: "Given a user with an unpaid invoice."
+
+### Good
+
+```gherkin
+Scenario: User can retry a failed payment
+  Given a user with an unpaid invoice
+  And the payment processor returns "insufficient_funds"
+  When the user retries payment with a different card
+  Then the invoice is marked as paid
+  And the user sees a receipt
+```
+
+### Bad
+
+```gherkin
+Scenario: Pay invoice
+  Given I click the "Billing" tab
+  And I wait 2 seconds
+  And I click the third button on the page
+  When I type "4111111111111111" into the card field
+  Then I should see "Success"
+```
+
+## Step Definition Banlist
+
+These are BANNED in step definitions. Not "avoid" — banned.
+
+| Banned | Use instead |
+|--------|-------------|
+| `setTimeout`, `sleep`, fixed waits | `waitFor(() => condition, { timeout })` polling utility |
+| Module-level `let`/`var` state | Cucumber World (`this`) for per-scenario state |
+| Raw SQL (`db.run`, `db.get`) | Helper methods in `features/support/helpers/` |
+| Loops and branching logic | One intentful helper call per step |
+| Assertions in Given/When steps | Assertions belong in Then steps only |
+| Inline selectors/click chains | Page objects or screen models |
+| Setting mock state then asserting it | Tests must exercise real production code |
+
+### Thin Step Pattern
+
+Steps do three things: parse parameters, call one helper, assert outcome.
+
+```js
+// GOOD — thin step, calls helper
+When('the user retries payment with a different card', async function () {
+  await this.billing.retryPaymentWith(this.validCard);
+});
+
+// BAD — inline implementation
+When('the user retries payment with a different card', async function () {
+  await page.click('#billing-tab');
+  await page.waitForSelector('.invoice-list');
+  await page.click('.invoice:first-child .retry-btn');
+  await page.fill('#card-number', '4242424242424242');
+  await page.click('#submit');
+  await new Promise(r => setTimeout(r, 2000));
+});
+```
+
+## Helper Layer Architecture
+
+Step definitions must not contain domain logic, SQL, or UI interaction directly. Use this layering:
+
+```
+Feature files (behavior — Gherkin)
+  └─ Step definitions (glue — thin, 1-5 lines)
+       └─ Helpers (features/support/helpers/)
+            ├─ Domain helpers (intentful operations)
+            ├─ API client
+            ├─ DB helpers (encapsulated queries)
+            └─ Wait utilities (polling, not sleeping)
+```
+
+**Dependency rules:**
+- Step defs call helpers. Never call drivers directly.
+- Helpers call drivers (DB, API, UI).
+- Feature files know nothing about implementation.
+
+**Before writing step definitions:** Read `features/support/helpers/` for existing helpers. Reuse before creating new ones.
+
+## Async & External Dependencies
+
+**Async:** Poll with timeout, never sleep.
+```js
+await waitFor(() => order.status === 'COMPLETED', { timeout: 10_000 });
+```
+
+**External services:** Stub at the boundary for most tests. Use fakes (in-memory implementations) over mocks. Mocks test call patterns ("did we call X?"); fakes test outcomes ("did the user get the result?").
+
+**Auth flows:** Use test shortcuts (token minting, session injection). Don't make every scenario pay the login tax.
+
+## Test Doubles
+
+Prefer stubs/fakes for BDD. They support behavior assertions without coupling to implementation.
+
+Use mocks only when verifying a side effect IS the scenario's purpose (e.g., "audit event was emitted").
+
+**BDD asserts outcomes, not internal choreography.**
+
+## Data Setup
+
+Use intentful factories:
+```js
+// GOOD
+await this.fixtures.createUserWithUnpaidInvoice();
+
+// BAD — implementation leakage
+await db.run('INSERT INTO users...');
+await db.run('INSERT INTO invoices...');
+```
+
+Freeze time and seed randomness. Assert on meaning ("receipt exists") not raw IDs.
+
+## Quality Checklist
+
+After writing tests, verify:
+
+- [ ] Steps are 1-5 lines, each calling one helper
+- [ ] No `setTimeout` or `sleep` anywhere in step definitions
+- [ ] State stored on `this` (Cucumber World), not module-level variables
+- [ ] No raw SQL in step definitions
+- [ ] Assertions only in Then steps
+- [ ] Tests exercise real production code (not asserting mock state you just set)
+- [ ] Existing helpers reused, not duplicated

package/templates/bdd-scaffolding/wait.js

@@ -0,0 +1,18 @@
+/**
+ * Poll a condition function until it returns true, with timeout.
+ * Use this instead of setTimeout/sleep in step definitions.
+ *
+ * Usage:
+ *   const { waitFor } = require('../helpers/wait');
+ *   await waitFor(() => order.status === 'COMPLETED', { timeout: 10000 });
+ */
+async function waitFor(conditionFn, { timeout = 5000, interval = 100 } = {}) {
+  const start = Date.now();
+  while (Date.now() - start < timeout) {
+    if (await conditionFn()) return;
+    await new Promise(r => setTimeout(r, interval));
+  }
+  throw new Error(`waitFor timed out after ${timeout}ms`);
+}
+
+module.exports = { waitFor };