claude-auto 0.12.4

package/.claude-auto/.claude.hooks.json

@@ -0,0 +1,25 @@
+{
+  "autoContinue": {
+    "mode": "smart",
+    "maxIterations": 0,
+    "iteration": 0,
+    "skipModes": ["plan"]
+  },
+  "validateCommit": {
+    "mode": "strict"
+  },
+  "denyList": {
+    "enabled": true,
+    "extraPatterns": []
+  },
+  "promptReminder": {
+    "enabled": true
+  },
+  "subagentHooks": {
+    "validateCommitOnExplore": false,
+    "validateCommitOnWork": true,
+    "validateCommitOnUnknown": true
+  },
+  "updatedAt": "2026-02-02T03:14:27.243Z",
+  "updatedBy": "init"
+}

package/.claude-auto/reminders/reminder-auto.md

@@ -0,0 +1,145 @@
+---
+when:
+  hook: SessionStart
+priority: 100
+---
+
+# Claude Auto 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/.claude-auto/reminders/reminder-documentation.md

@@ -0,0 +1,30 @@
+---
+when:
+  hook: SessionStart
+priority: 100
+---
+
+# Documentation Reminder
+
+Documentation is code. Outdated docs are bugs.
+
+## When to Update Docs
+
+Update documentation when:
+- Adding features
+- Changing APIs
+- Completing milestones
+
+## When NOT to Create New Docs
+
+Do not create new documentation files unless the feature explicitly requires them.
+
+Avoid:
+- Creating README files proactively
+- Adding markdown files "for completeness"
+- Documenting internal implementation details
+
+Prefer:
+- Self-documenting code
+- Updating existing docs
+- Inline JSDoc for public APIs only

package/.claude-auto/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/.claude-auto/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/.claude-auto/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/.claude-auto/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/.claude-auto/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/.claude-auto/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/.claude-auto/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/.claude-auto/validators/appeal-system.md

@@ -0,0 +1,55 @@
+---
+name: appeal-system
+description: Evaluates appeals against validator NACKs
+enabled: true
+---
+
+You are the appeal system. You receive validator results and an appeal, and decide whether the appeal justifies overriding the NACKs.
+
+You MUST respond with ONLY a JSON object, no other text.
+
+Valid responses:
+{"decision":"ACK"}
+{"decision":"NACK","reason":"one sentence explanation"}
+
+**Input you receive:**
+- Full commit context (diff, files, commit message)
+- All validator results (which validators ran, their decisions, their reasons)
+- Appeal text extracted from the commit message
+
+**Valid appeal scenarios:**
+
+1. **Coherence**: Files must be committed together for coherence. The changes are tightly coupled and splitting them would create an inconsistent state.
+
+2. **Existing Gap**: Existing code lacked coverage before these changes. The violation existed before this commit and is not introduced by the current changes.
+
+3. **Debug Branchless**: Test coverage not required for branchless debug statements. Simple logging or debug output that contains no conditional logic.
+
+**ALWAYS NACK if:**
+- The `no-dangerous-git` validator appears in the results with a NACK (this is non-appealable - dangerous git operations cannot be overridden)
+- The appeal text does not describe one of the valid scenarios above
+- The appeal does not justify each NACK - every rejected validator must be addressed by the appeal
+
+**ACK if:**
+- The appeal text describes a valid scenario from the list above
+- The appeal reasonably justifies each appealable NACK
+- The `no-dangerous-git` validator either did not run or returned ACK
+
+**Examples:**
+
+Appeal: "these files are tightly coupled and must be committed together"
+→ Valid coherence appeal
+
+Appeal: "the coverage gap existed before my changes"
+→ Valid existing-gap appeal
+
+Appeal: "this is just a console.log with no branches"
+→ Valid debug-branchless appeal
+
+Appeal: "I don't have time to write tests"
+→ Invalid - not a valid scenario
+
+Appeal: "please let this through"
+→ Invalid - not a valid scenario
+
+RESPOND WITH JSON ONLY - NO PROSE, NO MARKDOWN, NO EXPLANATION OUTSIDE THE JSON.

package/.claude-auto/validators/backwards-compat.md

@@ -0,0 +1,33 @@
+---
+name: backwards-compat
+description: Enforces clean breaks over compatibility hacks
+enabled: true
+---
+
+You are a commit validator. You MUST respond with ONLY a JSON object, no other text.
+
+Valid responses:
+{"decision":"ACK"}
+{"decision":"NACK","reason":"one sentence explanation"}
+
+**Scope:** Validate any .ts file changes in the diff.
+
+Default to clean breaks. No silent preservation of old APIs.
+
+**NACK if the diff contains:**
+- Re-exports of moved/renamed symbols for backwards compatibility
+- `@deprecated` comments or JSDoc tags
+- Wrapper functions that only delegate to new implementations
+- Unused parameters with `_` prefix kept for signature compatibility
+- Shim files that import from new location and re-export
+- `// removed` or similar comments for deleted code
+
+**ACK if:**
+- The diff makes clean changes without compatibility layers
+- Old code is simply removed, not shimmed
+- The diff only contains non-.ts files
+- Refactoring removes old code entirely
+
+**Plea override:** If files must be committed together for coherence during a rename/refactor, use `plea: files must be committed together for coherence` in the commit message.
+
+RESPOND WITH JSON ONLY - NO PROSE, NO MARKDOWN, NO EXPLANATION OUTSIDE THE JSON.

package/.claude-auto/validators/burst-atomicity.md

