# Build Validation — Procedures and Requirements

> **Agent role**: Reference this file for
  detailed validation procedures when working with build architecture changes.

## Required Validation Checklist

### Before Any Build System Change

- [ ] **Impact Assessment**: Which platforms are affected?

- [ ] **Testing Plan**: How will this be tested across platforms?

- [ ] **Rollback Plan**: How can this be reverted if it breaks?

- [ ] **Documentation**: Will `BUILDING.md` need updates?

- [ ] **Dependencies**: Are all required tools available?

### After Build System Change

- [ ] **Web Platform**: Does `npm run build:web:dev` work?

- [ ] **Mobile Platforms**: Do iOS/Android builds succeed?

- [ ] **Desktop Platform**: Does Electron build and run?

- [ ] **Tests Pass**: Do all build-related tests pass?

- [ ] **Documentation Updated**: Is `BUILDING.md` current?

## Specific Test Commands (Minimum Required)

### Web Platform

- **Development**: `npm run build:web:dev` - serve and load app

- **Production**: `npm run build:web:prod` - verify SW and WASM present

### Mobile Platforms

- **Android**: `npm run build:android:test` or `:prod` - confirm assets copied

- **iOS**: `npm run build:ios:test` or `:prod` - verify build succeeds

### Android Platform (Enhanced)

- **Development Mode**: `npm run build:android --dev` -

  verify 10.0.2.2 API routing

- **Custom IP Mode**: `npm run build:android --dev --api-ip 192.168.1.100` -

  verify custom IP

- **Asset Validation**: `npm run build:android --assets` -

  verify resource generation

- **Deploy Mode**: `npm run build:android --deploy` - verify device deployment

### Desktop Platform

- **Electron**: `npm run build:electron:dev` and packaging for target OS

- **Verify**: Single-instance behavior and app boot

### Auto-run (if affected)

- **Test Mode**: `npm run auto-run:test` and platform variants

- **Production Mode**: `npm run auto-run:prod` and platform variants

### Clean and Rebuild

- Run relevant `clean:*` scripts and ensure re-build works

## Risk Matrix & Required Validation

### Environment Handling

- **Trigger**: Change to `.env.*` loading / variable names

- **Validation**: Prove `dev/test/prod` builds; show environment echo in logs

### Script Flow

- **Trigger**: Reorder steps (prebuild → build → package), new flags

- **Validation**: Dry-run + normal run, show exit codes & timing

### Platform Packaging

- **Trigger**: Electron NSIS/DMG/AppImage, Android/iOS bundle

- **Validation**: Produce installer/artifact and open it;

  verify single-instance,
  icons, signing

### Service Worker / WASM

- **Trigger**: `sw_combine.js`, WASM copy path

- **Validation**: Verify combined SW exists and is injected; page loads offline;

  WASM present

### Docker

- **Trigger**: New base image, build args

- **Validation**: Build image locally; run container; list produced `/dist`

### Android Asset Management

- **Trigger**: Changes to `validate_android_assets()` function or resource paths

- **Validation**:

  Run `npm run build:android --assets` and verify all mipmap/drawable resources

- **Risk**: Missing splash screens or app icons causing build failures

### Android API Routing

- **Trigger**: Changes to Android-specific API server IP logic

- **Validation**: Test both emulator (10.0.2.2) and custom IP modes

- **Risk**: API connectivity failures on different device types

### Signing/Notarization

- **Trigger**: Cert path/profiles

- **Validation**: Show signing logs + verify on target OS

## PR Template (Paste into Description)

- [ ] **Level**: L1 / L2 / L3 + justification

- [ ] **Files & platforms touched**:

- [ ] **Risk triggers & mitigations**:

- [ ] **Commands run (paste logs)**:

- [ ] **Artifacts (names + sha256)**:

- [ ] **Docs updated (sections/links)**:

- [ ] **Rollback steps verified**:

- [ ] **CI**: Jobs passing and artifacts uploaded

## ADR Trigger List

Raise an ADR when you propose any of:

- **New build stage** or reorder of canonical stages

- **Replacement of packager** / packaging format

- **New environment model** or secure secret handling scheme

- **New service worker assembly** strategy or cache policy

- **New Docker base** or multi-stage pipeline

- **Relocation of build outputs** or directory conventions

- **New Android build modes** or argument parsing logic

- **Changes to asset validation** or resource generation strategy

- **Modifications to platform-specific API routing** (

  Android emulator vs physical)

- **New Android deployment strategies** or device management

**ADR must include**:
  motivation, alternatives, risks, validation plan, rollback,
  doc diffs.

---

**See also**:

- `.cursor/rules/architecture/build_architecture_guard.mdc` for

  core protection guidelines

- `.cursor/rules/architecture/build_testing.mdc` for testing requirements

**Status**: Active validation procedures
**Priority**: High
**Estimated Effort**: Ongoing reference
**Dependencies**: build_architecture_guard.mdc
**Stakeholders**: Development team, DevOps team, Build team

## Model Implementation Checklist

### Before Build Changes

- [ ] **Level Assessment**: Determine build validation level (L1/L2/L3)
- [ ] **Platform Analysis**: Identify all platforms affected by changes
- [ ] **Risk Assessment**: Identify risk triggers and mitigation strategies
- [ ] **Rollback Planning**: Plan rollback steps for build failures

### During Build Implementation

- [ ] **Validation Commands**: Run appropriate validation commands for level
- [ ] **Platform Testing**: Test changes across all affected platforms
- [ ] **Risk Mitigation**: Implement identified risk mitigation strategies
- [ ] **Documentation**: Document all commands run and their outputs

### After Build Implementation

- [ ] **Artifact Validation**: Verify build artifacts are correct and accessible
- [ ] **CI Verification**: Ensure CI jobs pass and artifacts are uploaded
- [ ] **Documentation Update**: Update relevant documentation sections
- [ ] **Team Communication**: Share build validation results with team