feat(ci): implement two-tier CI with develop/main branching strategy …

.github/workflows/ci.yml

@@ -1,27 +1,30 @@
-# CI Pipeline for CCH (Claude Code Hooks)
+# Fast CI Pipeline for CCH (Claude Code Hooks)
 #
-# This workflow runs on every push and PR to ensure code quality:
+# This workflow provides rapid feedback during daily development:
 # - Formatting check (rustfmt)
 # - Linting (clippy)
 # - Unit tests
-# - Integration tests (IQ/OQ/PQ)
-# - Code coverage (cargo-llvm-cov)
-# - Upload test evidence as artifacts
+# - Linux IQ smoke test
+# - Code coverage (informational)
+#
+# Target time: ~2-3 minutes
+#
+# For full IQ/OQ/PQ validation, see validation.yml (runs on PRs to main)
 
-name: CI
+name: Fast CI
 
 on:
   push:
-    branches: [main, "feature/**", "001-*"]
+    branches: [develop, "feature/**", "fix/**", "docs/**"]
   pull_request:
-    branches: [main]
+    branches: [develop]
 
 env:
   CARGO_TERM_COLOR: always
   RUST_BACKTRACE: 1
 
 jobs:
-  # Format check
+  # Format check (~30s)
   fmt:
     name: Format
     runs-on: ubuntu-latest
@@ -33,7 +36,7 @@ jobs:
       - name: Check formatting
         run: cargo fmt --all --check
 
-  # Linting with clippy
+  # Linting with clippy (~1 min)
   clippy:
     name: Clippy
     runs-on: ubuntu-latest
@@ -46,7 +49,7 @@ jobs:
       - name: Run clippy
         run: cargo clippy --all-targets --all-features -- -D warnings
 
-  # Unit tests
+  # Unit tests (~1 min)
   test-unit:
     name: Unit Tests
     runs-on: ubuntu-latest
@@ -57,32 +60,18 @@ jobs:
       - name: Run unit tests
         run: cargo test --lib
 
-  # Integration tests (IQ/OQ/PQ)
-  test-integration:
-    name: Integration Tests (${{ matrix.test }})
+  # Linux IQ smoke test (~1 min)
+  test-iq-smoke:
+    name: IQ Smoke Test (Linux)
     runs-on: ubuntu-latest
-    strategy:
-      matrix:
-        test: [iq_installation, oq_us1_blocking, oq_us2_injection, oq_us3_validators, oq_us4_permissions, oq_us5_logging, pq_performance]
     steps:
       - uses: actions/checkout@v4
       - uses: dtolnay/rust-toolchain@stable
       - uses: Swatinem/rust-cache@v2
-      - name: Set up Python (for validators)
-        uses: actions/setup-python@v5
-        with:
-          python-version: '3.11'
-      - name: Run integration test
-        run: cargo test --test ${{ matrix.test }}
-      - name: Upload test evidence
-        if: always()
-        uses: actions/upload-artifact@v4
-        with:
-          name: test-evidence-${{ matrix.test }}
-          path: cch_cli/target/test-evidence/
-          if-no-files-found: ignore
+      - name: Run IQ tests
+        run: cargo test iq_ -- --nocapture
 
-  # Code coverage
+  # Code coverage (informational, ~2 min)
   coverage:
     name: Code Coverage
     runs-on: ubuntu-latest
@@ -113,48 +102,20 @@ jobs:
           name: coverage-report
           path: lcov.info
 
-  # Build release binary
-  build:
-    name: Build Release
-    runs-on: ${{ matrix.os }}
-    strategy:
-      matrix:
-        include:
-          - os: ubuntu-latest
-            target: x86_64-unknown-linux-gnu
-          - os: macos-latest
-            target: x86_64-apple-darwin
-          - os: macos-latest
-            target: aarch64-apple-darwin
-    steps:
-      - uses: actions/checkout@v4
-      - uses: dtolnay/rust-toolchain@stable
-        with:
-          targets: ${{ matrix.target }}
-      - uses: Swatinem/rust-cache@v2
-      - name: Build release
-        run: cargo build --release --target ${{ matrix.target }}
-      - name: Upload binary
-        uses: actions/upload-artifact@v4
-        with:
-          name: cch-${{ matrix.target }}
-          path: target/${{ matrix.target }}/release/cch
-
   # Summary job that requires all others to pass
   ci-success:
-    name: CI Success
+    name: Fast CI Success
     runs-on: ubuntu-latest
-    needs: [fmt, clippy, test-unit, test-integration, coverage, build]
+    needs: [fmt, clippy, test-unit, test-iq-smoke]
     if: always()
     steps:
       - name: Check all jobs passed
         run: |
           if [[ "${{ needs.fmt.result }}" != "success" ]] || \
              [[ "${{ needs.clippy.result }}" != "success" ]] || \
              [[ "${{ needs.test-unit.result }}" != "success" ]] || \
