chore: add test verification and code quality rules to Ralph CLAUDE.md

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: NathanFlurry

scripts/ralph/CLAUDE.md

@@ -15,6 +15,55 @@ You are an autonomous coding agent working on a software project.
 9. Update the PRD to set `passes: true` for the completed story
 10. Append your progress to `progress.txt`
 
+## Test Verification (CRITICAL)
+
+A story is **only complete** when its tests actually EXECUTE and PASS. Follow these rules strictly:
+
+### Skipped Tests Are Not Passing Tests
+
+- After running tests, check the vitest summary line: `Tests  X passed | Y skipped | Z failed`
+- If any tests relevant to your story are **skipped**, the story does NOT pass
+- Skipped tests mean there's a blocker (missing dependency, unimplemented bridge, env issue)
+- If you write tests that skip due to a known blocker, set `passes: false` and document the blocker in the story's `notes` field
+- NEVER set `passes: true` for a story whose tests skip — this is dishonest and wastes future iterations
+
+### Check for Unhandled Errors
+
+- After running tests, check for the `Unhandled Errors` section in vitest output
+- Unhandled rejections and uncaught exceptions indicate bugs even when individual tests pass
+- If your story's tests produce unhandled errors, fix them before marking the story complete
+- Common cause: use-after-dispose (V8 context cleaned up before pending callbacks resolve)
+
+### Run Targeted Tests
+
+- Run ONLY the test file(s) relevant to your story, not the entire test suite
+- Example: `npx vitest run packages/secure-exec/tests/cli-tools/my-test.test.ts --reporter=verbose`
+- Check the verbose output to confirm each test case passes (not skips)
+- Only run the full suite if your changes could affect other tests
+
+### Tests With Runtime Probes
+
+Some tests use runtime probes (e.g., checking if a binary exists, if isTTY bridge works, if a module loads in the VM). If ALL tests skip because a probe fails:
+- The story is **blocked**, not complete
+- Set `passes: false` with a clear note explaining the blocker
+- If possible, fix the blocker as part of the story
+- If the blocker is out of scope, document it and move on — do NOT lie about completion
+
+## Code Quality
+
+### No Copy-Paste Duplication
+
+- Before writing a utility class or helper function, check if it already exists in a shared module
+- If you need the same code in multiple test files, extract it into a shared module (e.g., `test-utils.ts`, `shared-harness.ts`)
+- Common offenders: command executors, stdio capture helpers, overlay VFS factories, driver classes
+- If you find existing duplication, refactor it into a shared module as part of your story
+
+### Follow Existing Patterns
+
+- Read nearby test files and follow the same patterns
+- Use `createTestNodeRuntime()` from `test-utils.ts` when creating test runtimes
+- Use existing shared helpers before creating new ones
+
 ## Progress Report Format
 
 APPEND to progress.txt (never replace, always append):
@@ -102,3 +151,4 @@ If there are still stories with `passes: false`, end your response normally (ano
 - Commit frequently
 - Keep CI green
 - Read the Codebase Patterns section in progress.txt before starting
+- NEVER mark `passes: true` unless tests actually execute and pass (not skip)