claude-ketchup 0.7.0

package/reminders/reminder-emergent-design.md

@@ -0,0 +1,41 @@
+---
+when:
+  hook: SessionStart
+priority: 100
+---
+
+# Emergent Design Reminder
+
+Behavior first. Types/interfaces emerge from tests.
+
+## The Principle
+
+Don't design types upfront. Let them emerge from what the tests require.
+
+## Example
+
+```typescript
+// First: Write a test that calls a function and asserts output
+it("creates user with generated id", () => {
+  const result = createUser({ name: "Alice" });
+  expect(result).toEqual({ id: expect.any(String), name: "Alice" });
+});
+
+// Then: Types emerge because the function needs them
+// The test drove the need for: input type, output type, id generation
+```
+
+## Anti-Pattern
+
+```typescript
+// Don't do this: types/user.ts
+interface User {
+  id: string;
+  name: string;
+  email: string;
+  createdAt: Date;
+  // ... 20 more fields "just in case"
+}
+```
+
+Types should be minimal and driven by actual test requirements, not speculative design.

package/reminders/reminder-extreme-ownership.md

@@ -0,0 +1,27 @@
+---
+when:
+  hook: SessionStart
+priority: 100
+---
+
+# Extreme Ownership Reminder
+
+Every problem is your problem. No deflection. No explaining why something is broken.
+
+## The Rule
+
+See a problem → fix it or add a burst to fix it. No third option.
+
+If you read a file, you're responsible for its state when you're done.
+
+## Wrong vs Right Responses
+
+| Situation                | Wrong Response                          | Ownership Response            |
+| ------------------------ | --------------------------------------- | ----------------------------- |
+| Bug in existing code     | "The existing code has a bug where..."  | Fix it or add burst to fix it |
+| Test suite has gaps      | "Coverage was incomplete before..."     | Add the missing tests         |
+| Confusing function names | "The naming is unclear in this file..." | Rename in refactor step       |
+| Missing error handling   | "Error handling wasn't implemented..."  | Add it now                    |
+| Flaky test               | "This test appears to be unreliable..." | Stabilize it or add burst     |
+
+No excuses. No "you're right." Keep working.

package/reminders/reminder-ide-diagnostics.md

@@ -0,0 +1,25 @@
+---
+when:
+  hook: SessionStart
+priority: 100
+---
+
+# IDE Diagnostics Reminder
+
+Before committing, check IDE diagnostics on all uncommitted files.
+
+## Pre-Commit Checklist
+
+1. Review all files with uncommitted changes
+2. Check for TypeScript errors (red squiggles)
+3. Check for warnings (yellow squiggles)
+4. Ensure no linting errors remain
+5. Verify imports are correctly resolved
+
+## TCR Command
+
+```bash
+pnpm test --run && git add -A && git commit -m "<MSG>" || git checkout -- .
+```
+
+The tests will catch most issues, but IDE diagnostics can catch type errors and import issues before you even run tests.

package/reminders/reminder-ketchup.md