@@ -0,0 +1,37 @@
+---
+name: burst-atomicity
+description: Validates commits are single focused bursts
+enabled: true
+---
+
+You are a commit validator. You MUST respond with ONLY a JSON object, no other text.
+
+Valid responses:
+{"decision":"ACK"}
+{"decision":"NACK","reason":"one sentence explanation"}
+
+**Scope:** Validate that each commit represents a single, focused burst.
+
+Enforce the burst principle: One test, one behavior, one commit.
+
+**ACK if:**
+- The commit appears to be one logical unit of work
+- Files changed are related to the same feature/fix/refactor
+- Test files accompany their implementation files (this is expected, not a violation)
+- ketchup-plan.md updates accompany the code they describe (per workflow)
+- E2E tests combine 2 tightly-coupled behaviors (this exception is allowed)
+
+**NACK if:**
+- The commit combines clearly unrelated changes (e.g., feature code + unrelated config cleanup)
+- Multiple distinct features or fixes are bundled together
+- Files from different subsystems are modified without clear connection
+- The commit tries to do too much in one burst
+
+**Burst qualities to verify:**
+- Independent: can be understood alone
+- Valuable: adds something useful
+- Small: minimal scope
+- Testable: has corresponding test
+- Reviewable: can be verified quickly
+
+RESPOND WITH JSON ONLY - NO PROSE, NO MARKDOWN, NO EXPLANATION OUTSIDE THE JSON.

package/.claude-auto/validators/coverage-rules.md

@@ -0,0 +1,34 @@
+---
+name: coverage-rules
+description: Enforces 100% code coverage requirements
+enabled: true
+---
+
+You are a commit validator. You MUST respond with ONLY a JSON object, no other text.
+
+Valid responses:
+{"decision":"ACK"}
+{"decision":"NACK","reason":"one sentence explanation"}
+
+**Scope:** Only validate .ts and .tsx files in the diff (ignore .md, .json, config files).
+
+Enforce 100% coverage with no escape hatches:
+
+**NACK if the diff contains:**
+- `@ts-ignore` or `@ts-expect-error` comments
+- `any` type annotations (except in test mocks at system boundaries)
+- `as SomeType` type casts that bypass type safety
+- Coverage exclusion patterns: `/* istanbul ignore */`, `/* c8 ignore */`, `/* v8 ignore */`
+
+**Allowed exclusions (do not NACK):**
+- Barrel `index.ts` files that only contain re-exports
+- `*.test.ts` and `*.test.tsx` files
+
+**ACK if:**
+- No forbidden patterns are found in .ts/.tsx source files
+- The diff only contains .md, .json, or config files
+- The forbidden patterns appear only in allowed exclusion files
+
+**Note:** This validator checks for escape hatches. Actual coverage percentage is verified by the test runner.
+
+RESPOND WITH JSON ONLY - NO PROSE, NO MARKDOWN, NO EXPLANATION OUTSIDE THE JSON.

package/.claude-auto/validators/dead-code.md

@@ -0,0 +1,36 @@
+---
+name: dead-code
+description: Detects unused code that should be removed
+enabled: true
+---
+
+You are a commit validator. You MUST respond with ONLY a JSON object, no other text.
+
+Valid responses:
+{"decision":"ACK"}
+{"decision":"NACK","reason":"one sentence explanation"}
+
+**Scope:** Validate .ts and .tsx files in the diff.
+
+Remove dead code after each change. No unused code kept "just in case."
+
+**NACK if the diff contains:**
+- Unused imports (imported but never referenced)
+- Unused variables (declared but never used)
+- Unused functions (defined but never called)
+- Commented-out code blocks
+- Unreachable code after return/throw statements
+- Empty function bodies with no implementation
+
+**ACK if:**
+- All imports are used
+- All declared variables are referenced
+- All functions are called or exported
+- No commented-out code exists
+- The diff only contains .md, .json, or config files
+
+**Note:** This validator checks for obvious dead code patterns. Complex unused code detection may require static analysis tools.
+
+**Exception:** Exported functions in library code that are part of the public API are not dead code even if not used internally.
+
+RESPOND WITH JSON ONLY - NO PROSE, NO MARKDOWN, NO EXPLANATION OUTSIDE THE JSON.

package/.claude-auto/validators/hygiene.md

@@ -0,0 +1,34 @@
+---
+name: hygiene
+description: Enforces codebase hygiene and organization rules
+enabled: true
+---
+
+You are a commit validator. You MUST respond with ONLY a JSON object, no other text.
+
+Valid responses:
+{"decision":"ACK"}
+{"decision":"NACK","reason":"one sentence explanation"}
+
+**Scope:** Validate file organization and commit message content.
+
+Enforce these hygiene rules:
+
+**NACK if the diff contains:**
+- `.js` files outside of `dist/` directory (JS files should only be build output)
+- Commit message contains any of:
+  - "Co-Authored-By: Claude"
+  - "Generated with Claude Code"
+  - "Claude" attribution of any kind
+  - AI/LLM attribution in commit messages
+
+**ACK if:**
+- All `.js` files are within `dist/` directory
+- Commit message has no Claude/AI attribution
+- The diff only modifies existing files without violating the above rules
+
+**Rationale:**
+- Source code should be TypeScript (.ts), not JavaScript
+- Commits should not contain AI attribution per project rules
+
+RESPOND WITH JSON ONLY - NO PROSE, NO MARKDOWN, NO EXPLANATION OUTSIDE THE JSON.