Update AI Instructions and Design Principles for git-flow model (refs #20)

- Add mandatory branch validation requirements for git-flow
- Update release checklist with branch-specific procedures
- Add git-flow release process requirements and sequencing
- Update release testing requirements for different branches
- Add git-flow release automation requirements with branch validation
- Add comprehensive Git-Flow Release Management principle to Design Principles
- Include git-flow workflow standards and validation requirements
- Document branch structure, release process validation, and automation integration
- Add examples and benefits of git-flow implementation
- Ensure all release procedures align with git-flow branching model

Author: fxstein

AI_INSTRUCTIONS.md

@@ -50,16 +50,23 @@ This document establishes the foundational architectural decisions and design pa
      - Use bullet points for all lists
      - Group firmware by model and type (Official vs Labs)
 
-2. **Check for Uncommitted Changes**
+2. **Branch Validation** (MANDATORY FOR GIT-FLOW)
+   - **Real Releases**: Must be performed from `main` branch only
+   - **Dry Runs**: Can be performed from `develop`, `release/*`, or `hotfix/*` branches
+   - **Release Preparation**: Summary file must be created/updated on the preparation branch (typically `release/*`)
+   - **Pre-Release Validation**: Successful dry run required on preparation branch before merging to `main`
+
+3. **Check for Uncommitted Changes**
    - Ensure `scripts/release/` directory is clean (no uncommitted changes)
    - Ensure `.github/workflows/` directory is clean (no uncommitted changes)
+   - Ensure summary file is committed and pushed to the preparation branch
    - Commit and push all changes before proceeding
 
-3. **Use Full Release Script**
+4. **Use Full Release Script**
    - Always use `scripts/release/full-release.zsh` for releases
    - Never run individual scripts unless specifically instructed
 
-4. **Output File Requirements** (CRITICAL)
+5. **Output File Requirements** (CRITICAL)
    - ALL transient output files MUST be placed in the `output/` directory
    - NEVER create test files, logs, or any output in the repo root
    - This includes release notes, test files, debug output, etc.
@@ -107,6 +114,14 @@ This document establishes the foundational architectural decisions and design pa
 - By default, all test runs should be performed as dry runs (using `--dry-run`), unless a real release is explicitly requested.
 - Do not run the bump-version, release, or monitor scripts individually unless specifically instructed.
 
+**Git-Flow Release Process Requirements:**
+- **Development Phase**: All development work happens on `develop` branch
+- **Release Preparation**: Create `release/*` branch from `develop` for release preparation
+- **Dry Run Validation**: Perform dry run on `release/*` branch to validate release process
+- **Merge to Main**: Only merge to `main` after successful dry run validation
+- **Real Release**: Perform real release only from `main` branch
+- **Hotfix Process**: Use `hotfix/*` branches for urgent fixes, following same validation process
+
 ## Issue Creation Automation
 
 - Whenever the user requests an issue to be created, always create it as a GitHub tracker issue.
@@ -118,6 +133,11 @@ This document establishes the foundational architectural decisions and design pa
 ## Release Testing
 
 - Always perform test runs for releases as dry runs by default (using the dry-run option), unless a real release is explicitly requested by the user.
+- **Git-Flow Testing Requirements:**
+  - **Development Testing**: Run tests on `develop` branch during development
+  - **Release Testing**: Perform dry run on `release/*` branch before merging to `main`
+  - **Production Testing**: Real releases only from `main` branch after successful dry run validation
+  - **Hotfix Testing**: Perform dry run on `hotfix/*` branch before merging to `main`
 
 ## Script Language Requirements
 
@@ -142,6 +162,15 @@ This document establishes the foundational architectural decisions and design pa
 - If a full release (without `--dry-run`) is requested and there are changes in `scripts/release/`, first commit and push those changes, then perform a dry run. Only proceed with the real release if the dry run completes successfully.
 - Whenever a release is requested (dry-run or real), always create or update a file in `docs/release` with a summary of major changes since the requested previous release. The filename must match the convention used by the release process: `docs/release/latest-major-changes-since-<BASE>.md` (where `<BASE>` is the previous version, no leading 'v'). This file must be created every time a release is requested, before the release process starts.
 
+**Git-Flow Release Automation Requirements:**
+- **Branch Validation**: Script must validate current branch before proceeding
+  - Real releases: Must be on `main` branch
+  - Dry runs: Can be on `develop`, `release/*`, or `hotfix/*` branches
+- **Release Preparation**: Summary file must be created/updated on preparation branch
+- **Pre-Release Validation**: Successful dry run required before real release
+- **Merge Requirements**: Real releases only after successful merge to `main`
+- **Hotfix Handling**: Support for urgent fixes via `hotfix/*` branches with same validation
+
 ## GitHub Issue Management
 - Whenever a new GitHub issue is created, immediately run `scripts/maintenance/generate-issues-markdown.zsh` to update the local Markdown issue list.
 - After generating the issue list, read the output file (`output/github_issues.md`) to ensure you are memorizing and referencing the latest issues in all future work and communication.

docs/architecture/DESIGN_PRINCIPLES.md

@@ -398,6 +398,95 @@ mountoptions=(--archive --import --clean --firmware)
 - If a dependency is not available via Homebrew, document the alternative installation method and rationale
 - Ensure CI/CD and local environments use the same dependency installation approach for consistency
 
+### 11. Git-Flow Release Management
+
+**Principle:** Implement and maintain a strict git-flow branching model for all releases, ensuring proper separation between development, release preparation, and production deployment.
+
+**Rationale:** Git-flow provides a structured approach to managing releases, hotfixes, and feature development. It ensures that production releases are always stable, that release preparation is properly validated, and that urgent fixes can be deployed without disrupting ongoing development.
+
+**Implementation Requirements:**
+- **Branch Structure**: Maintain strict adherence to git-flow branch naming and purpose
+  - `main`: Production-ready code only
+  - `develop`: Integration branch for development features
+  - `release/*`: Release preparation branches (e.g., `release/v01.02.00`)
+  - `hotfix/*`: Urgent production fixes (e.g., `hotfix/v01.02.01`)
+  - `feature/*`: Individual feature development (optional)
+
+- **Release Process Validation**:
+  - All releases must be prepared on `release/*` branches
+  - Dry runs must be performed on preparation branches before merging to `main`
+  - Real releases must only be executed from `main` branch
+  - Summary files must be created/updated on preparation branches
+  - Successful dry run validation required before merge to `main`
+
+- **Branch Validation in Scripts**:
+  - Release scripts must validate current branch before proceeding
+  - Real releases: Must be on `main` branch
+  - Dry runs: Can be on `develop`, `release/*`, or `hotfix/*` branches
+  - Clear error messages for invalid branch operations
+
+- **Release Automation Integration**:
+  - GitHub Actions workflows must respect git-flow branch structure
+  - Automatic triggers for dry runs on `develop` and `release/*` branches
+  - Real release workflows only triggered from `main` branch
+  - Proper artifact handling and workflow dependencies
+
+**Git-Flow Workflow Standards:**
+```zsh
+# Development workflow
+git checkout develop
+# ... develop features ...
+git checkout -b feature/new-feature
+# ... implement feature ...
+git checkout develop
+git merge feature/new-feature
+
+# Release preparation
+git checkout -b release/v01.02.00 develop
+# ... prepare release (update version, summary file, etc.) ...
+./scripts/release/full-release.zsh --dry-run
+# ... validate dry run results ...
+git checkout main
+git merge release/v01.02.00
+git tag v01.02.00
+./scripts/release/full-release.zsh  # Real release
+
+# Hotfix workflow
+git checkout -b hotfix/v01.02.01 main
+# ... implement urgent fix ...
+./scripts/release/full-release.zsh --dry-run
+git checkout main
+git merge hotfix/v01.02.01
+git tag v01.02.01
+./scripts/release/full-release.zsh  # Real release
+```
+
+**Validation Requirements:**
+- All release scripts must include branch validation
+- Pre-commit hooks should validate branch naming conventions
+- CI/CD pipelines must respect git-flow branch purposes
+- Release automation must prevent invalid branch operations
+
+**Documentation Requirements:**
+- All git-flow procedures must be documented in project documentation
+- Release process must include branch-specific instructions
+- Hotfix procedures must be clearly documented
+- Branch naming conventions must be standardized
+
+**Benefits:**
+- **Stable Production**: `main` branch always contains production-ready code
+- **Controlled Releases**: Release preparation happens in isolated branches
+- **Emergency Fixes**: Hotfixes can be deployed without disrupting development
+- **Clear History**: Git history clearly shows release preparation and deployment
+- **Automated Validation**: CI/CD ensures proper branch usage and validation
+
+**Examples in GoProX:**
+- Release automation workflow validates branch before proceeding
+- Dry runs performed on `release/*` branches before merge to `main`
+- Summary files created on preparation branches and validated during dry runs
+- Real releases only executed from `main` after successful validation
+- Hotfix branches follow same validation process as release branches
+
 ## Decision Recording Process
 
 When making significant design or architectural decisions: