Feedback/Thoughts/Suggestions: **Section 11: Testing Strategy** - Confirming that `tests/` will live in the same repository? - To ensure the 80% unit test coverage is meaningful, prioritizing core business logic and transformation rules over boilerpate code, and validating edge cases (e.g., malformed ATS payloads) rather than just "happy paths". - Could add: `Unit tests must be isolated and fast. No databases or external APIs; all I/O must be mocked.` - I recommend removing the "20%" metric as it's hard to measure. Instead, let's define coverage by Criticality: `Every flow marked as 'Critical' in a Spec File must have an automated integration test. A feature is not 'Done' until these pass.` - State-Based Assertions: Integration tests should focus on the End State. For example: "Verify the job exists in the database with the correct Trade Me Category ID after a sync." - For the hard CI/CD gate, let's explicitly state that the pipeline will block merges if coverage falls below 80% OR if any Critical Path integration test fails. **Section 13: CI/CD & SDD** - Spec-Driven Testing: Every Individual Spec File (.md) should include a "Validation" section. This acts as the AI's instruction manual for building tests. Since we are using Gherkin (Given/When/Then), we should require that integration tests are generated directly from these scenarios to ensure 1:1 parity between the spec and the code. - I suggest a workflow where the AI generates the Integration Test first. This acts as a "logic check" on the spec before the implementation code is even written. - The "Done" Definition: A feature is only "Done" when the Spec, the Implementation, the Unit Tests, and the Integration Tests are all committed together. **Section 14: Non-Negotiables** MUST DO ✅ - For Integration Tests, use real internal dependencies (Database/Queues via Testcontainers) and use external mocking to simulate ATS and Trade Me responses to prevent pipeline failure due to external network issues. - Data Seeding. Use a consistent strategy to "seed" the database with known data before integration tests run. This ensures tests are repeatable and don't rely on whatever data happens to be in the DB. - To improve observability during integration testing, we could use Correlation IDs for every job sync to allow us to trace a single job's journey from the ATS to Trade Me in the logs, making it faster to debug why an integration test failed. - Spec-Test Sync. If the code logic changes during development, the Markdown Spec must be updated first. MUST NOT DO ❌: - "Empty" Tests. Do not accept AI-generated tests that pass without meaningful assertions (e.g., tests that check if a function ran but not what it actually did). **E2E Tests:** - Since true E2E is expensive and prone to flakiness, I suggest we lean heavily on our Integration Tests with API Mocks for daily development. We could limit E2E to a single 'Smoke Test' in the Staging environment to verify that our connections to the real ATS and Trade Me are active. Or something!