CI/CD workflow guidelines and installation command

## Feature Request

Create comprehensive CI/CD workflow guidelines and implement a command to install standardized GitHub Actions workflows based on project patterns and best practices.

## Current State

**Existing CI/CD Infrastructure:**
- 59 GitHub workflows (31 CI + 28 release)
- Consistent naming: `ci-{module}.yaml`, `release-{module}.yaml`
- Reusable workflow patterns across modules
- Custom composite actions in `.github/actions/`
- Workflow templates exist but no formal guidelines
- Manual workflow creation and maintenance

**Pain Points:**
- No documentation of CI/CD patterns and best practices
- New modules require manual workflow creation
- Inconsistent workflow implementations across modules
- No easy way to update all workflows when patterns change
- Difficult to ensure workflows follow project standards
- Learning curve for contributors creating new workflows

## Proposed Solution

### Part 1: CI/CD Guidelines Documentation

Create comprehensive documentation covering:

#### 1. Workflow Architecture

**Document existing patterns:**
```
.github/
  ├─ actions/                    # Composite actions
  │  ├─ setup-go/
  │  ├─ setup-python/
  │  ├─ cache-dependencies/
  │  └─ upload-artifacts/
  │
  ├─ workflows/
  │  ├─ ci-{module}.yaml         # Per-module CI
  │  ├─ release-{module}.yaml    # Per-module release
  │  ├─ _reusable-build.yaml     # Reusable workflows
  │  ├─ _reusable-test.yaml
  │  └─ _reusable-scan.yaml
  │
  └─ workflow-templates/         # Templates for new workflows
     ├─ ci-go-module.yaml
     ├─ ci-python-module.yaml
     ├─ release-go-module.yaml
     └─ release-container.yaml
```

#### 2. Workflow Types

**CI Workflows (`ci-{module}.yaml`):**
- Trigger: Push to main, pull requests
- Steps: Build → Test → Lint → Scan
- Artifacts: Test results, scan reports, build artifacts
- Duration target: < 15 minutes
- Runs on: `ubuntu-latest`

**Release Workflows (`release-{module}.yaml`):**
- Trigger: Tag push matching module pattern
- Steps: Build → Test → Scan → Generate Evidence → Release
- Artifacts: Binaries, containers, evidence PDFs
- Release notes: Auto-generated from changelog
- GitHub release creation with assets

**Nightly Workflows:**
- Trigger: Scheduled (cron)
- Steps: Extended tests, dependency updates, security scans
- Purpose: Catch issues not found in CI

**Manual Workflows:**
- Trigger: `workflow_dispatch`
- Purpose: Ad-hoc operations, testing, deployments

#### 3. Workflow Patterns

**Standard CI Pattern:**
```yaml
name: CI - Module Name

on:
  push:
    branches: [main]
    paths:
      - 'module/source/paths/**'
      - '.github/workflows/ci-module.yaml'
  pull_request:
    paths:
      - 'module/source/paths/**'

jobs:
  build-test-scan:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        
      - name: Setup Environment
        uses: ./.github/actions/setup-go  # Composite action
        
      - name: Build
        run: r2r eac build module-name
        
      - name: Test
        run: r2r eac test module-name --suite unit integration
        
      - name: Lint
        run: r2r eac lint module-name
        
      - name: Scan
        run: r2r eac scan module-name
        
      - name: Upload Artifacts
        uses: actions/upload-artifact@v4
        with:
          name: module-name-${{ github.sha }}
          path: |
            out/build/module-name/
            out/test/module-name/
            out/scan/module-name/
```

**Standard Release Pattern:**
```yaml
name: Release - Module Name

on:
  push:
    tags:
      - 'module-name/v*'      # SemVer
      - 'module-name/2*'      # CalVer

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        
      - name: Extract Version
        run: r2r eac release-extract-version
        
      - name: Check Release Exists
        run: r2r eac release-check-exists module-name
        
      - name: Wait for Dependencies
        run: r2r eac release-await-deps module-name
        
      - name: Build
        run: r2r eac build module-name
        
      - name: Test
        run: r2r eac test module-name
        
      - name: Scan
        run: r2r eac scan module-name
        
      - name: Generate Evidence
        run: r2r eac update-evidence module-name
        
      - name: Build Evidence PDF
        run: r2r eac build mkdocs-pdf --book module-name-evidence
        
      - name: Create Release
        run: r2r eac release-this module-name
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
```

#### 4. Best Practices

