@jaguilar87/gaia-ops 3.14.0 → 4.0.0

package/CHANGELOG.md

@@ -5,6 +5,79 @@ All notable changes to the CLAUDE.md orchestrator instructions are documented in
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [4.0.0] - 2026-03-03
+
+### Breaking: Contracts as Single Source of Truth
+
+Contracts now fully control what context each agent receives. Removed the progressive disclosure layer that was silently overriding contract definitions, and cleaned up ~400 lines of dead code from context_provider.py.
+
+#### Changed
+- **context_provider.py**: Contracts are the single source of truth -- removed progressive disclosure filtering that overrode contract-defined sections
+- **context_provider.py**: Simplified output payload -- removed `enrichment` and `progressive_disclosure` keys from response
+- **contracts/terraform-architect.json**: Now reads `cluster_details` and `application_services` sections
+- **contracts/gitops-operator.json**: Now reads `gcp_services` section (GCP overlay)
+- **pre_tool_use.py**: Updated log message to show sections count and rules count
+- **templates/CLAUDE.template.md**: Synced agent routing descriptions with CLAUDE.md
+
+#### Fixed
+- **context_provider.py `get_contracts_dir()`**: Path traversal went up 2 levels instead of 3, producing wrong directory -- masked by legacy fallback that silently compensated
+
+#### Removed
+- **context_provider.py**: ~400 lines of dead code:
+  - Progressive disclosure engine (section filtering, phase-based visibility)
+  - `LEGACY_AGENT_CONTRACTS` dictionary (hardcoded fallback contracts)
+  - Semantic enrichment pipeline
+  - `validate_project_paths()` function
+  - Path resolution utility functions
+
+#### Tests
+- **tests/tools/test_context_provider.py**: Complete rewrite -- 8 tests covering all 6 agents, payload structure, and invalid agent handling
+
+## [3.15.1] - 2026-02-24
+
+### Fix: Cross-Layer Consistency & Dead Code Cleanup
+
+Comprehensive audit of skills, hooks, and security modules. Fixed inconsistencies between layers that caused silent failures (tests pass but system broken).
+
+#### Fixed
+- **bash_validator**: Check blocked commands BEFORE safe commands (defense-in-depth order was inverted)
+- **tiers.py**: Split `VALIDATION_PATTERNS` into `T1_PATTERNS` (validate, lint, fmt, check) and `T2_PATTERNS` (plan, template, diff) — aligns with security-tiers skill
+- **tiers.py**: Removed `terraform plan` from `ULTRA_COMMON_T0_COMMANDS` fast-path (was T0, should be T2)
+- **safe_commands.py**: Removed `terraform plan`/`terragrunt plan` from `ALWAYS_SAFE_MULTIWORD` (simulation, not read-only)
+- **safe_commands.py**: Removed `python3`, `python` from `always_safe` (can execute arbitrary code)
+- **safe_commands.py**: Removed `tar`, `gzip`, `gunzip`, `zip`, `unzip` from `always_safe` (modify filesystem)
+- **task_validator.py**: Removed legacy `APPROVAL_INDICATORS` (`'validation["approved"] == True'`, `"Phase 5: Realization"`)
+- **task_validator.py**: Added `speckit-planner` to `META_AGENTS`
+- **pre_tool_use.py**: Resume regex `{6,7}` → `{5,}` to accept real Claude Code agent IDs
+- **pre_tool_use.py**: Session events now inject BEFORE `# User Task` marker (was after)
+- **post_tool_use.py**: Added `fcntl.flock` to prevent race conditions on `context.json`
+- **post_tool_use.py**: Guard empty timestamps in retention filter
+- **subagent_stop.py**: Fixed indentation bug in consecutive failure detection
+- **subagent_stop.py**: Use `deque(f, maxlen=7)` instead of `f.readlines()` for metrics.jsonl
+- **settings.json**: Moved 7 T3 commands from `allow` → `ask`: kubectl exec/label/annotate/uncordon, helm rollback, flux suspend/resume
+- **settings.json**: Added `flux create` to `ask` list (was unprotected)
+- **agent-protocol skill**: Removed `CURRENT_PHASE` from AGENT_STATUS (redundant with `PLAN_STATUS`)
+- **agent-protocol skill**: `PLANNING` state now explicitly emitted in Phase 2
+- **execution skill**: Scope clarified as T3-only (was accidentally broadened to T2)
+- All 3 hooks: Removed `logging.StreamHandler()` (was sending noise to stderr)
+
+#### Removed
+- **`config_loader.py`** — Dead code, never imported by any module
+- **`discovery_classifier.py`** — Deprecated, replaced by context_writer.py (609 lines)
+- **`exhaustion_detector.py`** — Never worked (wrong glob pattern, wrong file format parsing, 200K thresholds obsolete with 1M context)
+- **`detect_speckit_milestone()`** in event_detector.py — Dead code (post_hook only runs for Bash, not Skill)
+- **`SPECKIT_MILESTONE`** enum value from EventType
+- **`test_config_loader.py`** — Tests for deleted module
+- **`test_discovery_classifier.py`** — Tests for deleted module
+- Slow execution detection in subagent_stop.py (duration_ms always None)
+
+#### Added
+- **`test_cross_layer_consistency.py`** — 24 tests validating consistency between settings.json ↔ safe_commands ↔ blocked_commands ↔ tiers ↔ skills ↔ task_validator
+
+#### Metrics
+- Dead code removed: ~1,500 lines (config_loader + discovery_classifier + exhaustion_detector + dead test files)
+- All 890 tests pass, 0 failures
+
 ## [3.12.0] - 2026-02-17
 
 ### Refactor: Principle-First Skills & Agent Deduplication

