jettypod 4.4.115 → 4.4.118

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

@@ -741,9 +741,8 @@ 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:**
 
@@ -854,7 +853,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,8 +877,8 @@ 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:**

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 };

package/templates/bdd-scaffolding/world.js

@@ -0,0 +1,19 @@
+/**
+ * Cucumber World configuration.
+ * Provides per-scenario state via `this` in step definitions.
+ * Use this instead of module-level let/var for test state.
+ *
+ * Place at: features/support/world.js
+ */
+const { setWorldConstructor } = require('@cucumber/cucumber');
+
+class TestWorld {
+  constructor() {
+    // Per-scenario state — automatically reset between scenarios.
+    // Add properties here or in step definitions via this.propName = value
+  }
+}
+
+setWorldConstructor(TestWorld);
+
+module.exports = { TestWorld };

package/apps/dashboard/app/access-code/page.tsx

@@ -1,110 +0,0 @@
-'use client';
-
-import { useState } from 'react';
-import Image from 'next/image';
-
-export default function AccessCodePage() {
-  const [code, setCode] = useState('');
-  const [error, setError] = useState<string | null>(null);
-  const [isSubmitting, setIsSubmitting] = useState(false);
-
-  const handleSubmit = async (e: React.FormEvent) => {
-    e.preventDefault();
-    setError(null);
-
-    if (!code.trim()) {
-      setError('Please enter an access code.');
-      return;
-    }
-
-    if (!window.electronAPI?.isElectron) {
-      setError('Access code validation is only available in the desktop app.');
-      return;
-    }
-
-    setIsSubmitting(true);
-
-    try {
-      const result = await window.electronAPI.access.validate(code.trim());
-
-      if (!result.success) {
-        setError(result.error || 'Invalid access code.');
-        setIsSubmitting(false);
-        return;
-      }
-
-      // Access granted - navigate to main app
-      window.location.href = '/';
-    } catch (err) {
-      setError(err instanceof Error ? err.message : 'Failed to validate access code.');
-      setIsSubmitting(false);
-    }
-  };
-
-  return (
-    <div className="flex flex-col items-center justify-center min-h-screen bg-white dark:bg-zinc-900 p-8">
-      <div className="max-w-md w-full space-y-8">
-        {/* Logo */}
-        <div className="flex flex-col items-center space-y-4">
-          <Image
-            src="/jettypod_wordmark.png"
-            alt="JettyPod"
-            width={160}
-            height={40}
-            priority
-          />
-          <h1 className="text-2xl font-semibold text-zinc-900 dark:text-zinc-100 text-center">
-            Enter Access Code
-          </h1>
-          <p className="text-zinc-500 dark:text-zinc-400 text-center">
-            Enter your access code to get started with JettyPod.
-          </p>
-        </div>
-
-        {/* Error */}
-        {error && (
-          <div className="bg-red-50 dark:bg-red-900/20 border border-red-200 dark:border-red-800 text-red-700 dark:text-red-400 px-4 py-3 rounded-lg text-sm">
-            {error}
-          </div>
-        )}
-
-        {/* Form */}
-        <form onSubmit={handleSubmit} className="pt-4 space-y-4">
-          <input
-            type="text"
-            value={code}
-            onChange={(e) => setCode(e.target.value)}
-            placeholder="Access code"
-            autoFocus
-            disabled={isSubmitting}
-            className="w-full px-4 py-3 rounded-xl border border-zinc-300 dark:border-zinc-600 bg-white dark:bg-zinc-800 text-zinc-900 dark:text-zinc-100 placeholder-zinc-400 dark:placeholder-zinc-500 focus:outline-none focus:ring-2 focus:ring-zinc-400 dark:focus:ring-zinc-500 disabled:opacity-50"
-            data-testid="access-code-input"
-          />
-          <button
-            type="submit"
-            disabled={isSubmitting}
-            className="w-full py-3 px-6 rounded-xl font-medium transition-all duration-200 hover:-translate-y-1 hover:scale-[1.01] active:translate-y-0 active:scale-100 disabled:opacity-50 disabled:pointer-events-none"
-            style={{
-              cursor: isSubmitting ? 'default' : 'pointer',
-              background: 'linear-gradient(145deg, #ffffff 0%, #faf9f7 10%, #f0f4f4 35%, #c8d9da 55%, #819D9F 90%)',
-              color: '#3d4d4e',
-              boxShadow: `
-                0 1px 1px rgba(0, 0, 0, 0.02),
-                0 2px 4px rgba(0, 0, 0, 0.03),
-                0 6px 12px rgba(0, 0, 0, 0.05),
-                0 12px 24px rgba(0, 0, 0, 0.06),
-                0 20px 40px rgba(129, 157, 159, 0.2),
-                0 32px 64px rgba(129, 157, 159, 0.18),
-                inset 0 2px 4px rgba(255, 255, 255, 1),
-                inset 0 -2px 4px rgba(129, 157, 159, 0.05)
-              `,
-            }}
-            data-testid="access-code-submit"
-          >
-            {isSubmitting ? 'Validating...' : 'Continue'}
-          </button>
-        </form>
-      </div>
-    </div>
-  );
-}