@@ -0,0 +1,145 @@
+---
+when:
+  hook: SessionStart
+priority: 100
+---
+
+# Ketchup Core Reminder
+
+> Controlled Bursts | TDD | TCR | 100% Coverage
+
+## Core Loop
+
+```
+Red → Green → TCR → Refactor → TCR → Done
+TCR: test && commit || revert
+- Pass → commit → continue
+- Fail → REVERT → RETHINK (smaller steps or new design)
+```
+
+Never patch failing code. Revert, learn, try differently.
+
+## Bursts
+
+One test, one behavior, one commit. No exceptions.
+
+Each burst: independent, valuable, small, testable, reviewable.
+
+The constraint is scope, not time. Keep bursts small enough that:
+
+- You stay focused on one thing
+- The operator can verify quickly
+- A revert loses minimal work
+
+E2E exception: E2E tests may combine 2 tightly-coupled bursts when splitting creates artificial boundaries.
+
+## Workflow
+
+1. Create `ketchup-plan.md` with TODO/DONE sections, commit before coding
+2. Write ONE failing test
+3. Write MINIMAL passing code
+4. TCR (update plan in same commit)
+5. Refactor if needed → TCR
+6. Move burst to DONE → TCR
+7. Next burst
+
+```markdown
+# Ketchup Plan: [Feature]
+
+## TODO
+
+- [ ] Burst 1: [description]
+
+## DONE
+
+- [x] Burst N: [description] (hash)
+```
+
+## Refactoring
+
+Refactor for readability, not for explanation. If code is complex, rename variables or extract functions. Do not add comments.
+
+## Coverage
+
+100% enforced. No escape hatches.
+
+Exclusions allowed ONLY for: barrel `index.ts` re-exports, `*.test.ts` files
+
+Forbidden:
+
+- Excluding files to avoid testing them
+- Standalone type files (`types.ts`, `interfaces.ts`) — types live inline where used
+- `@ts-ignore`, `any`, `as SomeType` casts
+
+| Do                              | Don't                                    |
+| ------------------------------- | ---------------------------------------- |
+| Let tests drive all code        | Write code without a failing test first  |
+| Add branches only when tested   | Defensive `??`, `?:`, `if/else` untested |
+| Test all error paths            | Leave error handling unverified          |
+| Remove dead code after each run | Keep unused code "just in case"          |
+
+## Testing Rules
+
+**Assertion Strength:** Never use weak assertions (`toBeDefined`, `toBeTruthy`, `not.toBeNull`). Assert the exact shape and value. If you don't know the exact value, use `expect.any(String)` or `expect.any(Number)`.
+
+**Stubs over mocks:** Deterministic stubs preferred. Mock only at boundaries.
+
+**Assert whole objects:** `expect(result).toEqual({...})` not cherry-picked properties.
+
+**Squint test:** All tests must follow: SETUP (data) → EXECUTE (function call) → VERIFY (whole object assertion). No multiple execute/verify cycles in one test.
+
+**No state peeking:** Test observable behavior, not internal state.
+
+Litmus Test: "If I changed the internal data structure (e.g., Map to Array), would this test still pass?" If no, the test is coupled to implementation.
+
+| Forbidden (Implementation)                              | Allowed (Behavior)                                                        |
+| ------------------------------------------------------- | ------------------------------------------------------------------------- |
+| `expect(tracker.getActiveCount()).toBe(0)`              | Test via callbacks/events                                                 |
+| `expect(manager.clientCount).toBe(3)`                   | `tracker.onEvent(e => events.push(e))`                                    |
+| `expect(service["internalMap"].size).toBe(2)`           | Test via return values                                                    |
+| `tracker.cleanup(); expect(tracker.getCount()).toBe(0)` | Test cleanup by re-triggering: start same id, verify callback fires again |
+
+**Do NOT expose methods solely for testing.** If you're adding `.getCount()` or `.getActiveSessionCount()` just to make tests pass, you're testing implementation, not behavior.
+
+## Guardrails
+
+- No comments — write self-expressing code
+- No excuses, no "you're right" — keep working
+- JS files only in `dist/`
+- When tests fail, assume you broke it. CI passed before; your change is the variable.
+
+**Backwards compatibility:** Ask first. Default to clean breaks. No silent preservation unless explicitly requested.
+
+Backwards-compatibility hacks to avoid:
+
+- Re-exporting moved/renamed symbols
+- Keeping unused parameters with `_` prefix
+- Adding `// @deprecated` comments for removed code
+- Wrapper functions that delegate to new implementations
+
+## Infrastructure Commits
+
+Config files need no tests: `package.json`, `tsconfig.json`, `wrangler.toml`, `vite.config.ts`, `vitest.config.ts`, `.gitignore`, `ketchup-plan.md`
+
+Format: `chore(scope): description`
+
+First behavioral `.ts` file requires a test.
+
+## Plea System
+
+If the commit validator rejects your commit but you believe it's valid, add `plea: <reason>` to your commit message.
+
+**Valid pleas:**
+
+- Files must be committed together for coherence
+- Existing code lacked coverage before your changes
+
+**Invalid pleas (will be rejected):**
+
+- Skipping tests for new code
+- Untested code paths
+- Any other CLAUDE.md rule bypass
+
+## Misc
+
+- No "Generated with Claude Code" in commits

package/reminders/reminder-parallelization.md

