test as design guide principles

Author: devalbo

docs/CODING_GUIDELINES.md

@@ -43,7 +43,9 @@ This pattern is foundational, not mandatory—direct store access is fine for si
 - **Naming:** Use clear, consistent names. Prefer `handleSubmit` over `onClick` for handlers passed as props; keep event handlers and callbacks obvious.
 - **File length:** If a file grows past roughly 200–300 lines, consider splitting (e.g. by component, by feature, or into a small folder).
 - **Comments:** Comment *why* when it’s not obvious from the code; avoid restating what the code does.
-- **Tests:** New behavior should have unit tests where practical. Follow existing patterns in `tests/unit/` and use the test helpers (e.g. `renderWithProviders`, `createTestStore`).
+- **Tests:** Unit tests are **required** for all features—not optional. Follow existing patterns in `tests/unit/` and use the test helpers (e.g. `renderWithProviders`, `createTestStore`). If a test is hard to write, refactor the code rather than writing a complex test. See [TEST_PLAN.md](TEST_PLAN.md#testing-requirements).
+- **Tests guide design:** Use testability as feedback on your design. If you can't imagine a simple test for something, simplify the design before implementation gets complicated. Easy to test = easy to understand and maintain.
+- **Exception for performance-critical code:** Code optimized for performance may be harder to test due to its structure. This is acceptable **only if** the code is: (1) explicitly marked as performance-critical with a comment explaining why, (2) well bounded—small and focused on one thing, and (3) isolated—minimal dependencies, clear interface. Such code still needs tests, but they may test at the boundary rather than internals.
 
 ## Dependencies
 

docs/PRINCIPLES_AND_GOALS.md

@@ -242,6 +242,36 @@ We simulate Solid concepts locally; adding a sync target gives full Solid protoc
 
 ---
 
+## Technical Principles: Testability and Maintainability
+
+**If it's hard to test, it's hard to maintain.** These principles enable the project to live for a long time with minimal cost, and make it feasible for new participants to make changes without high levels of risk.
+
+### Testability Drives Design
+
+1. **Unit tests required for all features.** Every feature must have unit tests. No exceptions.
+2. **Refactor over complex tests.** If a test requires extensive setup, mocking, or is hard to write, that's a signal to refactor the code—not to write a more complex test.
+3. **Small, isolated units.** Code that's easy to test in isolation is easy to understand, change, and reuse.
+4. **Tests as documentation.** Tests show how code is meant to be used. If the test is hard to read, the API is probably hard to use.
+
+### Maintainability Enables Longevity
+
+1. **Low barrier to change.** New contributors should be able to make changes confidently. Good tests catch mistakes before they ship.
+2. **Refactoring is safe.** Comprehensive tests let you restructure code without fear. If you can't refactor safely, the project calcifies.
+3. **Cost stays low over time.** Projects without tests accumulate risk with every change. Projects with tests can grow indefinitely.
+
+### How This Connects to Project Goals
+
+| Goal | How Testability/Maintainability Supports It |
+|------|---------------------------------------------|
+| **Vibe coding friendly** | New contributors can experiment knowing tests will catch regressions |
+| **Agent-ready** | AI agents can modify code and verify correctness via tests |
+| **Minimal setup for app authors** | Well-tested library code means fewer bugs for consumers to work around |
+| **CLI as composable building blocks** | Commands tested in isolation work reliably when composed |
+
+See [TEST_PLAN.md](TEST_PLAN.md) for testing requirements and [SDLC_PROCESS.md](SDLC_PROCESS.md) for the verification workflow.
+
+---
+
 ## What We Commit To
 
 | Commitment | What It Means |
@@ -278,6 +308,7 @@ See [SHORTCOMINGS.md](SHORTCOMINGS.md) for the full list.
 | **Minimal setup** | One install, no backend, use what you need. |
 | **Vibe coding friendly** | Experiment, hack, use AI tools—vision over polish. |
 | **Unified CLI** | Same commands in browser, terminal, and AI agents. |
+| **Testability = maintainability** | If it's hard to test, refactor. Tests enable safe change. |
 
 TinyBase makes local-first reactive and practical. Solid provides the vision for user-owned, interoperable data. The unified CLI gives humans and AI agents the same command surface in browser and terminal. Together, they let users start immediately and grow into full data sovereignty—whether you're a seasoned developer, someone with an idea and an AI assistant, or an AI agent driving the library programmatically.
 

docs/SDLC_PROCESS.md

@@ -38,7 +38,18 @@ The process flows from **feature/requirements** → **design/selection** → **i
 
 The Feature Checklist serves two purposes: verifying new work and **defining behavior to preserve**. Before making changes, review affected checklist items—they represent working functionality that should not regress.
 
-For **code features**, “Documenting Changes” and “Verification Workflow” below apply. For **planning and documentation** (e.g. before or after a major phase), use the **Documentation review process** so design and docs stay coherent and gaps are tracked to closure.
+### Testability = Maintainability
+
+**If code is hard to test, it's hard to maintain.** This is a core technical principle (see [PRINCIPLES_AND_GOALS.md](PRINCIPLES_AND_GOALS.md#technical-principles-testability-and-maintainability)).
+
+- **Unit tests required for all features.** No exceptions. See [TEST_PLAN.md](TEST_PLAN.md#testing-requirements).
+- **Refactor over complex tests.** If a test needs extensive setup or mocking, refactor the code instead.
+- **Tests enable safe change.** New contributors can modify code confidently when tests catch regressions.
+- **Cost stays low.** Projects without tests accumulate risk. Projects with tests can grow indefinitely.
+
+This is what makes it feasible for new participants to make changes without high levels of risk, and what enables the project to live for a long time with minimal cost.
+
+For **code features**, "Documenting Changes" and "Verification Workflow" below apply. For **planning and documentation** (e.g. before or after a major phase), use the **Documentation review process** so design and docs stay coherent and gaps are tracked to closure.
 
 ---
 

docs/TEST_PLAN.md

@@ -1,5 +1,65 @@
 # Test Suite Implementation Plan
 
+## Testing Requirements
+
+**Unit tests are required for all features.** This is not optional. See [PRINCIPLES_AND_GOALS.md](PRINCIPLES_AND_GOALS.md#technical-principles-testability-and-maintainability) for why.
+
+### Core Rules
+
+1. **Every feature must have unit tests.** Before a feature is considered complete, it must have tests that verify its behavior.
+
+2. **Refactor over complex tests.** If writing a test requires:
+   - Extensive mocking or setup
+   - Deep knowledge of unrelated systems
+   - More than a few lines of boilerplate
+
+   ...then **refactor the code**, don't write a more complex test. Hard-to-test code is hard-to-maintain code.
+
+3. **Tests document behavior.** Tests show how code is meant to be used. If a test is hard to read, the API is probably hard to use.
+
+4. **Tests enable safe refactoring.** The test suite should give confidence that changes don't break existing behavior. If you can't refactor safely, add more tests first.
+
+### What to Test
+
+| Layer | What to test | Example |
+|-------|--------------|---------|
+| **Schemas** | Validation, factory functions, edge cases | `PersonaSchema.safeParse()`, `createPersona()` |
+| **Utilities** | Pure functions, transformations | `resolvePath()`, `findPersona()` |
+| **CLI commands** | Command execution, structured results | `executeCommandLine('ls')` returns expected result |
+| **Components** | Rendering, user interactions | ContactList renders items, handles selection |
+
+### Use Tests as a Design Guide
+
+**Unit tests are feedback on your design.** If code is hard to test, that's a signal the design is getting too complex or convoluted. Use this feedback:
+
+- Easy to test → probably easy to understand, change, and reuse
+- Hard to test → probably too coupled, doing too much, or poorly factored
+
+Write the test first (or at least think about how you'd test it) before the implementation gets complicated. If you can't imagine a simple test, simplify the design.
+
+### When Tests Are Hard to Write
+
+If you find yourself struggling to test something, ask:
+
+- **Is this unit doing too much?** Split it into smaller pieces.
+- **Are there too many dependencies?** Inject them or extract pure logic.
+- **Is the state management tangled?** Separate state from behavior.
+- **Am I testing implementation details?** Test behavior, not internals.
+
+The answer is almost always "refactor the code" rather than "write a more elaborate test."
+
+### Exception: Performance-Critical Code
+
+Code optimized for performance may have a structure that's harder to test (e.g., inlined logic, avoiding allocations). This is acceptable **only if**:
+
+1. **Explicitly marked** — Comment explains why this code is performance-critical
+2. **Well bounded** — Small and focused on one thing
+3. **Isolated** — Minimal dependencies, clear interface
+
+Such code still needs tests, but they may test at the boundary (inputs → outputs) rather than internals. The isolation requirement ensures that hard-to-test performance code doesn't spread throughout the codebase.
+
+---
+
 ## Status: Complete
 
 ### Completed