package/INSTALL.md

@@ -0,0 +1,451 @@
+# Gaia-Ops Installation Guide
+
+This guide will help you install and configure Gaia-Ops in your project. The process is automatic and takes less than 5 minutes.
+
+## 🎯 What is Gaia-Ops?
+
+Gaia-Ops is a system of specialized AI agents that automate DevOps tasks. Think of it as having a team of experts (Terraform, Kubernetes, GCP, AWS) working together, coordinated by an intelligent orchestrator.
+
+---
+
+## 🚀 Quick Installation (Recommended)
+
+### Option 1: Interactive Installation
+
+The easiest way - the installer will guide you step by step:
+
+```bash
+npx gaia-init
+```
+
+It will ask questions like:
+- Where are your GitOps files?
+- Where is your Terraform code?
+- What is your GCP project?
+
+### Option 2: Non-Interactive Installation
+
+For CI/CD scripts or if you already know the values:
+
+```bash
+npx gaia-init --non-interactive \
+  --gitops ./gitops \
+  --terraform ./terraform \
+  --app-services ./app-services \
+  --project-id my-gcp-project \
+  --cluster my-gke-cluster
+```
+
+---
+
+## 🔄 How Installation Works
+
+### Installation Flow
+
+```
+User runs: npx gaia-init
+        ↓
+[Detector] scans your project
+        ↓
+   Finds automatically:
+   - GitOps directory
+   - Terraform directory
+   - Apps directory
+        ↓
+[Installer] asks for missing data:
+   - GCP Project ID
+   - Region
+   - Cluster name
+        ↓
+[Installer] checks Claude Code
+        ↓
+    Already installed?
+    ┌────┴────┐
+    ↓         ↓
+  YES        NO
+    ↓         ↓
+  Use     Install
+ existing    new
+    ↓         ↓
+    └────┬────┘
+         ↓
+Creates .claude/ structure
+         ↓
+Creates symlinks to gaia-ops:
+  .claude/agents → node_modules/.../agents
+  .claude/tools → node_modules/.../tools
+  .claude/hooks → node_modules/.../hooks
+  .claude/commands → node_modules/.../commands
+  .claude/config → node_modules/.../config
+  .claude/skills → node_modules/.../skills
+  .claude/speckit → node_modules/.../speckit
+  .claude/templates → node_modules/.../templates
+         ↓
+Generates config files:
+  - CLAUDE.md (orchestrator)
+  - project-context.json
+  - settings.json
+         ↓
+Validates installation:
+  ✅ Symlinks correct
+  ✅ Claude Code available
+  ✅ Valid configuration
+         ↓
+Ready! You can use: claude-code
+```
+
+### Real Installation Example
+
+```
+Example: Installation in project with GitOps and Terraform
+
+1. User: npx gaia-init
+   ↓
+2. Detector finds:
+   ✅ ./gitops (52 YAML files detected)
+   ✅ ./terraform (15 .tf files detected)
+   ❌ ./app-services (not found)
+   ↓
+3. Installer asks:
+   ? GCP Project ID: → aaxis-rnd-general-project
+   ? Primary region: → us-central1
+   ? Cluster name: → tcm-gke-non-prod
+   ↓
+4. Checks Claude Code:
+   ✅ Claude Code already installed at /usr/local/bin/claude
+   ⏭️  Skipping reinstall
+   ↓
+5. Creates structure:
+   ✅ .claude/ created
+   ✅ 6 symlinks created
+   ✅ CLAUDE.md generated (196 lines)
+   ✅ project-context.json created
+   ↓
+6. Result:
+   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+   ✅ Gaia-Ops installed successfully!
+   
+   📚 Documentation available:
+   - .claude/agents/README.md
+   - .claude/config/README.md
+   - .claude/commands/README.md
+   
+   🚀 Next steps:
+   1. Run: claude-code
+   2. Ask: "Show me GKE clusters"
+   3. Or use: /gaia to explore the system
+```
+
+---
+
+## ⚙️ Installation Options
+
+### Environment Variables
+
+Configure before installing to avoid questions:
+
+```bash
+# Configure paths
+export CLAUDE_GITOPS_DIR="./gitops"
+export CLAUDE_TERRAFORM_DIR="./terraform"
+export CLAUDE_APP_SERVICES_DIR="./app-services"
+
+# Configure project
+export CLAUDE_PROJECT_ID="my-gcp-project"
+export CLAUDE_REGION="us-central1"
+export CLAUDE_CLUSTER_NAME="my-gke-cluster"
+
+# Install without questions
+npx gaia-init --non-interactive
+```
+
+### Complete CLI Options
+
+```
+gaia-init [options]
+
+Options:
+  --non-interactive          Skip prompts, use provided values or defaults
+  --gitops <path>           GitOps directory path
+  --terraform <path>        Terraform directory path
+  --app-services <path>     Applications directory path
+  --project-id <id>         GCP project ID
+  --region <region>         Primary region (default: us-central1)
+  --cluster <name>          Cluster name
+  --skip-claude-install     Skip Claude Code installation
+```
+
+---
+
+## 📦 What Gets Installed?
+
+### Created Structure
+
+```
+your-project/
+├── .claude/                    ← New directory
+│   ├── agents/ (symlink)       → Agent definitions
+│   ├── skills/ (symlink)       → Skill modules
+│   ├── tools/ (symlink)        → Orchestration tools
+│   ├── hooks/ (symlink)        → Security validations
+│   ├── commands/ (symlink)     → Slash commands
+│   ├── config/ (symlink)       → Configuration (contracts, rules)
+│   ├── templates/ (symlink)    → Installation templates
+│   ├── speckit/ (symlink)      → Spec-Kit framework
+│   ├── project-context/        ← Your project context (SSOT)
+│   ├── logs/                   ← Audit logs
+│   └── settings.json           ← Security configuration
+├── CLAUDE.md                   ← Main orchestrator
+└── node_modules/
+    └── @jaguilar87/gaia-ops/   ← npm package
+```
+
+---
+
+## 📚 Documentation Available After Installation
+
+Once installed, you have access to **complete documentation** in each directory:
+
+### Directory READMEs
+
+```
+.claude/
+├── agents/               6 agents (terraform-architect, gitops-operator, etc.)
+├── skills/README.md      17 skill modules
+├── commands/README.md    7 speckit slash commands
+├── config/README.md      Contracts, git standards, universal rules
+├── hooks/README.md       3 hooks (pre, post, metrics)
+├── tools/                Context, memory, validation, review
+├── speckit/README.md     Spec-Kit framework
+├── templates/README.md   Installation templates
+└── bin/README.md         CLI utilities
+```
+
+---
+
+## ✅ Post-Installation
+
+### 1. Verify Installation
+
+```bash
+# Check created structure
+ls -la .claude/
+
+# Should show symlinks:
+# agents -> ../node_modules/@jaguilar87/gaia-ops/agents
+# tools -> ../node_modules/@jaguilar87/gaia-ops/tools
+```
+
+### 2. Review Generated Configuration
+
+```bash
+# View generated CLAUDE.md
+cat CLAUDE.md
+
+# View project-context.json
+cat .claude/project-context/project-context.json
+```
+
+### 3. Start Claude Code
+
+```bash
+claude-code
+```
+
+### 4. Test the System
+
+```bash
+# In Claude Code, try:
+"Show me GKE clusters"
+"List deployments in production namespace"
+
+# Or use slash commands:
+/gaia Explain how routing works
+```
+
+---
+
+## 🔄 Package Updates
+
+### ⚠️ Files That Get Overwritten
+
+When you update `@jaguilar87/gaia-ops`, these files are **regenerated from templates**:
+
+| File | Behavior | Recommended Action |
+|------|----------|-------------------|
+| `CLAUDE.md` | ⚠️ **Overwritten** | Backup if you customize |
+| `.claude/settings.json` | ⚠️ **Overwritten** | Backup if you customize |
+| `.claude/project-context/project-context.json` | ✅ **Preserved** | Safe |
+| `.claude/logs/` | ✅ **Preserved** | Safe |
+| Other `.claude/` files | ✅ **Auto-updated via symlinks** | Safe |
+
+### Update Process
+
+```bash
+# 1. Backup (optional, if you customized)
+cp CLAUDE.md CLAUDE.md.backup
+cp .claude/settings.json .claude/settings.json.backup
+
+# 2. Update package
+npm install @jaguilar87/gaia-ops@latest
+
+# 3. Postinstall hook automatically regenerates:
+#    - CLAUDE.md
+#    - .claude/settings.json
+
+# 4. If you made backup, compare and merge changes
+diff CLAUDE.md CLAUDE.md.backup
+```
+
+---
+
+## 🛠️ Claude Code Management
+
+### Avoiding Multiple Installations
+
+Gaia-Ops **automatically detects** if you already have Claude Code installed and **does NOT reinstall it**.
+
+#### Installation Verification
+
+```bash
+# See where Claude Code is installed
+which claude-code
+
+# Should show ONE location:
+# ✅ /usr/local/bin/claude-code (native - recommended)
+```
+
+#### If You Have Multiple Installations
+
+**Option 1: Automatic Cleanup**
+```bash
+npx gaia-cleanup
+```
+
+**Option 2: Manual Cleanup**
+```bash
+# Remove npm global installation (if exists)
+npm -g uninstall @anthropic-ai/claude-code
+
+# Verify only one remains
+which claude-code
+claude-code --version
+```
+
+---
+
+## 🐛 Troubleshooting
+
+### Problem: Claude Code Not Found
+
+**Solution:**
+```bash
+# Verify installation
+which claude-code
+
+# If not found, install manually
+npm install -g @anthropic-ai/claude-code
+```
+
+---
+
+### Problem: Multiple Claude Code Installations
+
+**Solution:**
+```bash
+# Automatic cleanup
+npx gaia-cleanup
+```
+
+---
+
+### Problem: Permission Denied on npm global
+
+**Solution (recommended):**
+```bash
+mkdir ~/.npm-global
+npm config set prefix '~/.npm-global'
+export PATH=~/.npm-global/bin:$PATH
+echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
+```
+
+---
+
+### Problem: Symlinks Not Created
+
+**Solution:**
+```bash
+# Re-run installation
+npx gaia-init --force
+```
+
+---
+
+## 🧹 Uninstallation
+
+### Complete Uninstallation
+
+```bash
+# Interactive script (recommended)
+npx gaia-uninstall
+
+# Forced uninstall (no questions)
+npx gaia-uninstall --force --remove-all
+```
+
+### Manual Uninstallation
+
+```bash
+# 1. Remove .claude/ directory
+rm -rf .claude/
+
+# 2. Remove generated files
+rm CLAUDE.md AGENTS.md
+
+# 3. Uninstall npm package
+npm uninstall @jaguilar87/gaia-ops
+```
+
+---
+
+## 💡 Design Principles
+
+Gaia-Ops is designed with these principles:
+
+✅ **Minimal** - Only creates what's needed, no duplicates  
+✅ **Adaptive** - Auto-detects existing installations  
+✅ **Non-invasive** - Works from any directory  
+✅ **Safe** - Validates paths and skips reinstalls  
+✅ **Clear** - Explicit feedback on each step  
+✅ **Documented** - Complete documentation in each directory  
+
+---
+
+## 📞 Support
+
+### Resources
+
+- **Documentation:** Inside `.claude/*/README.md`
+- **Issues:** https://github.com/metraton/gaia-ops/issues
+- **Email:** jaguilar1897@gmail.com
+
+### Frequently Asked Questions
+
+**Q: Can I use gaia-ops in multiple projects?**  
+A: Yes. Install in each project and each will have its own `project-context.json`.
+
+**Q: Do symlinks work on Windows?**  
+A: Yes, but you need to enable developer mode or run as administrator.
+
+**Q: Can I customize CLAUDE.md without it being overwritten?**  
+A: Not directly. Better: contribute changes to the template in the repository.
+
+**Q: How do I update only documentation without changing code?**  
+A: `npm update @jaguilar87/gaia-ops` - symlinks point to the new version automatically.
+
+---
+
+**Version:** 4.0.0
+**Last updated:** 2026-03-03
+**Maintained by:** Jorge Aguilar + Gaia (meta-agent)
+