Starwards Verification

Verification Before Completion - Starwards

Overview

Claiming work is complete without verification is dishonesty, not efficiency.

Core principle: "Evidence before claims, always."

Starwards-specific: Run project commands, check all module tests, verify E2E snapshots.

Verification includes conformance to the code standards in docs/standards/ (structure, style, naming) — review the diff against them before claiming completion.

The Iron Law

NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE

If you haven't run the verification command in this message, you cannot claim it passes.

The Gate Function

BEFORE claiming any status:

1. IDENTIFY: Which Starwards command proves this claim?
2. RUN: Execute the EXACT command (fresh, complete)
3. READ: Full output, exit code, count failures
4. VERIFY: Does output confirm the claim?
   - If NO: State actual status with evidence
   - If YES: State claim WITH evidence
5. ONLY THEN: Make the claim

Skip any step = lying, not verifying

Starwards Verification Commands

Unit & Integration Tests

# All tests (core, server, node-red)
npm test
# Expected: "Tests: X passed, X total" with 0 failures

# Specific module
npm test -- --projects=core
npm test -- --projects=server
# Expected: All tests in that module pass

# Specific file
npm test -- modules/core/test/shield.spec.ts
# Expected: All tests in file pass

# Specific test by name
npm test -- --testNamePattern="shield recharge"
# Expected: Matching tests pass

# Watch mode (during development)
npm test -- --watch
# Not for verification - use for dev only

Verification pattern:

✅ Correct:
[Run: npm test]
[Output shows: Tests: 215 passed, 215 total]
"All tests pass"

❌ Wrong:
"Tests should pass now"
"I fixed the bug, so tests will pass"

E2E Tests

# All E2E tests
npm run test:e2e
# Expected: All tests pass, 0 failures

# Specific test file
npm run test:e2e -- engineer-screen.spec.ts
# Expected: All tests in file pass

# With visible browser (debugging only)
npm run test:e2e -- --headed
# Not for verification - use for debugging

# Update snapshots (after intentional visual changes)
npm run test:e2e -- --update-snapshots
# Then verify updated snapshots look correct
# Then commit new snapshots with changes

Verification pattern:

✅ Correct:
[Run: npm run test:e2e]
[Output shows: 18 passed (2.1m)]
[Check test-results/ - no failures]
"All E2E tests pass"

❌ Wrong:
"E2E tests probably pass, I only changed server code"
"Manual testing shows it works"

Type Checking

# Full TypeScript type check
npm run test:types
# Expected: No errors, clean output

# Specific module (manual)
cd modules/core && npx tsc --noEmit
# Expected: No type errors

Verification pattern:

✅ Correct:
[Run: npm run test:types]
[Output shows no errors, exit code 0]
"TypeScript types are correct"

❌ Wrong:
"VSCode shows no red squiggles"
"Types should be fine"

Code Formatting

# Check formatting (doesn't modify files)
npm run test:format
# Expected: No formatting errors

# Fix formatting (modifies files)
npm run lint:fix
# Expected: Files auto-formatted, then test:format passes

# Just Prettier
npm run prettier
# Expected: All files formatted correctly

# Just ESLint
npm run lint
# Expected: No linting errors

Verification pattern:

✅ Correct:
[Run: npm run test:format]
[Output: All files pass]
"Code formatting is correct"

❌ Wrong:
"I used Prettier plugin, so formatting is fine"
"Code looks formatted to me"

Build

# Build all modules
npm run build
# Expected: All modules build successfully, no errors

# Build specific module
npm run build:core
npm run build:browser
npm run build:server
npm run build:node-red
# Expected: Module builds successfully

# Clean build (recommended)
npm run clean && npm run build
# Expected: Fresh build with no errors

Verification pattern:

✅ Correct:
[Run: npm run build]
[Output shows: core ✓, browser ✓, server ✓, node-red ✓]
[Exit code: 0]
"Build succeeds"

❌ Wrong:
"Linter passed, so build will work"
"Built successfully earlier"

Complete Verification (Before PR/Commit)

# Full verification sequence
npm run clean          # Clear artifacts
npm ci                 # Fresh dependencies
npm run test:types     # TypeScript check
npm run test:format    # Formatting check
npm run build          # Build all modules
npm test               # Unit tests
npm run test:e2e       # E2E tests

Verification pattern:

✅ Correct:
[Run all 7 commands in sequence]
[All show success]
"All checks pass, ready to commit"

❌ Wrong:
"I ran tests yesterday, they passed"
"Only changed one file, don't need full verification"

Module-Specific Verification

After Changing Core Module

cd modules/core && npm run build:watch  # Should already be running
npm test -- --projects=core             # Core tests
npm test                                # All tests (server may depend on core)

Why: Server and other modules depend on core. Changes must not break dependents.

After Changing Browser Module

npm run build:browser    # Rebuild browser
npm run test:e2e         # E2E tests verify UI
# Manual: Check http://localhost:3000 in browser

Why: Browser changes need visual verification.

After Changing Server Module

npm run build:server     # Rebuild server
npm test -- --projects=server  # Server tests
# Restart Terminal 3 (API server)
npm run test:e2e         # E2E tests verify server behavior

Why: Server must be restarted to pick up changes.

Common Verification Failures

Red Flags - STOP

• Using "should", "probably", "seems to"
• Expressing satisfaction before verification ("Great!", "Done!")
• About to commit without running full verification
• Trusting VSCode error display instead of CLI
• Relying on partial verification ("just unit tests")
• "Tests passed yesterday"
• "Only changed CSS, don't need tests"
• "Build worked on my machine"

Starwards-Specific Patterns

Float Precision Verification

// Claim: "Shield strength is 750"
test('shield strength matches expected', () => {
  expect(shield.strength).toBeCloseTo(750, 1); // ✅ Correct
  expect(shield.strength).toBe(750);            // ❌ Wrong (float32)
});

Multiplayer Verification

// Claim: "State syncs to all clients"
test('state syncs to multiple clients', async () => {
  const driver = new MultiClientDriver();
  await driver.start();

  const [c1, c2] = await Promise.all([
    driver.joinShip('ship-1'),
    driver.joinShip('ship-1')
  ]);

  driver.getShipManager('ship-1').state.shield.strength = 800;
  await driver.waitForSync();

  expect(c1.state.shield.strength).toBe(800);  // ✅ Both verified
  expect(c2.state.shield.strength).toBe(800);

  await driver.cleanup();
});

E2E Visual Verification

# Claim: "UI displays shield strength correctly"
npm run test:e2e -- shield-widget.spec.ts
# ✅ Correct: Test passes, screenshot matches expected

# Check test-results/ for any failures
# Review updated snapshots if --update-snapshots used

When To Apply

ALWAYS before:

• Committing changes (git commit)
• Creating PR (gh pr create)
• Marking task complete
• Claiming "bug fixed"
• Saying "tests pass"
• Moving to next feature

Rule applies to:

• Any success claim
• Any completion statement
• Any "done" or "finished" message
• Implications that work is complete

Rationalization Prevention

Integration with Other Skills

• starwards-tdd - Write tests BEFORE implementation
• starwards-debugging - Debug failures systematically
• starwards-monorepo - Understand module dependencies

The Bottom Line

"No shortcuts for verification."

npm run test:types && \
npm run test:format && \
npm run build && \
npm test && \
npm run test:e2e

Run the commands. Read the output. THEN claim the result.

This is non-negotiable.