-             [[ "${{ needs.test-integration.result }}" != "success" ]] || \
-             [[ "${{ needs.build.result }}" != "success" ]]; then
-            echo "One or more jobs failed"
+             [[ "${{ needs.test-iq-smoke.result }}" != "success" ]]; then
+            echo "One or more Fast CI jobs failed"
             exit 1
           fi
-          echo "All CI jobs passed successfully"
+          echo "All Fast CI jobs passed successfully"

.github/workflows/iq-validation.yml

@@ -3,6 +3,13 @@
 # Validates CCH installation and basic functionality across all supported platforms.
 # This is the first phase of IQ/OQ/PQ validation framework.
 #
+# NOTE: This workflow is MANUAL-ONLY. It does not run automatically.
+# Use this for formal validation runs and compliance audits.
+#
+# For automatic validation, use:
+# - Fast CI (ci.yml) - runs on PRs to develop
+# - Full Validation (validation.yml) - runs on PRs to main
+#
 # Platforms tested:
 # - macOS ARM64 (M1/M2/M3)
 # - macOS Intel (x86_64)
@@ -11,19 +18,16 @@
 #
 # Reference: docs/IQ_OQ_PQ_IntegrationTesting.md
 
-name: IQ Validation
+name: IQ Validation (Manual)
 
 on:
-  push:
-    branches: [main]
-  pull_request:
-    branches: [main]
+  # Manual trigger only - for formal validation runs
   workflow_dispatch:
     inputs:
       evidence_collection:
         description: 'Collect formal evidence for validation report'
         type: boolean
-        default: false
+        default: true
 
 env:
   CARGO_TERM_COLOR: always

.github/workflows/validation.yml

@@ -1,22 +1,28 @@
-# Combined IQ/OQ/PQ Validation Workflow
+# Full IQ/OQ/PQ Validation Workflow
 #
 # Orchestrates the full validation sequence:
 # 1. IQ (Installation Qualification) - Cross-platform installation verification
 # 2. OQ (Operational Qualification) - Functional testing of all features
 # 3. PQ (Performance Qualification) - Performance benchmarks and limits
 #
-# This workflow serves as the release gate - all phases must pass.
+# This workflow serves as the RELEASE GATE - all phases must pass.
+# Only runs on PRs to main, release tags, or manual dispatch.
+#
+# For daily development, use Fast CI (ci.yml) which runs on develop.
 #
 # Reference: docs/IQ_OQ_PQ_IntegrationTesting.md
+# Reference: docs/devops/CI_TIERS.md
 
-name: IQ/OQ/PQ Validation
+name: Full Validation
 
 on:
-  push:
-    branches: [main]
-    tags: ['v*']
+  # Only PRs targeting main trigger full validation
   pull_request:
     branches: [main]
+  # Release tags trigger full validation
+  push:
+    tags: ['v*']
+  # Manual trigger for formal validation runs
   workflow_dispatch:
     inputs:
       skip_iq:
@@ -62,7 +68,9 @@ jobs:
   iq-macos-intel:
     name: IQ - macOS Intel
     if: ${{ github.event.inputs.skip_iq != 'true' }}
-    runs-on: macos-13
+    # Note: macos-13 was retired Jan 2026 (see actions/runner-images#13046)
+    # Using macos-15-intel - last supported x86_64 image (until Aug 2027)
+    runs-on: macos-15-intel
     steps:
       - uses: actions/checkout@v4
       - uses: dtolnay/rust-toolchain@stable

.speckit/constitution.md

@@ -26,26 +26,63 @@ This positions CCH as comparable to:
 
 ## Git Workflow Principles
 
+### Branching Model
+
+```
+main (protected)          <- Production-ready, fully validated
+  ^
+  |
+develop (default)         <- Integration branch, fast CI
+  ^
+  |
+feature/* | fix/*         <- Short-lived working branches
+```
+
+| Branch | Purpose | CI Level | Protection |
+|--------|---------|----------|------------|
+| `main` | Production-ready releases | Full Validation | Protected, requires IQ/OQ/PQ |
+| `develop` | Integration branch (default) | Fast CI | Protected, requires Fast CI |
+| `feature/*` | Active development | Fast CI | None |
+| `fix/*` | Bug fixes | Fast CI | None |
+| `release/*` | Release candidates | Full Validation | None |
+| `hotfix/*` | Emergency fixes to main | Full Validation | None |
+
 ### Feature Branch Requirement
-- **NEVER commit directly to `main`** - This is a non-negotiable principle
+- **NEVER commit directly to `main` or `develop`** - This is a non-negotiable principle
 - All feature work MUST be done in a dedicated feature branch