**Security:**
- Minimal token permissions (principle of least privilege)
- Use `permissions:` block explicitly
- No secrets in logs
- OIDC authentication preferred over PATs
- Dependabot for action version updates

**Performance:**
- Use caching for dependencies
- Parallel jobs when possible
- Fail fast strategies
- Incremental builds (only changed modules)
- Matrix strategies for multi-platform builds

**Reliability:**
- Retry logic for flaky operations
- Timeout specifications
- Clear failure messages
- Artifact retention policies
- Health checks before proceeding

**Maintainability:**
- DRY: Use composite actions for repeated steps
- Reusable workflows for common patterns
- Clear naming conventions
- Inline documentation
- Version pinning for actions

#### 5. CD Model Integration

**12-Stage CD Model Mapping:**
```
Pre-commit  → Local: build, test (unit), lint
Commit      → CI: build, test (unit+integration), lint, scan
MR          → CI: full validation
Acceptance  → Deploy PLTE, test (@L3)
Production  → Deploy, smoke tests (@L4 @piv)
```

**Workflow triggers by stage:**
- Pre-commit: Git hooks (local)
- Commit: `push` to main
- MR: `pull_request`
- Acceptance: Manual `workflow_dispatch` or tag
- Production: Tag push with approval

### Part 2: Workflow Installation Command

#### Command Interface

```bash
# Install CI workflow for module
r2r eac pipeline install-workflow ci <module>

# Install release workflow for module
r2r eac pipeline install-workflow release <module>

# Install both CI and release
r2r eac pipeline install-workflow all <module>

# Install workflows for all modules
r2r eac pipeline install-workflow all --all-modules

# List available workflow templates
r2r eac pipeline list-workflow-templates

# Show workflow template details
r2r eac pipeline show-workflow-template ci-go-module

# Validate existing workflows
r2r eac pipeline validate-workflows

# Update existing workflows (apply template updates)
r2r eac pipeline update-workflows <module>

# Generate workflow from scratch (interactive)
r2r eac pipeline create-workflow
```

#### Workflow Templates

**Template Structure:**
```
templates/
  workflows/
    ci/
      go-library.yaml           # Go library CI
      go-cli.yaml              # Go CLI CI
      go-container.yaml        # Go container CI
      python-package.yaml      # Python package CI
      typescript-package.yaml  # TypeScript package CI
      
    release/
      go-library.yaml          # Go library release
      go-cli.yaml             # Go CLI with binaries
      go-container.yaml       # Container build + push
      python-package.yaml     # PyPI publish
      
    composite-actions/
      setup-go/action.yaml
      setup-python/action.yaml
      cache-deps/action.yaml
      upload-evidence/action.yaml
    
    reusable/
      build.yaml              # Reusable build workflow
      test.yaml               # Reusable test workflow
      scan.yaml               # Reusable scan workflow
```

**Template Variables:**
```yaml
# templates/workflows/ci/go-library.yaml
name: CI - {{module_name}}

on:
  push:
    branches: [main]
    paths:
      - '{{module_source_paths}}'
      - '.github/workflows/ci-{{module_moniker}}.yaml'
  pull_request:
    paths:
      - '{{module_source_paths}}'

jobs:
  build-test-scan:
    runs-on: {{runner_os}}
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        
      - name: Setup Go
        uses: actions/setup-go@v5
        with:
          go-version: '{{go_version}}'
          cache: true
          
      - name: Build
        run: r2r eac build {{module_moniker}}
        
      - name: Test
        run: r2r eac test {{module_moniker}} --suite unit integration
        
      - name: Lint
        run: r2r eac lint {{module_moniker}}
        
      - name: Scan
        run: r2r eac scan {{module_moniker}}
        
      - name: Upload Artifacts
        uses: actions/upload-artifact@v4
        with:
          name: {{module_moniker}}-${{ github.sha }}
          path: |
            out/build/{{module_moniker}}/
            out/test/{{module_moniker}}/
            out/scan/{{module_moniker}}/
          retention-days: {{artifact_retention_days}}
```

**Variable Sources:**
```yaml
# Variables populated from repository.yml
module_name: "EAC Core"
module_moniker: "eac-core"
module_type: "library"
module_source_paths: "go/eac/core/**"
go_version: ">=1.21"
runner_os: "ubuntu-latest"
artifact_retention_days: 30

# User-provided overrides
custom_build_command: "make build"
custom_test_command: "make test"
```

#### Installation Process

