Browse Source
- Create comprehensive guard rules for build system protection - Define protected file patterns and validation requirements - Include risk matrix and required validation checklists - Add emergency procedures and rollback playbooksdialog-styles-unified
Matthew Raymer
2 days ago
2 changed files with 370 additions and 0 deletions
@ -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 |
||||
@ -0,0 +1,295 @@ |
|||||
|
--- |
||||
|
description: Guards against unauthorized changes to the TimeSafari building |
||||
|
architecture |
||||
|
alwaysApply: false |
||||
|
--- |
||||
|
|
||||
|
# Build Architecture Guard Directive |
||||
|
|
||||
|
**Author**: Matthew Raymer |
||||
|
**Date**: 2025-08-20 |
||||
|
**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. |
||||
|
|
||||
|
## 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` |
||||
|
|
||||
|
### 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 |
||||
|
|
||||
|
**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 |
||||
|
|
||||
|
## 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 |
||||
|
|
||||
|
### 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 |
||||
|
|
||||
|
## 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 |
||||
|
|
||||
|
## 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 |
||||
|
|
||||
|
## 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` |
||||
|
|
||||
|
### 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 |
||||
|
|
||||
|
## 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 |
||||
|
|
||||
|
## 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 |
||||
|
|
||||
|
**ADR must include**: motivation, alternatives, risks, validation plan, rollback, |
||||
|
doc diffs. |
||||
|
|
||||
|
## 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? |
||||
|
|
||||
|
--- |
||||
|
|
||||
|
**Status**: Active build system protection |
||||
|
**Priority**: Critical |
||||
|
**Estimated Effort**: Ongoing vigilance |
||||
|
**Dependencies**: All build system components |
||||
|
**Stakeholders**: Development team, DevOps, Platform owners |
||||
|
**Next Review**: 2025-09-20 |
||||
Loading…
Reference in new issue