-- Pull Requests are REQUIRED for all changes to `main`
+- Pull Requests are REQUIRED for all changes
 - Code review via PR ensures quality and knowledge sharing
 
 ### Branch Naming Convention
 - Features: `feature/<feature-name>` (e.g., `feature/add-debug-command`)
 - Bugfixes: `fix/<bug-description>` (e.g., `fix/config-parsing-error`)
 - Documentation: `docs/<doc-topic>` (e.g., `docs/update-readme`)
 - Releases: `release/<version>` (e.g., `release/v1.0.0`)
+- Hotfixes: `hotfix/<issue>` (e.g., `hotfix/critical-security-fix`)
 
-### PR Workflow
-1. Create feature branch from `main`
+### Standard PR Workflow (Daily Development)
+1. Create feature branch from `develop`
 2. Implement changes with atomic, conventional commits
-3. **Run all pre-commit checks locally** (see below)
-4. Push branch and create Pull Request
-5. Request review and address feedback
-6. Merge via GitHub (squash or merge commit as appropriate)
-7. Delete feature branch after merge
+3. **Run pre-commit checks locally** (see below)
+4. Push branch and create Pull Request **targeting `develop`**
+5. Fast CI runs (~2-3 minutes)
+6. Request review and address feedback
+7. Merge to `develop` via GitHub
+8. Delete feature branch after merge
+
+### Release Workflow (Production Deployment)
+1. Create PR from `develop` to `main`
+2. Full IQ/OQ/PQ validation runs (~10-15 minutes)
+3. All 4 platforms tested (macOS ARM64, Intel, Linux, Windows)
+4. Evidence artifacts collected
+5. Merge to `main` only after all validation passes
+6. Tag release from `main`
+
+### Hotfix Workflow (Emergency Fixes)
+1. Create `hotfix/*` branch from `main`
+2. Implement fix with minimal changes
+3. Create PR to `main` (triggers full validation)
+4. After merge to `main`, backport to `develop`
 
 ### Pre-Commit Checks (MANDATORY)
 
@@ -73,7 +110,69 @@ cd cch_cli && cargo fmt && cargo clippy --all-targets --all-features -- -D warni
 ```
 
 ### Rationale
-Direct commits to `main` bypass code review, risk introducing bugs, and make it difficult to revert changes. Feature branches enable parallel development, clean history, and proper CI/CD validation before merge.
+- **Two-branch model** enables fast iteration on `develop` while maintaining production stability on `main`
+- **Fast CI on develop** provides rapid feedback (~2-3 min) during active development
+- **Full validation on main** ensures releases are thoroughly tested across all platforms
+- Direct commits bypass code review, risk introducing bugs, and make it difficult to revert changes
+
+---
+
+## CI/CD Policy
+
+### CI Tiers
+
+| Tier | Trigger | Duration | What Runs |
+|------|---------|----------|-----------|
+| **Fast CI** | Push to `develop`, `feature/*`; PRs to `develop` | ~2-3 min | fmt, clippy, unit tests, Linux IQ smoke test |
+| **Full Validation** | PRs to `main`, release tags, manual dispatch | ~10-15 min | Fast CI + IQ (4 platforms) + OQ + PQ + evidence |
+
+### Fast CI (~2-3 minutes)
+**Purpose:** Rapid feedback during active development
+
+**Jobs:**
+- Format check (`cargo fmt --check`)
+- Linting (`cargo clippy`)
+- Unit tests (`cargo test --lib`)
+- Linux IQ smoke test (`cargo test iq_`)
+- Code coverage (report only, non-blocking)
+
+**When it runs:**
+- Every push to `develop` or `feature/*` branches
+- Every PR targeting `develop`
+
+### Full Validation (~10-15 minutes)
+**Purpose:** Release gate validation ensuring production readiness
+
+**Jobs:**
+- All Fast CI jobs
+- IQ on 4 platforms (macOS ARM64, macOS Intel, Linux, Windows)
+- Full OQ test suite (US1-US5)
+- PQ benchmarks (performance, memory)
+- Evidence collection and artifact upload
+
+**When it runs:**
+- PRs targeting `main`
+- Release tags (`v*`)
+- Manual workflow dispatch
+
+### Validation Gates
+
+| Event | Required Checks | Blocking |
+|-------|-----------------|----------|
+| PR to `develop` | Fast CI passes | Yes |
+| PR to `main` | Full IQ/OQ/PQ Validation passes | Yes |
+| Release tag | Full Validation already passed on `main` | Yes |
+
+### Evidence Collection
+Full validation automatically collects and uploads:
+- IQ evidence per platform
+- OQ test results
+- PQ benchmark data
+- Combined validation report
+
+Evidence is stored as GitHub Actions artifacts and can be downloaded for compliance audits.
+
+Reference: [CI Tiers Documentation](docs/devops/CI_TIERS.md)
 
 ---