forge-server 0.1.0

package/plugin/skills/test-strategy/SKILL.md

@@ -0,0 +1,365 @@
+---
+name: test-strategy
+description: >
+  This skill should be used when designing test strategies, planning test coverage, or determining
+  what and how to test. Used by the qa-strategist agent and referenced by implementation agents
+  for test-first development approaches.
+user-invocable: false
+---
+
+# Test Strategy Skill
+
+## The Test Pyramid: Structure for Sustainable Quality
+
+Adopt a layered testing strategy modeled on the test pyramid. The pyramid is not a suggestion — it is a structural requirement for a test suite that remains fast, stable, and meaningful as the codebase grows.
+
+### Unit Tests (Base Layer — Many, Fast)
+
+Unit tests form the foundation. Write the most of these. Each unit test exercises a single unit of business logic — a function, a method, a transformation, a validation rule — in complete isolation from external systems.
+
+Characteristics of a good unit test:
+
+- Execute in under 50ms. If a unit test takes longer, it is probably not a unit test.
+- Have zero I/O: no network, no filesystem, no database, no external services.
+- Mock only at the boundary. If the unit under test calls a service interface, mock that interface. Never mock internal methods of the unit itself.
+- Be deterministic. No random values, no wall-clock time, no environment-dependent behavior. Supply all inputs explicitly.
+
+Target: aim for hundreds of unit tests per module. They should run in seconds, not minutes.
+
+### Integration Tests (Middle Layer — Moderate, Thorough)
+
+Integration tests verify that components work together correctly across service boundaries. These tests exercise real connections — real database queries, real HTTP calls between services, real message queue interactions — but within a controlled environment.
+
+Characteristics of a good integration test:
+
+- Use real database connections (test databases, Docker containers, or in-memory alternatives where faithful).
+- Test API contracts: send a real HTTP request to the endpoint, verify the response shape, status codes, and headers.
+- Test database queries: execute the actual Drizzle query, verify the returned data against known seed state.
+- Test service-to-service interactions: verify that a service call produces the expected side effects.
+- Run in a test environment with known state. Set up fixtures before each test or test group. Tear down after.
+
+Target: tens to low hundreds of integration tests per service. They will take longer (seconds each) but must remain reliable.
+
+### End-to-End Tests (Top Layer — Few, Comprehensive)
+
+E2E tests validate complete user flows through the entire system. These are the most expensive to write, the slowest to run, and the most fragile — so write few of them, but make each one count.
+
+Characteristics of a good E2E test:
+
+- Model a real user journey: login, navigate, perform action, verify outcome, logout.
+- Use Playwright for browser-based E2E. Target user-visible behavior, not DOM structure.
+- Cover only critical paths: the flows that, if broken, would make the product unusable.
+- Accept some brittleness as the cost of realistic testing, but minimize it through good selector strategies (data-testid attributes, ARIA roles — never CSS classes or tag hierarchies).
+
+Target: tens of E2E tests per product. Each one should represent a user story from the vision document.
+
+## Contract Testing: Test the Interface, Not the Implementation
+
+The single most important principle in test design: **if a stub passes the test, the test is wrong.**
+
+This means:
+
+- Test observable behavior, not internal mechanics. A test for a sorting function should verify the output order, not that `Array.prototype.sort` was called.
+- Test the contract a module promises to fulfill, not how it fulfills it. If a service promises to return a paginated list of users, test the response shape and pagination behavior. Do not test that it used a specific SQL query.
+- Refactoring should not break tests. If changing the internal implementation of a function (without changing its inputs or outputs) causes tests to fail, those tests are testing implementation details and must be rewritten.
+- Assert on results, not on call counts. `expect(service.save).toHaveBeenCalledTimes(1)` is almost always a test of implementation, not behavior. Instead, assert that the data was actually persisted by reading it back.
+
+### Contract Tests for API Boundaries
+
+For services that expose APIs consumed by other services or frontends:
+
+- Define the contract explicitly (OpenAPI spec, TypeScript interface, or Zod schema).
+- Write tests that validate the response against the contract, not against a hardcoded expected object.
+- When the contract changes, update the contract definition first, then update the implementation. Tests against the old contract should fail — that is the point.
+
+## Test Data Strategy
+
+Test data quality directly determines test quality. Lazy test data produces lazy coverage.
+
+### Principles
+
+- **Use realistic data.** Names should be actual names ("Elena Rodriguez"), not placeholders ("test123", "foo bar", "John Doe" for every record). Emails should look like emails. Dates should be plausible.
+- **Exercise edge cases through data.** Include: empty strings, maximum-length strings, Unicode characters (CJK, emoji, RTL scripts), null values where nullable, zero and negative numbers, dates at epoch and at year boundaries, deeply nested objects.
+- **Use factory functions, not hardcoded fixtures.** Create a `createTestUser(overrides?)` factory that generates a realistic user with defaults, allowing individual fields to be overridden per test. This keeps tests concise while ensuring realistic data.
+- **Generate data deterministically.** If using random data, seed the generator so tests are reproducible. Flaky tests from random data are worse than no tests.
+- **Match production shapes.** If production data has 50 fields, test data should have 50 fields. Do not test against a 3-field subset and assume it generalizes.
+
+### Test Database State
+
+For integration tests involving databases:
+
+- Use a dedicated test database. Never run tests against development or production data.
+- Seed known state before each test suite. Use explicit seed scripts, not shared mutable state.
+- Clean up after tests. Use transactions that roll back, or truncate tables between tests.
+- Avoid test-order dependencies. Each test must work in isolation, regardless of execution order.
+
+## E2E Testing with Playwright
+
+### Focus on User Flows, Not Components
+
+Playwright tests should model complete user journeys that cross component and page boundaries. A Playwright test is not a component test — it is a simulation of what a real user does.
+
+Structure each E2E test as a flow:
+
+1. **Arrange**: Navigate to the starting point, authenticate if needed, set up preconditions.
+2. **Act**: Perform the sequence of user actions (click, type, navigate, wait).
+3. **Assert**: Verify the final state from the user's perspective (visible text, URL, downloaded file, notification).
+
+### Selector Strategy
+
+Use selectors in this priority order:
+
+1. `data-testid` attributes — explicit, stable, decoupled from presentation.
+2. ARIA roles and accessible names — `getByRole('button', { name: 'Submit' })` — good for accessibility too.
+3. Text content — `getByText('Welcome back')` — acceptable for static text.
+4. **Never**: CSS classes, tag names, DOM hierarchy, or nth-child selectors. These break on any style or layout change.
+
+### Handling Asynchrony
+
+- Use Playwright's built-in waiting mechanisms (`waitForSelector`, `waitForURL`, `waitForResponse`). Never use `sleep()` or fixed timeouts.
+- Assert against final states, not intermediate states. The UI may transition through loading/skeleton states — wait for the final rendered state.
+- For network-dependent assertions, intercept and assert on network requests/responses rather than UI text alone.
+
+### Test Isolation
+
+- Each E2E test must be independent. Use fresh authentication state (Playwright storage state), clean data (API-based setup/teardown), and no shared session state between tests.
+- Use Playwright's test fixtures for reusable setup (authenticated page, seeded database, etc.).
+
+## Integration Test Design
+
+### Service Boundary Testing
+
+Test where services meet:
+
+- **HTTP boundaries**: Send actual requests to controller endpoints. Verify status codes, response shapes, error formats, and headers (CORS, cache control, content type).
+- **Database boundaries**: Execute actual queries through the repository/service layer. Verify correct data is read and written, including edge cases (empty results, constraint violations, concurrent access).
+- **External service boundaries**: Use WireMock, MSW, or Nock to simulate external APIs. Verify the integration handles success, failure, timeout, and unexpected response shapes.
+
+### What to Cover in Integration Tests
+
+- Request validation: malformed requests return 400 with descriptive error messages.
+- Authentication and authorization: unauthenticated requests return 401; unauthorized requests return 403; valid tokens grant access.
+- Database constraint enforcement: unique violations, foreign key violations, not-null violations produce appropriate application-level errors.
+- Pagination: first page, last page, empty page, out-of-range page.
+- Concurrent operations: two simultaneous writes to the same resource produce a consistent outcome.
+
+## Unit Test Design
+
+### What to Test
+
+- **Business logic**: calculations, transformations, state machines, decision trees.
+- **Validations**: input validation rules, schema enforcement, constraint checking.
+- **Data transformations**: mappers, serializers, formatters, parsers.
+- **Error handling paths**: verify that specific inputs produce specific error types with correct messages.
+- **Conditional logic**: every branch in an if/else or switch should have at least one test.
+
+### What to Mock
+
+Mock only at external boundaries:
+
+- Database clients/repositories (when testing service logic, not query correctness).
+- HTTP clients (when testing a service that calls an external API).
+- File system access (when testing logic that reads/writes files).
+- Clock/time (when testing time-dependent logic).
+
+Never mock:
+
+- Internal methods of the class under test.
+- Utility functions that are part of the same module.
+- Language/framework primitives.
+
+## Coverage Strategy
+
+100% code coverage is a vanity metric. A codebase with 100% coverage can still be full of bugs if the tests assert nothing meaningful.
+
+### What to Cover (Prioritized)
+
+1. **Happy paths**: the primary success scenarios for each feature. Non-negotiable.
+2. **Error paths**: what happens when things go wrong — invalid input, missing data, service unavailable, timeout. Non-negotiable.
+3. **Edge cases**: boundary values, empty inputs, maximum sizes, Unicode, null/undefined. High priority.
+4. **Security-relevant paths**: authentication, authorization, input sanitization, token validation, rate limiting. Non-negotiable.
+5. **Regression paths**: any bug that was found and fixed gets a test that would have caught it. Non-negotiable.
+
+### What NOT to Cover
+
+- Trivial getters and setters with no logic.
+- Framework-generated code (NestJS decorators, Drizzle schema definitions).
+- Third-party library behavior (do not test that `dayjs` parses dates correctly).
+- Configuration-only files (module imports, provider registrations with no logic).
+
+### Coverage Targets
+
+Set practical targets, not vanity targets:
+
+- Business logic modules: 90%+ line coverage, 85%+ branch coverage.
+- API controllers: 80%+ (focus on request/response contract, not framework plumbing).
+- Utility/helper modules: 95%+ (these are pure functions — easy to test thoroughly).
+- Overall project: 80%+ as a floor, not a ceiling. Below 80% indicates gaps; above 95% indicates possible over-testing of trivial code.
+
+## Test Naming Conventions
+
+Test names must describe behavior, not method names. A test name is a sentence that describes what the system does under specific conditions.
+
+### Pattern
+
+```
+should [expected behavior] when [condition]
+```
+
+### Good Examples
+
+- `should reject expired tokens with 401 status`
+- `should return empty array when no users match the filter`
+- `should paginate results with correct next cursor`
+- `should trim whitespace from email before validation`
+- `should cascade delete child records when parent is removed`
+
+### Bad Examples
+
+- `testValidateToken` — describes nothing about expected behavior.
+- `test1`, `test2` — meaningless.
+- `should work` — what does "work" mean?
+- `should call repository.save` — testing implementation, not behavior.
+
+### Test Organization
+
+Group tests by behavior, not by method:
+
+```typescript
+describe('UserService', () => {
+  describe('registration', () => {
+    it('should create a new user with hashed password', ...);
+    it('should reject duplicate email addresses', ...);
+    it('should send a verification email on success', ...);
+  });
+
+  describe('authentication', () => {
+    it('should return a JWT for valid credentials', ...);
+    it('should reject invalid passwords with 401', ...);
+    it('should lock account after 5 failed attempts', ...);
+  });
+});
+```
+
+## What NOT to Test
+
+Avoid wasting effort on tests that provide no meaningful coverage:
+
+- **Framework internals**: do not test that NestJS dependency injection works, that decorators apply metadata, or that middleware chains execute in order. Trust the framework.
+- **Trivial code**: a getter that returns `this.name` does not need a test. A setter that assigns a value does not need a test. Add a test only when logic is involved.
+- **Third-party library behavior**: do not test that `bcrypt.hash()` produces a hash or that `zod.parse()` validates schemas. Test that YOUR code uses these libraries correctly at the boundaries.
+- **Type system assertions**: if TypeScript's type checker prevents a class of bugs, do not write runtime tests for those same bugs. Let the compiler do its job.
+- **Test infrastructure**: do not test test utilities, test factories, or mock setup code. If test infrastructure needs tests, it is too complex.
+
+## Anti-Patterns to Avoid
+
+### Testing Implementation Details
+
+If a test breaks when the internal implementation changes but the external behavior stays the same, the test is coupled to implementation. Symptoms:
+
+- Asserting on method call counts (`toHaveBeenCalledTimes`).
+- Asserting on internal state (`expect(service._cache.size).toBe(3)`).
+- Asserting on intermediate steps rather than final outcomes.
+
+### Over-Mocking
+
+If a test has more mock setup code than assertion code, it is over-mocked. Symptoms:
+
+- Mocking 5+ dependencies for a single test.
+- Mock return values that are themselves mocked objects.
+- Tests that pass regardless of what the function under test does, because the mocks control the entire flow.
+
+### Testing the Mock
+
+If a test asserts behavior that is entirely determined by mock configuration, it is testing the mock, not the code. Example: mocking `findUser` to return `null`, then asserting that the service returns `null` — this tests the mock setup, not the service logic.
+
+### Fragile E2E Selectors
+
+CSS class selectors (`'.btn-primary'`), deeply nested selectors (`'div > ul > li:nth-child(3) > span'`), or auto-generated class names (`'.css-1a2b3c'`) produce E2E tests that break on every style change.
+
+### Shared Mutable Test State
+
+Tests that modify shared variables, database state, or global configuration without cleanup create order-dependent test suites that pass individually but fail when run together.
+
+## Test Plan Document Format
+
+For each feature or project, produce a test plan document at:
+
+```
+docs/plans/YYYY-MM-DD-{TITLE}/test-plan.md
+```
+
+Use the following structure:
+
+```markdown
+# Test Plan: {Feature Title}
+
+**Date**: YYYY-MM-DD
+**Status**: Draft | Active | Completed
+**Author**: {Agent name}
+**Vision Reference**: docs/plans/YYYY-MM-DD-{TITLE}/vision.md
+
+## Scope
+
+[What is being tested and what is explicitly excluded]
+
+## Test Pyramid Allocation
+
+| Layer | Count (est.) | Focus Areas |
+|-------|-------------|-------------|
+| Unit | ... | ... |
+| Integration | ... | ... |
+| E2E | ... | ... |
+
+## Unit Test Plan
+
+### Module: {module-name}
+| Test Case | Type | Priority |
+|-----------|------|----------|
+| should ... when ... | happy path | P0 |
+| should ... when ... | error path | P0 |
+| should ... when ... | edge case | P1 |
+
+[Repeat for each module]
+
+## Integration Test Plan
+
+### Boundary: {service-to-service or service-to-database}
+| Test Case | Dependencies | Priority |
+|-----------|-------------|----------|
+| should ... | [db, external API, etc.] | P0 |
+
+[Repeat for each boundary]
+
+## E2E Test Plan
+
+### Flow: {user-story-name}
+| Step | Action | Expected Outcome |
+|------|--------|-----------------|
+| 1 | Navigate to ... | Page loads with ... |
+| 2 | Click ... | Modal appears with ... |
+
+[Repeat for each critical flow]
+
+## Test Data Requirements
+
+[Describe factories, seed data, and fixtures needed]
+
+## Environment Requirements
+
+[Database, external services, environment variables, Docker containers needed]
+
+## Coverage Targets
+
+| Module | Line Target | Branch Target |
+|--------|------------|---------------|
+| ... | ...% | ...% |
+
+## Risks and Mitigations
+
+| Risk | Mitigation |
+|------|------------|
+| ... | ... |
+```
+
+Populate the test plan from the vision document's success criteria and user stories. Every success criterion must trace to at least one test case. Every user story must trace to at least one E2E flow.

