refactor: restructure cursor rules with new meta-rule architecture
- Remove legacy rule files (documentation.mdc, general_development.mdc, etc.) - Implement new meta-rule system with core, app, and feature categories - Add meta-rule files for different workflows (bug diagnosis, feature planning, etc.) - Create organized directory structure: core/, app/, features/, database/, etc. - Add comprehensive README.md for rules documentation - Establish new rule architecture with always-on and workflow-specific rules This restructuring improves rule organization, enables better workflow management, and provides clearer separation of concerns for different development tasks.
This commit is contained in:
Matthew Raymer
75
.cursor/rules/architecture/README.md
Normal file
75
.cursor/rules/architecture/README.md
Normal file
@@ -0,0 +1,75 @@
|
||||
# Architecture Rules Directory
|
||||
|
||||
**Author**: Matthew Raymer
|
||||
**Date**: 2025-08-20
|
||||
**Status**: 🎯 **ACTIVE** - Architecture protection guidelines
|
||||
|
||||
## Overview
|
||||
|
||||
This directory contains MDC (Model Directive Configuration) rules that protect
|
||||
critical architectural components of the TimeSafari project. These rules ensure
|
||||
that changes to system architecture follow proper review, testing, and
|
||||
documentation procedures.
|
||||
|
||||
## Available Rules
|
||||
|
||||
### Build Architecture Guard (`build_architecture_guard.mdc`)
|
||||
|
||||
Protects the multi-platform build system including:
|
||||
|
||||
- Vite configuration files
|
||||
- Build scripts and automation
|
||||
- Platform-specific configurations (iOS, Android, Electron, Web)
|
||||
- Docker and deployment infrastructure
|
||||
- CI/CD pipeline components
|
||||
|
||||
**When to use**: Any time you're modifying build scripts, configuration files,
|
||||
or deployment processes.
|
||||
|
||||
**Authorization levels**:
|
||||
|
||||
- **Level 1**: Minor changes (review required)
|
||||
- **Level 2**: Moderate changes (testing required)
|
||||
- **Level 3**: Major changes (ADR required)
|
||||
|
||||
## Usage Guidelines
|
||||
|
||||
### For Developers
|
||||
|
||||
1. **Check the rule**: Before making architectural changes, review the relevant
|
||||
rule
|
||||
2. **Follow the process**: Use the appropriate authorization level
|
||||
3. **Complete validation**: Run through the required checklist
|
||||
4. **Update documentation**: Keep BUILDING.md and related docs current
|
||||
|
||||
### For Reviewers
|
||||
|
||||
1. **Verify authorization**: Ensure changes match the required level
|
||||
2. **Check testing**: Confirm appropriate testing has been completed
|
||||
3. **Validate documentation**: Ensure BUILDING.md reflects changes
|
||||
4. **Assess risk**: Consider impact on other platforms and systems
|
||||
|
||||
## Integration with Other Rules
|
||||
|
||||
- **Version Control**: Works with `workflow/version_control.mdc`
|
||||
- **Research & Diagnostic**: Supports `research_diagnostic.mdc` for
|
||||
investigations
|
||||
- **Software Development**: Aligns with development best practices
|
||||
- **Markdown Automation**: Integrates with `docs/markdown-automation.mdc` for
|
||||
consistent documentation formatting
|
||||
|
||||
## Emergency Procedures
|
||||
|
||||
If architectural changes cause system failures:
|
||||
|
||||
1. **Immediate rollback** to last known working state
|
||||
2. **Document the failure** with full error details
|
||||
3. **Investigate root cause** using diagnostic workflows
|
||||
4. **Update procedures** to prevent future failures
|
||||
|
||||
---
|
||||
|
||||
**Status**: Active architecture protection
|
||||
**Priority**: Critical
|
||||
**Maintainer**: Development team
|
||||
**Next Review**: 2025-09-20
|
||||
186
.cursor/rules/architecture/build_architecture_guard.mdc
Normal file
186
.cursor/rules/architecture/build_architecture_guard.mdc
Normal file
@@ -0,0 +1,186 @@
|
||||
|
||||
# Build Architecture Guard Directive
|
||||
|
||||
**Author**: Matthew Raymer
|
||||
**Date**: 2025-08-22
|
||||
**Status**: 🎯 **ACTIVE** - Build system protection guidelines
|
||||
|
||||
## Purpose
|
||||
|
||||
Protect the TimeSafari building architecture from unauthorized changes that
|
||||
could break the multi-platform build pipeline, deployment processes, or
|
||||
development workflow. This directive ensures all build system modifications
|
||||
follow proper review, testing, and documentation procedures.
|
||||
|
||||
**Note**: Recent Android build system enhancements (2025-08-22) include
|
||||
sophisticated asset validation, platform-specific API routing, and automatic
|
||||
resource regeneration. These features require enhanced testing and validation
|
||||
procedures.
|
||||
|
||||
## Protected Architecture Components
|
||||
|
||||
### Core Build Infrastructure
|
||||
|
||||
- **Vite Configuration Files**: `vite.config.*.mts` files
|
||||
|
||||
- **Build Scripts**: All scripts in `scripts/` directory
|
||||
|
||||
- **Package Scripts**: `package.json` build-related scripts
|
||||
|
||||
- **Platform Configs**: `capacitor.config.ts`, `electron/`, `android/`,
|
||||
|
||||
`ios/`
|
||||
|
||||
- **Docker Configuration**: `Dockerfile`, `docker-compose.yml`
|
||||
|
||||
- **Environment Files**: `.env.*`, `.nvmrc`, `.node-version`
|
||||
|
||||
### Android-Specific Build Validation
|
||||
|
||||
- **Asset Validation Scripts**:
|
||||
|
||||
`validate_android_assets()` function and resource checking
|
||||
|
||||
- **Resource Generation**: `capacitor-assets` integration and verification
|
||||
|
||||
- **Platform-Specific IP Handling**:
|
||||
|
||||
Android emulator vs physical device API routing
|
||||
|
||||
- **Build Mode Validation**: Development/test/production mode handling
|
||||
|
||||
- **Resource Fallback Logic**:
|
||||
|
||||
Automatic regeneration of missing Android resources
|
||||
|
||||
### Critical Build Dependencies
|
||||
|
||||
- **Build Tools**: Vite, Capacitor, Electron, Android SDK, Xcode
|
||||
|
||||
- **Asset Management**: `capacitor-assets.config.json`, asset scripts
|
||||
|
||||
- **Testing Infrastructure**: Playwright, Jest, mobile test scripts
|
||||
|
||||
- **CI/CD Pipeline**: GitHub Actions, build validation scripts
|
||||
|
||||
- **Service Worker Assembly**: `sw_scripts/`, `sw_combine.js`, WASM copy steps
|
||||
|
||||
## Change Authorization Requirements
|
||||
|
||||
### Level 1: Minor Changes (Requires Review)
|
||||
|
||||
- Documentation updates to `BUILDING.md`
|
||||
|
||||
- Non-breaking script improvements
|
||||
|
||||
- Test additions or improvements
|
||||
|
||||
- Asset configuration updates
|
||||
|
||||
**Process**: Code review + basic testing
|
||||
|
||||
### Level 2: Moderate Changes (Requires Testing)
|
||||
|
||||
- New build script additions
|
||||
|
||||
- Environment variable changes
|
||||
|
||||
- Dependency version updates
|
||||
|
||||
- Platform-specific optimizations
|
||||
|
||||
- **Build script argument parsing**:
|
||||
|
||||
New flag handling (--api-ip, --auto-run, --deploy)
|
||||
|
||||
- **Platform-specific environment overrides**:
|
||||
|
||||
Android API server IP customization
|
||||
|
||||
- **Asset regeneration logic**: Automatic fallback for missing Android resources
|
||||
|
||||
**Process**: Code review + platform testing + documentation update
|
||||
|
||||
### Level 3: Major Changes (Requires ADR)
|
||||
|
||||
- Build system architecture changes
|
||||
|
||||
- New platform support
|
||||
|
||||
- Breaking changes to build scripts
|
||||
|
||||
- Major dependency migrations
|
||||
|
||||
**Process**: ADR creation + comprehensive testing + team review
|
||||
|
||||
## Prohibited Actions
|
||||
|
||||
### ❌ Never Allow Without ADR
|
||||
|
||||
- **Delete or rename** core build scripts
|
||||
|
||||
- **Modify** `package.json` build script names
|
||||
|
||||
- **Change** Vite configuration structure
|
||||
|
||||
- **Remove** platform-specific build targets
|
||||
|
||||
- **Alter** Docker build process
|
||||
|
||||
- **Modify** CI/CD pipeline without testing
|
||||
|
||||
### ❌ Never Allow Without Testing
|
||||
|
||||
- **Update** build dependencies
|
||||
|
||||
- **Change** environment configurations
|
||||
|
||||
- **Modify** asset generation scripts
|
||||
|
||||
- **Alter** test infrastructure
|
||||
|
||||
- **Update** platform SDK versions
|
||||
|
||||
---
|
||||
|
||||
**See also**:
|
||||
|
||||
- `.cursor/rules/architecture/build_validation.mdc` for
|
||||
|
||||
detailed validation procedures
|
||||
|
||||
- `.cursor/rules/architecture/build_testing.mdc` for testing requirements
|
||||
|
||||
**Status**: Active build protection guidelines
|
||||
**Priority**: Critical
|
||||
**Estimated Effort**: Ongoing reference
|
||||
**Dependencies**: None
|
||||
**Stakeholders**: Development team, DevOps team, Build team
|
||||
|
||||
**Estimated Effort**: Ongoing vigilance
|
||||
**Dependencies**: All build system components
|
||||
**Stakeholders**: Development team, DevOps, Platform owners
|
||||
**Next Review**: 2025-09-22
|
||||
|
||||
## Model Implementation Checklist
|
||||
|
||||
### Before Build Changes
|
||||
|
||||
- [ ] **Change Level**: Determine if change is L1, L2, or L3
|
||||
- [ ] **Impact Assessment**: Assess impact on build system architecture
|
||||
- [ ] **ADR Requirement**: Check if ADR is required for major changes
|
||||
- [ ] **Testing Planning**: Plan appropriate testing for change level
|
||||
|
||||
### During Build Changes
|
||||
|
||||
- [ ] **Guard Compliance**: Ensure changes comply with build architecture guard
|
||||
- [ ] **Documentation**: Document changes according to level requirements
|
||||
- [ ] **Testing**: Execute appropriate testing for change level
|
||||
- [ ] **Review Process**: Follow required review process for change level
|
||||
|
||||
### After Build Changes
|
||||
|
||||
- [ ] **Validation**: Verify build system still functions correctly
|
||||
- [ ] **Documentation Update**: Update relevant documentation
|
||||
- [ ] **Team Communication**: Communicate changes to affected teams
|
||||
- [ ] **Monitoring**: Monitor for any build system issues
|
||||
248
.cursor/rules/architecture/build_testing.mdc
Normal file
248
.cursor/rules/architecture/build_testing.mdc
Normal file
@@ -0,0 +1,248 @@
|
||||
# Build Testing — Requirements and Emergency Procedures
|
||||
|
||||
> **Agent role**: Reference this file for testing requirements and
|
||||
emergency procedures when working with build architecture changes.
|
||||
|
||||
## Emergency Procedures
|
||||
|
||||
### Build System Broken
|
||||
|
||||
1. **Immediate**: Revert to last known working commit
|
||||
|
||||
2. **Investigation**: Create issue with full error details
|
||||
|
||||
3. **Testing**: Verify all platforms work after revert
|
||||
|
||||
4. **Documentation**: Update `BUILDING.md` with failure notes
|
||||
|
||||
### Platform-Specific Failure
|
||||
|
||||
1. **Isolate**: Identify which platform is affected
|
||||
|
||||
2. **Test Others**: Verify other platforms still work
|
||||
|
||||
3. **Rollback**: Revert platform-specific changes
|
||||
|
||||
4. **Investigation**: Debug in isolated environment
|
||||
|
||||
## Rollback Playbook
|
||||
|
||||
### Immediate Rollback
|
||||
|
||||
1. `git revert` or `git reset --hard <prev>`; restore prior `scripts/` or config
|
||||
|
||||
files
|
||||
|
||||
2. Rebuild affected targets; verify old behavior returns
|
||||
|
||||
3. Post-mortem notes → update this guard and `BUILDING.md` if gaps found
|
||||
|
||||
### Rollback Verification
|
||||
|
||||
- **Web**: `npm run build:web:dev` and `npm run build:web:prod`
|
||||
|
||||
- **Mobile**: `npm run build:android:test` and `npm run build:ios:test`
|
||||
|
||||
- **Desktop**: `npm run build:electron:dev` and packaging commands
|
||||
|
||||
- **Clean**: Run relevant `clean:*` scripts and verify re-build works
|
||||
|
||||
### Android-Specific Rollback Verification
|
||||
|
||||
- **Asset Generation**: `npm run build:android --assets` -
|
||||
|
||||
verify resources regenerate
|
||||
|
||||
- **API Routing**: Test both `--dev` and `--dev --api-ip <custom>` modes
|
||||
|
||||
- **Resource Validation**:
|
||||
|
||||
Check `android/app/src/main/res/` for all required assets
|
||||
|
||||
- **Build Modes**: Verify development, test, and production modes all work
|
||||
|
||||
- **Resource Fallback**:
|
||||
|
||||
Confirm missing resources trigger automatic regeneration
|
||||
|
||||
## Integration Points
|
||||
|
||||
### With Version Control
|
||||
|
||||
- **Branch Protection**: Require reviews for build script changes
|
||||
|
||||
- **Commit Messages**: Must reference ADR for major changes
|
||||
|
||||
- **Testing**: All build changes must pass CI/CD pipeline
|
||||
|
||||
### With Documentation
|
||||
|
||||
- **BUILDING.md**: Must be updated for any script changes
|
||||
|
||||
- **README.md**: Must reflect new build requirements
|
||||
|
||||
- **CHANGELOG.md**: Must document breaking build changes
|
||||
|
||||
### With Testing
|
||||
|
||||
- **Pre-commit**: Run basic build validation
|
||||
|
||||
- **CI/CD**: Full platform build testing
|
||||
|
||||
- **Manual Testing**: Human verification of critical paths
|
||||
|
||||
## Competence Hooks
|
||||
|
||||
### Why This Works
|
||||
|
||||
- **Prevents Build Failures**: Catches issues before they reach production
|
||||
|
||||
- **Maintains Consistency**: Ensures all platforms build identically
|
||||
|
||||
- **Reduces Debugging Time**: Prevents build system regressions
|
||||
|
||||
### Common Pitfalls
|
||||
|
||||
- **Silent Failures**: Changes that work on one platform but break others
|
||||
|
||||
- **Dependency Conflicts**: Updates that create version incompatibilities
|
||||
|
||||
- **Documentation Drift**: Build scripts that don't match documentation
|
||||
|
||||
### Next Skill Unlock
|
||||
|
||||
- Learn to test build changes across all platforms simultaneously
|
||||
|
||||
### Teach-back
|
||||
|
||||
- "What three platforms must I test before committing a build script change?"
|
||||
|
||||
## Collaboration Hooks
|
||||
|
||||
### Team Review Requirements
|
||||
|
||||
- **Platform Owners**: iOS, Android, Electron, Web specialists
|
||||
|
||||
- **DevOps**: CI/CD pipeline maintainers
|
||||
|
||||
- **QA**: Testing infrastructure owners
|
||||
|
||||
### Discussion Prompts
|
||||
|
||||
- "Which platforms will be affected by this build change?"
|
||||
|
||||
- "How can we test this change without breaking existing builds?"
|
||||
|
||||
- "What's our rollback plan if this change fails?"
|
||||
|
||||
## Self-Check (Before Allowing Changes)
|
||||
|
||||
- [ ] **Authorization Level**: Is this change appropriate for the level?
|
||||
|
||||
- [ ] **Testing Plan**: Is there a comprehensive testing strategy?
|
||||
|
||||
- [ ] **Documentation**: Will BUILDING.md be updated?
|
||||
|
||||
- [ ] **Rollback**: Is there a safe rollback mechanism?
|
||||
|
||||
- [ ] **Team Review**: Have appropriate stakeholders been consulted?
|
||||
|
||||
- [ ] **CI/CD**: Will this pass the build pipeline?
|
||||
|
||||
## Continuous Improvement & Feedback
|
||||
|
||||
### Feedback Collection
|
||||
|
||||
The Build Architecture Guard system includes feedback mechanisms to continuously
|
||||
improve its effectiveness:
|
||||
|
||||
- **User Feedback**: Script includes feedback prompts for guard improvements
|
||||
|
||||
- **Pattern Analysis**:
|
||||
|
||||
Monitor which file patterns trigger false positives/negatives
|
||||
|
||||
- **Documentation Gaps**: Track which changes lack proper documentation
|
||||
|
||||
- **Testing Effectiveness**: Measure how often guard catches actual issues
|
||||
|
||||
### Feedback Integration Process
|
||||
|
||||
1. **Collect Feedback**: Monitor guard execution logs and user reports
|
||||
|
||||
2. **Analyze Patterns**: Identify common false positives or missed patterns
|
||||
|
||||
3. **Update Rules**: Modify `build_architecture_guard.mdc` based on feedback
|
||||
|
||||
4. **Enhance Script**: Update `build-arch-guard.sh` with new validations
|
||||
|
||||
5. **Test Changes**: Verify guard improvements don't introduce new issues
|
||||
|
||||
6. **Document Updates**: Update guard documentation with new patterns
|
||||
|
||||
### Feedback Categories
|
||||
|
||||
- **False Positives**: Files flagged as sensitive that shouldn't be
|
||||
|
||||
- **False Negatives**: Sensitive files that weren't caught
|
||||
|
||||
- **Missing Patterns**: New file types that should be protected
|
||||
|
||||
- **Overly Strict**: Patterns that are too restrictive
|
||||
|
||||
- **Documentation Gaps**: Missing guidance for specific change types
|
||||
|
||||
- **Testing Improvements**: Better validation procedures
|
||||
|
||||
### Feedback Reporting
|
||||
|
||||
When reporting guard issues, include:
|
||||
|
||||
- **File patterns** that triggered false positives/negatives
|
||||
|
||||
- **Build system changes** that weren't properly caught
|
||||
|
||||
- **Documentation gaps** in current guard rules
|
||||
|
||||
- **Testing procedures** that could be improved
|
||||
|
||||
- **User experience** issues with guard enforcement
|
||||
|
||||
---
|
||||
|
||||
**See also**:
|
||||
|
||||
- `.cursor/rules/architecture/build_architecture_guard.mdc` for
|
||||
|
||||
core protection guidelines
|
||||
|
||||
- `.cursor/rules/architecture/build_validation.mdc` for validation procedures
|
||||
|
||||
**Status**: Active testing requirements
|
||||
**Priority**: High
|
||||
**Estimated Effort**: Ongoing reference
|
||||
**Dependencies**: build_architecture_guard.mdc, build_validation.mdc
|
||||
**Stakeholders**: Development team, DevOps team, Build team
|
||||
|
||||
## Model Implementation Checklist
|
||||
|
||||
### Before Build Testing
|
||||
|
||||
- [ ] **Test Planning**: Plan comprehensive testing strategy for build changes
|
||||
- [ ] **Platform Coverage**: Identify all platforms that need testing
|
||||
- [ ] **Risk Assessment**: Assess testing risks and mitigation strategies
|
||||
- [ ] **Resource Planning**: Plan testing resources and time requirements
|
||||
|
||||
### During Build Testing
|
||||
|
||||
- [ ] **Test Execution**: Execute planned tests across all platforms
|
||||
- [ ] **Issue Tracking**: Track and document any issues found
|
||||
- [ ] **Feedback Collection**: Collect feedback on testing effectiveness
|
||||
- [ ] **Documentation**: Document testing procedures and results
|
||||
|
||||
### After Build Testing
|
||||
|
||||
- [ ] **Result Analysis**: Analyze testing results and identify patterns
|
||||
- [ ] **Feedback Integration**: Integrate feedback into testing procedures
|
||||
- [ ] **Process Improvement**: Update testing procedures based on feedback
|
||||
- [ ] **Team Communication**: Share testing results and improvements with team
|
||||
224
.cursor/rules/architecture/build_validation.mdc
Normal file
224
.cursor/rules/architecture/build_validation.mdc
Normal file
@@ -0,0 +1,224 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user