proagents 1.0.0

package/proagents/config-versioning/changelog.md

@@ -0,0 +1,300 @@
+# Configuration Changelog
+
+Track and document configuration changes over time.
+
+---
+
+## Changelog Overview
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    Config Changelog                          │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│  Every config change generates a changelog entry:          │
+│                                                             │
+│  ┌─────────────────────────────────────────────────────┐   │
+│  │ v1.5.1 - January 15, 2024                           │   │
+│  │                                                     │   │
+│  │ Changed:                                            │   │
+│  │ • checkpoints.before_deployment: false → true       │   │
+│  │                                                     │   │
+│  │ Added:                                              │   │
+│  │ • security.require_review: true                     │   │
+│  │ • security.scan_dependencies: true                  │   │
+│  │                                                     │   │
+│  │ Reason: Stricter security requirements              │   │
+│  │ Author: alice@company.com                           │   │
+│  └─────────────────────────────────────────────────────┘   │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Changelog Configuration
+
+### Auto-Generation
+
+```yaml
+config_versioning:
+  changelog:
+    enabled: true
+
+    # Auto-generate on changes
+    auto_generate: true
+
+    # Output location
+    output:
+      file: ".proagents/config-history/changelog.md"
+      format: "markdown"  # markdown, json, yaml
+
+    # What to include
+    include:
+      - version
+      - timestamp
+      - author
+      - reason
+      - changes
+      - files_affected
+```
+
+### Changelog Format
+
+```yaml
+config_versioning:
+  changelog:
+    format:
+      # Markdown template
+      template: |
+        ## {{version}} - {{date}}
+
+        **Author:** {{author}}
+        **Reason:** {{reason}}
+
+        ### Changes
+        {{#each changes}}
+        - `{{this.path}}`: {{this.old}} → {{this.new}}
+        {{/each}}
+
+        ### Files Modified
+        {{#each files}}
+        - {{this}}
+        {{/each}}
+
+        ---
+```
+
+---
+
+## Viewing Changelog
+
+### Command Line
+
+```bash
+# View recent changes
+proagents config changelog
+
+# View specific version
+proagents config changelog --version v1.5.0
+
+# View changes between versions
+proagents config changelog --from v1.4.0 --to v1.5.0
+
+# Export changelog
+proagents config changelog --export changelog.md
+```
+
+### Changelog Output
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ Configuration Changelog                                     │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│ ## v1.5.1 - January 15, 2024 10:30                         │
+│                                                             │
+│ **Author:** alice@company.com                              │
+│ **Reason:** Added stricter security rules                  │
+│                                                             │
+│ ### Changes                                                 │
+│ - `checkpoints.before_deployment`: false → true            │
+│ - `security.require_review`: (new) true                    │
+│ - `security.scan_dependencies`: (new) true                 │
+│                                                             │
+│ ### Files Modified                                          │
+│ - proagents.config.yaml                                    │
+│ - rules/security-rules.yaml                                │
+│                                                             │
+│ ---                                                         │
+│                                                             │
+│ ## v1.5.0 - January 14, 2024 15:45                         │
+│                                                             │
+│ **Author:** bob@company.com                                │
+│ **Reason:** Configured test coverage targets               │
+│                                                             │
+│ ### Changes                                                 │
+│ - `testing.coverage.minimum`: 70 → 80                      │
+│ - `testing.coverage.fail_under`: (new) true                │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Change Categories
+
+### Categorize Changes
+
+```yaml
+config_versioning:
+  changelog:
+    categories:
+      added:
+        label: "Added"
+        description: "New configuration options"
+        emoji: "✨"
+
+      changed:
+        label: "Changed"
+        description: "Modified existing options"
+        emoji: "🔄"
+
+      removed:
+        label: "Removed"
+        description: "Removed configuration options"
+        emoji: "🗑️"
+
+      deprecated:
+        label: "Deprecated"
+        description: "Options marked for removal"
+        emoji: "⚠️"
+
+      security:
+        label: "Security"
+        description: "Security-related changes"
+        emoji: "🔒"
+```
+
+### Categorized Output
+
+```markdown
+## v1.5.1 - January 15, 2024
+
+### ✨ Added
+- `security.require_review`: Enable security review requirement
+- `security.scan_dependencies`: Enable dependency scanning
+
+### 🔄 Changed
+- `checkpoints.before_deployment`: Now required by default
+
+### 🔒 Security
+- Added mandatory security review for production deployments
+```
+
+---
+
+## Changelog Annotations
+
+### Add Context
+
+```yaml
+# When making changes, add context
+config_versioning:
+  annotations:
+    enabled: true
+
+    # Require reason for changes
+    require_reason: true
+
+    # Optional fields
+    optional:
+      - ticket_id
+      - related_pr
+      - documentation_link
+```
+
+### Annotated Entry
+
+```markdown
+## v1.5.1 - January 15, 2024
+
+**Author:** alice@company.com
+**Reason:** Stricter security requirements per SOC 2 audit
+**Ticket:** SEC-123
+**PR:** #456
+**Documentation:** https://docs.company.com/security-config
+
+### Changes
+...
+```
+
+---
+
+## Search and Filter
+
+### Search Changelog
+
+```bash
+# Search by keyword
+proagents config changelog --search "security"
+
+# Filter by author
+proagents config changelog --author "alice@company.com"
+
+# Filter by date range
+proagents config changelog --from "2024-01-01" --to "2024-01-31"
+
+# Filter by file
+proagents config changelog --file "rules/security-rules.yaml"
+```
+
+---
+
+## Integration
+
+### Slack Notifications
+
+```yaml
+config_versioning:
+  changelog:
+    notifications:
+      on_change:
+        channels: ["slack:#config-changes"]
+        template: |
+          *Config Update: {{version}}*
+
+          Author: {{author}}
+          Reason: {{reason}}
+
+          Changes: {{change_count}}
+          {{#each changes}}
+          • `{{this.path}}`: {{this.summary}}
+          {{/each}}
+```
+
+### Git Integration
+
+```yaml
+config_versioning:
+  changelog:
+    git:
+      # Commit changelog updates
+      auto_commit: true
+      commit_message: "chore: update config changelog for {{version}}"
+
+      # Tag releases
+      tag_versions: true
+      tag_prefix: "config-"
+```
+
+---
+
+## Best Practices
+
+1. **Always Add Reason**: Explain why changes were made
+2. **Link to Tickets**: Reference related issues/tickets
+3. **Review Regularly**: Check changelog for patterns
+4. **Categorize Changes**: Use consistent categories
+5. **Export for Audits**: Generate reports when needed
+6. **Notify Team**: Keep team informed of changes