@@ -0,0 +1,27 @@
+---
+when:
+  hook: SessionStart
+priority: 100
+---
+
+# Parallelization Reminder
+
+Maximize parallel execution. Launch multiple sub-agents when:
+
+- Bursts have no dependencies on each other (`[depends: none]`)
+- Exploration can be split by area (e.g., "search tests" + "search implementation")
+- Multiple files need similar changes
+
+## Dependency Notation
+
+```markdown
+### Bottle: Authentication
+- [ ] Burst 10: createUser returns user object [depends: none]
+- [ ] Burst 11: hashPassword uses bcrypt [depends: none]
+- [ ] Burst 12: validatePassword checks hash [depends: 11]
+```
+
+**Rules:**
+- `[depends: none]` - can start immediately, parallelizable with other `none` bursts
+- `[depends: N]` - must wait for burst N to complete
+- Bursts at the same dependency level can run in parallel

package/reminders/reminder-rethink-after-revert.md

@@ -0,0 +1,25 @@
+---
+when:
+  hook: SessionStart
+priority: 100
+---
+
+# RETHINK After Revert Reminder
+
+After a revert, do NOT immediately retry the same approach.
+
+## Ask These Questions First
+
+1. **Was the burst too big?** → Split it into smaller bursts
+2. **Was the design flawed?** → Try a different approach entirely
+3. **Was the test wrong?** → Clarify the requirement before writing code
+
+## Then
+
+Only after answering these questions, write the next failing test.
+
+Never patch failing code. The TCR pattern means:
+- Pass → commit → continue
+- Fail → REVERT → RETHINK (smaller steps or new design)
+
+A revert is a signal to change your approach, not to try harder at the same thing.

package/reminders/reminder-sub-agent-rules.md

@@ -0,0 +1,27 @@
+---
+when:
+  hook: SessionStart
+priority: 100
+---
+
+# Sub-Agent Rules Reminder
+
+When spawning a Task agent (sub-agent), ensure:
+
+1. **Include CLAUDE.md context** - Sub-agents must receive and follow these rules
+2. **Include ketchup-plan.md** - Sub-agents work from the same plan
+3. **No orphan work** - Sub-agent output must be committed by parent or sub-agent
+
+Sub-agents follow identical rules to the parent. They are not exempt from any CLAUDE.md requirements.
+
+## Prompt Pattern
+
+```
+You are working on [bottle name]. Follow CLAUDE.md rules exactly.
+
+Your burst: [burst description]
+Dependencies: [list completed bursts this depends on, or "none"]
+Parallel with: [list of bursts running concurrently]
+
+[specific instructions]
+```

package/reminders/reminder-test-title-matches-spec.md

@@ -0,0 +1,37 @@
+---
+when:
+  hook: SessionStart
+priority: 100
+---
+
+# Test Title = Spec Reminder
+
+The test body must prove exactly what `it('should...')` claims.
+
+## The Principle
+
+**Title = Spec:** One assertion per behavior. The test title is the specification; the test body is the proof.
+
+## Example
+
+```typescript
+// Good: Title matches what's being tested
+it("creates user with generated id", () => {
+  const result = createUser({ name: "Alice" });
+  expect(result).toEqual({ id: expect.any(String), name: "Alice" });
+});
+
+// Bad: Title doesn't match assertion
+it("creates user with generated id", () => {
+  const result = createUser({ name: "Alice" });
+  expect(result.name).toBe("Alice"); // Not testing the ID!
+});
+```
+
+## Ask Yourself
+
+"Does this test body prove exactly what the `it()` description claims?"
+
+If not, either:
+1. Fix the test body to prove the claim
+2. Fix the title to match what you're actually testing

package/scripts/auto-continue.ts

@@ -0,0 +1,34 @@
+#!/usr/bin/env npx tsx
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import { writeHookLog } from '../src/hook-logger.js';
+import { handleStop, type StopHookInput } from '../src/hooks/auto-continue.js';
+
+const projectDir = process.cwd();
+const claudeDir = path.resolve(projectDir, '.claude');
+const stdin = fs.readFileSync(0, 'utf8').trim();
+
+if (!stdin) {
+  process.exit(0);
+}
+
+const input: StopHookInput = JSON.parse(stdin);
+const startTime = Date.now();
+const result = handleStop(projectDir, input);
+
+const output = result.decision === 'block' ? { stopReason: result.reason, forceResult: { behaviour: 'block' } } : null;
+
+writeHookLog(claudeDir, {
+  hookName: 'auto-continue',
+  timestamp: new Date().toISOString(),
+  input,
+  output: output ?? { decision: result.decision, reason: result.reason },
+  durationMs: Date.now() - startTime,
+});
+
+if (output) {
+  console.log(JSON.stringify(output));
+}
+
+process.exit(0);