```
1. Template Selection
   ├─ Detect module type from repository.yml
   ├─ Select appropriate template
   │  - go-library, go-cli, go-container
   │  - python-package, typescript-package
   └─ Confirm with user (interactive mode)

2. Variable Population
   ├─ Read module configuration
   ├─ Extract: moniker, name, type, paths, language version
   ├─ Set defaults (runner OS, retention, etc.)
   └─ Prompt for custom values (if interactive)

3. Template Rendering
   ├─ Load template file
   ├─ Replace {{variables}}
   ├─ Validate YAML syntax
   └─ Preview rendered workflow (if interactive)

4. File Writing
   ├─ Determine output path
   │  - .github/workflows/ci-{module}.yaml
   │  - .github/workflows/release-{module}.yaml
   ├─ Check for existing file (backup or overwrite)
   └─ Write rendered workflow

5. Validation
   ├─ Validate workflow syntax
   ├─ Check path triggers match module paths
   ├─ Verify referenced actions exist
   └─ Report any issues

6. Update Module Config
   ├─ Update repository.yml with workflow paths
   │  files:
   │    workflows:
   │      ci: .github/workflows/ci-{module}.yaml
   │      release: .github/workflows/release-{module}.yaml
   └─ Commit changes (if requested)
```

#### Interactive Mode

```
┌─ Workflow Installation ───────────────────────────────────┐
│                                                           │
│  Module: eac-core                                        │
│  Type: library                                           │
│                                                           │
│  Select workflow type:                                   │
│    [1] CI workflow only                                  │
│    [2] Release workflow only                             │
│    [3] Both CI and release (recommended)                 │
│                                                           │
│  Choice [3]: _                                           │
│                                                           │
└───────────────────────────────────────────────────────────┘

┌─ Template Selection ──────────────────────────────────────┐
│                                                           │
│  Detected module type: Go library                        │
│  Recommended template: ci/go-library.yaml                │
│                                                           │
│  Select CI template:                                     │
│    [1] go-library.yaml (recommended)                     │
│    [2] go-cli.yaml                                       │
│    [3] go-container.yaml                                 │
│    [4] Custom path                                       │
│                                                           │
│  Choice [1]: _                                           │
│                                                           │
└───────────────────────────────────────────────────────────┘

┌─ Configuration ───────────────────────────────────────────┐
│                                                           │
│  Module: eac-core                                        │
│  Template: ci/go-library.yaml                            │
│                                                           │
│  Runner OS [ubuntu-latest]: _                            │
│  Go Version [1.21]: _                                    │
│  Test Suites [unit integration]: _                       │
│  Artifact Retention Days [30]: _                         │
│                                                           │
│  Custom build command (leave empty for default): _       │
│  Custom test command (leave empty for default): _        │
│                                                           │
└───────────────────────────────────────────────────────────┘

┌─ Preview ─────────────────────────────────────────────────┐
│                                                           │
│  Generated workflow: .github/workflows/ci-eac-core.yaml  │
│                                                           │
│  Triggers:                                               │
│    - push to main (paths: go/eac/core/**)               │
│    - pull_request (paths: go/eac/core/**)               │
│                                                           │
│  Jobs:                                                   │
│    build-test-scan:                                      │
│      - Checkout                                          │
│      - Setup Go 1.21                                     │
│      - Build (r2r eac build eac-core)                   │
│      - Test (r2r eac test eac-core --suite unit...)     │
│      - Lint (r2r eac lint eac-core)                     │
│      - Scan (r2r eac scan eac-core)                     │
│      - Upload Artifacts                                  │
│                                                           │
│  View full workflow? [y/N]: _                            │
│  Install this workflow? [Y/n]: _                         │
│                                                           │
└───────────────────────────────────────────────────────────┘
```

#### Validation Features

```bash
# Validate all workflows
r2r eac pipeline validate-workflows

# Check:
- YAML syntax
- Required fields present
- Path triggers match module paths
- Referenced actions exist
- Token permissions are minimal
- Secrets are not exposed
- Workflow follows project patterns
```

**Validation Output:**
```
┌✓ Workflow Validation ─────────────────────────────────────┐
│  Validated: 59 workflows (31 CI, 28 release)             │
│  Duration: 1.2s                                           │
└────────────────────────────────────────────────────────────┘

✓ ci-eac-core.yaml
  ✓ Valid YAML syntax
  ✓ Paths match module source files
  ✓ All actions exist
  ✓ Minimal permissions
  ✓ Follows project patterns

✗ ci-old-module.yaml
  ✗ Path trigger mismatch (expected: go/old/**, actual: src/**)
  ✗ Using outdated action: actions/checkout@v2 (update to v4)
  ⚠ No artifact upload step
  ⚠ Missing lint step

⚠ release-some-module.yaml
  ✓ Valid syntax
  ⚠ Artifact retention: 90 days (recommended: 30)
  ⚠ No evidence generation step
```