package/proagents/config-versioning/rollback.md

@@ -0,0 +1,283 @@
+# Configuration Rollback
+
+Restore previous configuration versions.
+
+---
+
+## Rollback Overview
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    Config Rollback Flow                      │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│  Current Config (v1.5.1)                                   │
+│       │                                                     │
+│       │  Issue detected                                     │
+│       ▼                                                     │
+│  ┌─────────────┐                                           │
+│  │   Rollback  │                                           │
+│  │   Command   │                                           │
+│  └──────┬──────┘                                           │
+│         │                                                   │
+│    ┌────┴────┐                                             │
+│    ▼         ▼                                             │
+│  [Previous] [Specific]                                      │
+│  (v1.5.0)   (v1.4.0)                                       │
+│    │         │                                             │
+│    └────┬────┘                                             │
+│         ▼                                                   │
+│  ┌─────────────┐                                           │
+│  │  Validate   │                                           │
+│  └──────┬──────┘                                           │
+│         │                                                   │
+│         ▼                                                   │
+│  ┌─────────────┐                                           │
+│  │   Apply     │                                           │
+│  └──────┬──────┘                                           │
+│         │                                                   │
+│         ▼                                                   │
+│  Config restored to v1.5.0                                 │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Rollback Commands
+
+### Quick Rollback
+
+```bash
+# Rollback to previous version
+proagents config rollback
+
+# Rollback to specific version
+proagents config rollback --to v1.5.0
+
+# Rollback specific file
+proagents config rollback --file rules/security-rules.yaml
+
+# Preview rollback (dry run)
+proagents config rollback --dry-run
+```
+
+### Rollback Output
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ Configuration Rollback                                      │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│ Rolling back: v1.5.1 → v1.5.0                              │
+│                                                             │
+│ Files to restore:                                           │
+│ ├── proagents.config.yaml                                  │
+│ └── rules/security-rules.yaml                              │
+│                                                             │
+│ Changes to revert:                                          │
+│ ├── checkpoints.before_deployment: true → false            │
+│ └── security.require_review: true → false                  │
+│                                                             │
+│ [Confirm Rollback]  [Cancel]                               │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Rollback Configuration
+
+### Rollback Settings
+
+```yaml
+config_versioning:
+  rollback:
+    # Require confirmation
+    require_confirmation: true
+
+    # Create backup before rollback
+    backup_current: true
+
+    # Validate after rollback
+    validate_after: true
+
+    # Notify on rollback
+    notify:
+      enabled: true
+      channels: ["slack:#config-changes"]
+
+    # Audit
+    audit:
+      enabled: true
+      require_reason: true
+```
+
+### Rollback Permissions
+
+```yaml
+config_versioning:
+  rollback:
+    permissions:
+      # Who can rollback
+      allowed_users:
+        - "@team/tech-leads"
+        - "@team/devops"
+
+      # Require approval for old versions
+      approval_required:
+        versions_back: 5  # Need approval for > 5 versions back
+
+      # Emergency rollback
+      emergency:
+        enabled: true
+        bypass_approval: true
+        notify: ["@team/managers"]
+```
+
+---
+
+## Partial Rollback
+
+### Rollback Specific Files
+
+```bash
+# Rollback single file
+proagents config rollback --file proagents.config.yaml --to v1.5.0
+
+# Rollback multiple files
+proagents config rollback --files "rules/*.yaml" --to v1.5.0
+
+# Rollback specific setting
+proagents config rollback --setting checkpoints.before_deployment
+```
+
+### Selective Restore
+
+```yaml
+# Restore specific sections
+proagents config restore --section checkpoints --from v1.5.0
+
+# Restore keeping current values
+proagents config restore --merge --from v1.5.0
+```
+
+---
+
+## Rollback Validation
+
+### Pre-Rollback Checks
+
+```yaml
+config_versioning:
+  rollback:
+    validation:
+      # Check before rollback
+      pre_checks:
+        - "syntax_valid"
+        - "schema_valid"
+        - "no_breaking_changes"
+
+      # Block if checks fail
+      block_on_failure: true
+```
+
+### Post-Rollback Verification
+
+```bash
+# After rollback, verify
+proagents config validate
+
+# Output:
+┌─────────────────────────────────────────────────────────────┐
+│ Post-Rollback Validation                                    │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│ ✅ Syntax: Valid YAML                                      │
+│ ✅ Schema: Matches expected structure                      │
+│ ✅ Rules: All rules valid                                  │
+│ ✅ References: All files exist                             │
+│                                                             │
+│ Rollback successful. Configuration is valid.               │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Rollback History
+
+### View Rollback Log
+
+```bash
+proagents config rollback-history
+
+# Output:
+┌─────────────────────────────────────────────────────────────┐
+│ Rollback History                                            │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│ Jan 15, 2024 10:30                                         │
+│ ├── From: v1.5.1 → To: v1.5.0                             │
+│ ├── User: alice@company.com                                │
+│ ├── Reason: Security rule caused build failures           │
+│ └── Files: rules/security-rules.yaml                       │
+│                                                             │
+│ Jan 10, 2024 15:45                                         │
+│ ├── From: v1.4.2 → To: v1.4.0                             │
+│ ├── User: bob@company.com                                  │
+│ ├── Reason: Checkpoint changes broke CI                    │
+│ └── Files: proagents.config.yaml                           │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Emergency Rollback
+
+### Quick Emergency Restore
+
+```bash
+# Emergency rollback (skip confirmations)
+proagents config rollback --emergency --to v1.5.0
+
+# Requires emergency permissions
+# Automatically notifies team
+# Creates detailed audit log
+```
+
+### Emergency Configuration
+
+```yaml
+config_versioning:
+  rollback:
+    emergency:
+      enabled: true
+
+      # Skip normal approvals
+      bypass_approval: true
+
+      # Still require
+      require_reason: true
+      require_audit: true
+
+      # Notify immediately
+      notify:
+        - "slack:#incidents"
+        - "pagerduty:config-oncall"
+
+      # Auto-create incident
+      create_incident: true
+```
+
+---
+
+## Best Practices
+
+1. **Test in Staging**: Rollback in staging first if possible
+2. **Document Reason**: Always explain why rollback is needed
+3. **Verify After**: Run validation after rollback
+4. **Notify Team**: Ensure team knows about config changes
+5. **Keep History**: Maintain rollback history for auditing
+6. **Plan Forward**: After rollback, plan proper fix