package/plugin/skills/verification-protocol/SKILL.md

@@ -0,0 +1,256 @@
+---
+name: verification-protocol
+description: This skill should be used when verifying that implementation work is complete and correct — checking wiring, anti-stub compliance, XD conformance, code quality, test quality, and security. Used primarily by the inspector agent as the unified quality gate, and referenced by all implementation agents for self-verification before handoff.
+user-invocable: false
+---
+
+# Verification Protocol
+
+The verification protocol is the unified quality gate for the forge system. Nothing passes without evidence that it works. Reading code is insufficient — run commands, test endpoints, verify output.
+
+---
+
+## Core Principle
+
+> If it cannot be proven to work, it does not pass.
+
+Verification means executing, not reading. A function that "looks correct" is not verified. A function whose output has been observed and matches expectations is verified.
+
+---
+
+## The Seven Checks
+
+Every piece of work passes through all seven checks. Partial passes are failures. A single blocker in any check means the entire deliverable is blocked.
+
+### Check 1: Wiring Verification
+
+Confirm that all parts of the system are actually connected.
+
+**API Wiring:**
+- Every controller endpoint calls a real service method
+- Every service method calls real data access (Drizzle queries, external APIs)
+- Every data access returns real data from a real source
+- Response DTOs match the actual data shape returned
+- Error responses are properly typed and returned (not swallowed)
+
+**Frontend Wiring:**
+- Every component that displays data calls a real API endpoint
+- API base URLs and paths resolve to actual backend routes
+- Authentication tokens are attached to protected requests
+- Loading, error, and empty states are handled (not just the happy path)
+- Navigation/routing connects all pages
+
+**Database Wiring:**
+- Schema matches the migration output (run `db:generate`, verify SQL)
+- Seed data inserts successfully
+- Foreign keys reference existing tables
+- Indexes exist for queried columns
+- JSONB columns have explicit TypeScript types
+
+**Verification commands:**
+```bash
+# Backend starts without errors
+npm run start:dev
+
+# Frontend builds without errors
+npm run build
+
+# All migrations apply cleanly
+npm run db:migrate
+
+# Seed data loads
+npm run db:seed
+```
+
+### Check 2: Anti-Stub Enforcement
+
+Search production code for incomplete implementations. Any hit is a blocker unless explicitly justified.
+
+**Detection patterns (grep for these):**
+```
+TODO|FIXME|HACK|PLACEHOLDER|STUB|NOT.IMPLEMENTED
+return \[\]|return \{\}|return null|return ''
+lorem ipsum|coming soon|under construction
+console\.log\(.*error|catch.*\{\s*\}
+throw new Error\('Not implemented'\)
+```
+
+**Manual inspection targets:**
+- Service methods that return hardcoded arrays or objects
+- API endpoints that return 200 with empty or static bodies
+- Components that render placeholder text instead of real data
+- Error handlers that swallow exceptions silently
+- Functions with commented-out implementation
+
+**Acceptable exceptions:**
+- Mock data in test files (not production code)
+- Loading states and empty states (these are real UI features)
+- Feature flags gating incomplete features (the flag is real, the stub is not)
+- Graceful degradation for unavailable external services (must log and surface)
+
+### Check 3: XD Compliance
+
+Compare implementation against the Designer's XD plan (`xd-plan.md`).
+
+**Component compliance:**
+- Correct atomic level used (atom, molecule, organism)
+- Component names match the XD plan's naming convention
+- Props match the defined component contracts
+- Variant system follows the established pattern
+- No ad-hoc components that bypass the design system
+
+**Style compliance:**
+- No inline styles (`style={{}}`) — all styling through the design system
+- Color values come from theme tokens, not hardcoded hex/rgb
+- Spacing uses the defined scale (not arbitrary pixel values)
+- Typography uses the defined scale (not arbitrary font sizes)
+- Layout follows the grid system from xd-plan.md
+
+**Interaction compliance:**
+- Hover, focus, active, disabled states match the XD plan
+- Transitions and animations follow the defined patterns
+- Form validation displays errors as specified
+- Responsive breakpoints match the defined set
+
+### Check 4: Code Quality
+
+Review for clean patterns, maintainability, and correctness.
+
+**Structural quality:**
+- No circular dependencies between modules
+- Imports resolve correctly (no broken paths)
+- No unused imports, variables, or functions
+- Consistent naming conventions throughout
+- Files are in the correct directories per project convention
+
+**NestJS-specific:**
+- Modules properly import and export providers
+- Guards and interceptors are applied correctly
+- DTOs use class-validator decorators for input validation
+- Services are injectable and properly scoped
+- Environment variables read through ConfigService or lazy initialization (not top-level process.env)
+
+**TypeScript quality:**
+- No `any` types in production code (except justified edge cases)
+- Interfaces exported when used as return types (avoids TS4053)
+- Generics used appropriately (not over-engineered)
+- Strict null checks honored (no non-null assertions without justification)
+
+### Check 5: Test Quality
+
+Verify that tests exercise real behavior and would catch regressions.
+
+**The stub test litmus test:**
+> If production code were replaced with a hardcoded return value, would the test still pass? If yes, the test is insufficient.
+
+**Test quality checklist:**
+- Tests describe behavior, not method names
+- Tests use realistic data (not "foo", "bar", "test123")
+- Tests cover: happy path, error path, edge cases
+- Tests are independent (no shared mutable state between tests)
+- Integration tests use real service boundaries
+- E2E tests exercise user-visible flows, not internal APIs
+- Mocks are at external boundaries only (HTTP calls, database), not internal methods
+
+**Coverage assessment:**
+- Critical paths (auth, data mutation, payment) have comprehensive coverage
+- Edge cases (empty input, max length, special characters) are tested
+- Error paths (network failure, invalid data, unauthorized) are tested
+- Security-relevant paths (token validation, access control) are tested
+
+### Check 6: Security Review
+
+Scan for OWASP Top 10 vulnerabilities and common security mistakes.
+
+**Quick scan checklist:**
+- [ ] No hardcoded secrets, tokens, passwords, or API keys
+- [ ] All user input validated and sanitized before use
+- [ ] Authentication checks on all protected endpoints
+- [ ] Authorization checks enforce ownership/role requirements
+- [ ] No sensitive data in logs (tokens, passwords, PII)
+- [ ] CORS configured with specific origins (not wildcard `*`)
+- [ ] Rate limiting on public-facing endpoints
+- [ ] SQL injection prevented (parameterized queries via Drizzle)
+- [ ] XSS prevented (React escaping, no dangerouslySetInnerHTML with user data)
+- [ ] Dependencies checked for known vulnerabilities (`npm audit`)
+
+**Infrastructure security (if applicable):**
+- IAM policies follow least privilege
+- Secrets stored in AWS Secrets Manager (not env files in repos)
+- Network policies restrict pod-to-pod communication
+- IRSA roles scoped to specific service accounts
+
+### Check 7: Build and Runtime Verification
+
+Prove the system works by running it.
+
+**Build verification:**
+```bash
+# TypeScript compiles without errors
+npx tsc --noEmit
+
+# Application builds successfully
+npm run build
+
+# All tests pass
+npm run test
+
+# Linting passes
+npm run lint
+```
+
+**Runtime verification:**
+```bash
+# Application starts and responds
+npm run start:dev
+# Hit health check endpoint
+curl http://localhost:3000/health
+
+# Frontend dev server starts
+npm run dev
+# Verify page loads in browser
+```
+
+---
+
+## Failure Reporting Format
+
+Report each finding with:
+
+```
+## [BLOCKER|MAJOR|MINOR] — [Check Name] — [Location]
+
+**File:** path/to/file.ts:line
+**Finding:** Clear description of what is wrong
+**Evidence:** The specific code, output, or behavior observed
+**Fix:** Suggested remediation
+```
+
+- **BLOCKER:** Prevents delivery. Must be fixed before passing. (Stubs, broken wiring, security vulnerabilities)
+- **MAJOR:** Significant quality issue. Should be fixed before delivery. (Missing error handling, poor test coverage, XD drift)
+- **MINOR:** Improvement opportunity. Can be noted and addressed later. (Naming inconsistency, missing edge case test)
+
+---
+
+## Verdict Criteria
+
+**PASS:** All seven checks pass with zero blockers and zero majors. Minors documented.
+
+**PASS WITH WARNINGS:** All seven checks pass with zero blockers. Majors documented with explicit acknowledgment from the Strategist.
+
+**FAIL:** Any blocker exists. Work returns to the responsible agent with the failure report.
+
+---
+
+## Re-Verification After Fixes
+
+After fixes are applied, run the FULL protocol again — not just the failed items. Fixes can introduce new issues. The only exception: if the fix is a single-line change to a minor finding, re-run only the affected check.
+
+---
+
+## Reporting to Strategist and Knowledge Keeper
+
+After verification completes:
+
+1. **Strategist** receives: verdict, summary of findings, list of blockers/majors, recommendation (pass/iterate/escalate)
+2. **Knowledge Keeper** receives: patterns observed (recurring issues, new gotchas discovered, conventions violated), suggestions for CLAUDE.md updates