## Implementation Phases

### Phase 1: Documentation (3 weeks)

**Scope:**
- Document existing workflow patterns
- Create CI/CD guidelines
- Document composite actions
- Create workflow architecture diagrams
- Best practices guide

**Deliverables:**
- `docs/reference/eac/ci-cd/workflow-architecture.md`
- `docs/reference/eac/ci-cd/workflow-patterns.md`
- `docs/reference/eac/ci-cd/best-practices.md`
- `docs/how-to-guides/eac/ci-cd/create-workflows.md`

### Phase 2: Template System (2 weeks)

**Scope:**
- Create workflow templates for all module types
- Define template variable system
- Create composite action templates
- Document template structure

**Deliverables:**
- `templates/workflows/` directory structure
- Templates for Go, Python, TypeScript
- CI and release workflow templates
- Template documentation

### Phase 3: Installation Command (3 weeks)

**Scope:**
- Implement `pipeline install-workflow` command
- Template rendering engine
- Variable population from repository.yml
- File writing and backup
- Basic validation

**Deliverables:**
- Working installation command
- Non-interactive mode
- Template-to-file rendering
- Module config integration

### Phase 4: Interactive Mode (2 weeks)

**Scope:**
- Interactive prompts for workflow installation
- Template selection UI
- Configuration input
- Preview before installation
- Confirmation prompts

**Deliverables:**
- Interactive installation workflow
- User-friendly prompts
- Preview functionality
- Help text and guidance

### Phase 5: Validation & Update (2 weeks)

**Scope:**
- Workflow validation command
- Syntax checking
- Pattern compliance checking
- Workflow update/migration command
- Diff preview for updates

**Deliverables:**
- `pipeline validate-workflows` command
- `pipeline update-workflows` command
- Validation reporting
- Update preview and confirmation

### Phase 6: Advanced Features (2 weeks)

**Scope:**
- Multi-module workflow installation
- Custom template support
- Workflow generation wizard
- Template marketplace/registry
- Migration from old patterns

**Deliverables:**
- Batch installation
- Custom template loading
- Workflow wizard (step-by-step)
- Template sharing/reuse

## Documentation Structure

### New Documentation

```
docs/
  reference/
    eac/
      ci-cd/
        workflow-architecture.md      # Overall architecture
        workflow-patterns.md          # Standard patterns
        workflow-types.md             # CI, release, nightly, manual
        composite-actions.md          # Reusable actions
        reusable-workflows.md         # Reusable workflow patterns
        best-practices.md             # Security, performance, reliability
        cd-model-integration.md       # 12-stage CD model mapping
        
  how-to-guides/
    eac/
      ci-cd/
        create-ci-workflow.md         # Create new CI workflow
        create-release-workflow.md    # Create new release workflow
        customize-workflows.md        # Customize templates
        migrate-workflows.md          # Migrate old workflows
        troubleshoot-workflows.md     # Debug workflow issues
        
  tutorials/
    ci-cd-setup.md                    # Complete CI/CD setup tutorial
    workflow-customization.md         # Customize workflow tutorial
```

### Updated Documentation

- Quick start guide (include workflow installation)
- Module creation guide (include workflow setup)
- Extension development guide (include CI/CD)
- Release process documentation

## Configuration Schema

### Workflow Configuration (Optional)

```yaml
# .r2r/eac/workflows.yml (optional advanced config)
workflows:
  defaults:
    ci:
      runner: ubuntu-latest
      timeout: 15
      artifact_retention_days: 30
      test_suites: [unit, integration]
      
    release:
      runner: ubuntu-latest
      timeout: 30
      artifact_retention_days: 90
      generate_evidence: true
      attach_pdf: true
      
  modules:
    eac-core:
      ci:
        runner: ubuntu-latest
        custom_steps:
          - name: Custom validation
            run: make validate
            
    r2r-cli:
      release:
        platforms: [linux/amd64, linux/arm64, darwin/amd64, darwin/arm64, windows/amd64]
        attach_binaries: true
```

## Success Criteria