package/lib/discovery-checkpoint.js

@@ -1,123 +0,0 @@
-const config = require('./config');
-
-/**
- * Update discovery checkpoint with current progress
- * @param {number} step - Current discovery step (1-7)
- * @param {Object} data - Checkpoint data (user_journey, ux_approach, epics_created)
- */
-function updateCheckpoint(step, data = {}) {
-  const currentConfig = config.read();
-
-  // Ensure project_discovery exists
-  if (!currentConfig.project_discovery) {
-    currentConfig.project_discovery = config.getDefaultProjectDiscovery();
-  }
-
-  // Update checkpoint
-  currentConfig.project_discovery.checkpoint = {
-    step,
-    user_journey: data.user_journey || currentConfig.project_discovery.checkpoint?.user_journey || null,
-    ux_approach: data.ux_approach || currentConfig.project_discovery.checkpoint?.ux_approach || null,
-    epics_created: data.epics_created !== undefined ? data.epics_created : (currentConfig.project_discovery.checkpoint?.epics_created || false)
-  };
-
-  // Update status to in_progress if not already completed
-  if (currentConfig.project_discovery.status === 'not_started') {
-    currentConfig.project_discovery.status = 'in_progress';
-    currentConfig.project_discovery.started_date = new Date().toISOString();
-  }
-
-  config.write(currentConfig);
-}
-
-/**
- * Get current discovery checkpoint
- * @returns {Object|null} Checkpoint data or null if not started
- */
-function getCheckpoint() {
-  const currentConfig = config.read();
-
-  if (!currentConfig.project_discovery || currentConfig.project_discovery.status === 'not_started') {
-    return null;
-  }
-
-  return currentConfig.project_discovery.checkpoint || null;
-}
-
-/**
- * Clear discovery checkpoint (when discovery is completed)
- */
-function clearCheckpoint() {
-  const currentConfig = config.read();
-
-  if (currentConfig.project_discovery) {
-    currentConfig.project_discovery.checkpoint = config.getDefaultProjectDiscovery().checkpoint;
-    config.write(currentConfig);
-  }
-}
-
-/**
- * Get human-readable description of current checkpoint step
- * @param {number} step - Step number
- * @returns {string} Step description
- */
-function getStepDescription(step) {
-  const steps = {
-    1: 'Starting discovery - define user journey',
-    2: 'User journey defined - present UX approaches',
-    3: 'UX approach selected - build prototypes',
-    4: 'Prototypes tested - break into epics',
-    5: 'Epics created - choose tech stack',
-    6: 'Tech stack chosen - record decision',
-    7: 'Discovery complete'
-  };
-
-  return steps[step] || 'Unknown step';
-}
-
-/**
- * Generate a formatted resume message for displaying when resuming discovery
- * @param {Object} checkpoint - Checkpoint object with step, user_journey, ux_approach, epics_created
- * @returns {string|null} Formatted resume message or null if no checkpoint
- */
-function generateResumeMessage(checkpoint) {
-  if (!checkpoint) {
-    return null;
-  }
-
-  const stepDesc = getStepDescription(checkpoint.step);
-
-  let lines = [
-    '━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━',
-    '🔄 RESUMING PROJECT DISCOVERY',
-    '━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━',
-    '',
-    `📍 Resuming from Step ${checkpoint.step}: ${stepDesc}`,
-    ''
-  ];
-
-  if (checkpoint.user_journey) {
-    lines.push(`📝 User Journey: "${checkpoint.user_journey}"`);
-  }
-  if (checkpoint.ux_approach) {
-    lines.push(`🎨 UX Approach: "${checkpoint.ux_approach}"`);
-  }
-  if (checkpoint.epics_created) {
-    lines.push(`✅ Epics: Already created`);
-  }
-
-  lines.push('');
-  lines.push('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
-  lines.push('');
-  lines.push('Continuing where you left off...');
-
-  return lines.join('\n');
-}
-
-module.exports = {
-  updateCheckpoint,
-  getCheckpoint,
-  clearCheckpoint,
-  getStepDescription,
-  generateResumeMessage
-};