- [ ] Comprehensive CI/CD guidelines documented
- [ ] Workflow patterns documented with examples
- [ ] Best practices guide available
- [ ] Templates created for all module types (Go, Python, TypeScript)
- [ ] `pipeline install-workflow` command working
- [ ] Interactive workflow installation
- [ ] Workflow validation command
- [ ] Can install workflows for all 31 modules
- [ ] Generated workflows match existing patterns
- [ ] Documentation complete with tutorials
- [ ] Migration guide for existing workflows

## Open Questions

1. **Template Updates**: How to update all workflows when template patterns change?
2. **Custom Actions**: Should we extract common patterns into more composite actions?
3. **Versioning**: Version workflow templates separately from r2r-cli?
4. **Platform Support**: Support for other CI systems (GitLab CI, Bitbucket Pipelines)?
5. **Testing**: How to test generated workflows without pushing to GitHub?
6. **Secrets Management**: How to handle module-specific secrets in templates?
7. **Matrix Builds**: Template support for matrix strategies (multi-platform, multi-version)?

## Related Issues

- #98 - Test EAC commands in Docker (Docker-based workflow testing)
- #104 - Multi-language support (workflow templates for each language)
- #105 - Evidence PDF generation (evidence steps in release workflows)
- #106 - Auto-scan init (workflow detection during init)

## Impact

- **Scope**: Medium-Large - affects all modules, new documentation section
- **Effort**: ~3 months for full implementation (6 phases)
- **Benefit**: Standardized CI/CD, easier onboarding, consistent patterns
- **Risk**: Breaking existing workflows if migration not handled carefully

## Examples

### Example 1: Install CI Workflow for New Module

```bash
# Auto-detect and install
r2r eac pipeline install-workflow ci my-new-module

# Output:
✓ Detected module type: Go library
✓ Selected template: ci/go-library.yaml
✓ Generated: .github/workflows/ci-my-new-module.yaml
✓ Updated: .r2r/eac/repository.yml

Next steps:
  1. Review workflow: .github/workflows/ci-my-new-module.yaml
  2. Commit and push: git add . && git commit -m "Add CI workflow"
  3. Workflow will run on next push to main
```

### Example 2: Interactive Workflow Creation

```bash
r2r eac pipeline create-workflow

# Interactive prompts guide through:
# - Module selection
# - Workflow type (CI/release/both)
# - Template selection
# - Configuration (runner, versions, etc.)
# - Preview and confirmation
# - Installation
```

### Example 3: Validate All Workflows

```bash
r2r eac pipeline validate-workflows

# Output:
✓ 57/59 workflows valid
✗ 2 workflows need updates

Recommendations:
  - Update actions/checkout@v2 → v4 (12 workflows)
  - Add evidence generation step (5 release workflows)
  - Fix path triggers (2 workflows)
```

## Related Documentation

Current workflow-related commands:
```bash
r2r eac pipeline ci              # CI orchestration
r2r eac pipeline wait            # Wait for workflows
r2r eac pipeline status          # Check workflow status
r2r eac get-ci-workflows         # List CI workflows
```

New commands (this issue):
```bash
r2r eac pipeline install-workflow       # Install workflow
r2r eac pipeline validate-workflows     # Validate workflows
r2r eac pipeline update-workflows       # Update workflows
r2r eac pipeline list-workflow-templates # List templates
```

Uh oh!

CI/CD workflow guidelines and installation command #107

Description

Feature Request

Current State

Proposed Solution

Part 1: CI/CD Guidelines Documentation

1. Workflow Architecture

2. Workflow Types

3. Workflow Patterns

4. Best Practices

5. CD Model Integration

Part 2: Workflow Installation Command

Command Interface

Workflow Templates

Installation Process

Interactive Mode

Validation Features

Implementation Phases

Phase 1: Documentation (3 weeks)

Phase 2: Template System (2 weeks)

Phase 3: Installation Command (3 weeks)

Phase 4: Interactive Mode (2 weeks)

Phase 5: Validation & Update (2 weeks)

Phase 6: Advanced Features (2 weeks)

Documentation Structure

New Documentation

Updated Documentation

Configuration Schema

Workflow Configuration (Optional)

Success Criteria

Open Questions

Related Issues

Impact

Examples

Example 1: Install CI Workflow for New Module

Example 2: Interactive Workflow Creation

Example 3: Validate All Workflows

Related Documentation

Metadata

Metadata

Assignees

Labels

Type

Fields

Projects

Milestone

Relationships

Development

Issue actions