icdev 1.0.0__py3-none-any.whl

icdev/data/goals/cli_capabilities.md

@@ -0,0 +1,340 @@
+// CUI // SP-CTI
+// Distribution: Authorized personnel only
+// Handling: In accordance with DoDI 5200.48
+
+# Goal: CLI Capabilities — Optional Claude Code CLI Features
+
+## Purpose
+
+Guide customers in deciding whether to enable Claude Code CLI capabilities beyond the standard VSCode extension. Four optional capabilities — CI/CD automation, parallel agent execution, container-based execution, and scripted intake — are independently toggleable per project, with tenant-level ceilings in SaaS deployments.
+
+**Why this matters:** The VSCode extension and CLI use the same engine (same model, same tools, same capabilities). The CLI unlocks headless, scripted, parallel, and containerized execution modes that some environments need and others cannot support. Forcing CLI on all customers creates friction; disabling it everywhere limits power users. Independent toggles let each project use what fits.
+
+---
+
+## Prerequisites
+
+- [ ] Project initialized (`goals/init_project.md` completed)
+- [ ] `args/cli_config.yaml` present (capability toggles, cost controls, detection settings)
+- [ ] For SaaS deployments: tenant ceiling set by tenant admin
+- [ ] `memory/MEMORY.md` loaded (session context)
+
+---
+
+## Decision Guide: CLI vs VSCode Extension
+
+### When the VSCode Extension Is Sufficient (Default)
+
+| Scenario | Why Extension Works |
+|----------|-------------------|
+| Interactive development | File context, inline diffs, visual feedback built in |
+| Single developer workflow | No need for parallel execution |
+| Manual requirements intake | Conversational Q&A works well interactively |
+| GUI-preferred users | PMs, ISSOs, compliance officers prefer visual tools |
+| No CI/CD pipeline yet | No runners to install CLI on |
+| Restricted desktop environments | Some environments lock down terminal access |
+
+**Recommendation:** Start with the extension. Enable CLI capabilities only when a specific need arises.
+
+### When to Enable CLI Capabilities
+
+#### Capability 1: CI/CD Pipeline Automation (`cicd_automation`)
+
+**Enable when:**
+- You have GitLab CI/CD or GitHub Actions runners
+- You want AI-assisted build/test/review as automated pipeline stages
+- Your runners have network access to the LLM endpoint (Bedrock or Anthropic API)
+- You want pipeline stages that can reason about failures and self-correct
+
+**Do NOT enable when:**
+- No CI/CD infrastructure exists
+- Runners are air-gapped with no LLM access
+- Cost controls are strict (each pipeline run consumes tokens)
+- Deterministic Python tools (`tools/`) already handle your pipeline needs
+
+**Environment requirements:**
+- Claude CLI installed on runner: `npm install -g @anthropic-ai/claude-code`
+- API credentials available to runner (env var or secrets manager)
+- Network egress to LLM endpoint
+- Sufficient runner compute (CLI needs ~200MB RAM)
+
+**Example GitLab CI stage:**
+```yaml
+icdev-review:
+  stage: review
+  image: icdev/agent-base:latest
+  script:
+    - claude -p "/icdev-review" --no-interactive --output-format json
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+  variables:
+    ANTHROPIC_API_KEY: $ANTHROPIC_API_KEY
+```
+
+---
+
+#### Capability 2: Parallel Agent Execution (`parallel_agents`)
+
+**Enable when:**
+- You need to run independent SDLC phases concurrently (e.g., security scan + compliance check)
+- Your API rate limits support multiple concurrent requests
+- You use git worktrees for file isolation (`args/worktree_config.yaml`)
+- Time-to-delivery matters more than token cost
+
+**Do NOT enable when:**
+- Phases are interdependent (plan must finish before build)
+- API rate limits are restrictive
+- Single-threaded execution meets your timeline
+- Coordination overhead outweighs time savings
+
+**Safe parallel combinations:**
+| Parallel Group | Why Safe |
+|----------------|----------|
+| Security scan + Compliance check | Read-only analysis, no file changes |
+| Unit tests + BDD tests | Independent test suites |
+| Terraform plan + Ansible lint | Independent IaC validation |
+
+**Always sequential:**
+| Phase | Must Wait For |
+|-------|--------------|
+| Build | Plan completion |
+| Test | Build completion |
+| Deploy | All gates passed |
+
+---
+
+#### Capability 3: Container-Based Execution (`container_execution`)
+
+**Enable when:**
+- You run agents as K8s pods (not just local Python processes)
+- You need STIG-hardened agent runtime environments
+- You want resource limits enforced per agent (CPU, memory)
+- You need container-level network isolation between agents
+
+**Do NOT enable when:**
+- Agents run locally on developer machines
+- No container runtime available
+- The existing Python A2A agent pattern meets your needs
+- Container registry not available for custom images
+
+**Security requirements (all enforced):**
+- Non-root execution (UID 1000)
+- Read-only root filesystem
+- All capabilities dropped
+- Secrets via K8s secrets or AWS Secrets Manager (never in image)
+- Network policy: default-deny egress, whitelist LLM endpoint + internal A2A
+
+---
+
+#### Capability 4: Scripted / Batch Intake (`scripted_intake`)
+
+**Enable when:**
+- You have large volumes of existing requirements documents (SOWs, CDDs, CONOPS)
+- You want to batch-process documents without interactive Q&A
+- Your intake process is repeatable across similar projects
+- You need programmatic intake (API or script-driven)
+
+**Do NOT enable when:**
+- Requirements are vague and need conversational clarification
+- Customer prefers interactive guided intake
+- Document quality is low (batch mode may miss ambiguities that conversation catches)
+- You want gap detection to prompt follow-up questions in real-time
+
+**Example batch command:**
+```bash
+# Pre-create session
+python tools/requirements/intake_engine.py \
+  --project-id "proj-123" \
+  --customer-name "Jane Smith" \
+  --customer-org "DoD PEO" \
+  --impact-level IL5 --json > session.json
+
+# Batch intake from document
+SESSION_ID=$(jq -r '.session_id' session.json)
+claude -p "/icdev-intake --session-id $SESSION_ID --batch" < sow.txt
+```
+
+---
+
+## Process: Enabling CLI Capabilities
+
+### Step 1: Check Environment Compatibility
+
+**Tool:** Auto-detection via `args/cli_config.yaml` → `detection.auto_detect: true`
+
+The system auto-checks CLI availability on first use. Result is logged to audit trail.
+
+**Manual check:**
+```bash
+claude --version        # CLI installed?
+claude --help           # Accessible?
+python --version        # Python available for tools?
+```
+
+**Decision matrix:**
+
+| Environment | CLI Available | Recommended Capabilities |
+|-------------|--------------|-------------------------|
+| Developer laptop (Windows/Mac) | Usually yes | None — use VSCode extension |
+| GitLab runner (Linux) | Install required | cicd_automation |
+| K8s pod (container) | Install in image | container_execution, cicd_automation |
+| Air-gapped workstation | Maybe (offline install) | scripted_intake (if LLM accessible) |
+| Cloud IDE (Gitpod, Codespaces) | Usually yes | parallel_agents, cicd_automation |
+| Restricted government desktop | Unlikely | None — use VSCode extension |
+
+**Error handling:**
+- CLI not found → fallback to extension mode, log warning
+- CLI found but no API key → log error, disable all CLI capabilities
+- CLI found but rate-limited → reduce `max_concurrent` and `max_invocations_per_hour`
+
+**Verify:** Detection result stored in audit trail. `args/cli_config.yaml` updated if auto-detect changes defaults.
+
+---
+
+### Step 2: Configure Tenant Ceiling (SaaS Only)
+
+**Applies to:** SaaS multi-tenant deployments only. Skip for standalone installations.
+
+Tenant admin sets the maximum CLI capabilities allowed for all projects in their organization.
+
+**Tool:** Tenant portal (`tools/saas/portal/`) → Settings → CLI Capabilities
+
+Or via API:
+```bash
+curl -X PUT https://platform/api/v1/tenant/settings \
+  -H "Authorization: Bearer icdev_..." \
+  -d '{"cli_ceiling": {"cicd_automation": true, "parallel_agents": false, "container_execution": true, "scripted_intake": true}}'
+```
+
+**Rules:**
+- Tenant ceiling defaults to all-enabled for Enterprise tier
+- Professional tier: all except `container_execution`
+- Starter tier: `scripted_intake` only
+- Project cannot exceed tenant ceiling (enforced at runtime)
+
+**Verify:** Tenant settings stored in `platform.db` → `tenants` table `settings_json` column.
+
+---
+
+### Step 3: Enable Project-Level Capabilities
+
+**Tool:** Edit `args/cli_config.yaml` → `project` section
+
+For each capability:
+1. Check tenant ceiling allows it (SaaS) or skip (standalone)
+2. Verify prerequisites are met (see capability-specific sections above)
+3. Set `enabled: true`
+4. Configure capability-specific settings
+
+**Example — enable CI/CD automation only:**
+```yaml
+project:
+  cicd_automation:
+    enabled: true
+    runner_type: gitlab
+    allowed_commands:
+      - "/icdev-build"
+      - "/icdev-test"
+      - "/icdev-review"
+  parallel_agents:
+    enabled: false
+  container_execution:
+    enabled: false
+  scripted_intake:
+    enabled: false
+```
+
+**Verify:** Run `python tools/testing/health_check.py` — CLI capabilities section should show enabled/disabled status.
+
+---
+
+### Step 4: Set Cost Controls
+
+**Tool:** Edit `args/cli_config.yaml` → `cost_controls` section
+
+CLI invocations consume API tokens. Set budgets to prevent runaway costs.
+
+**Recommended defaults by tier:**
+
+| Tier | Daily Token Budget | Hourly Invocations | Alert Threshold |
+|------|-------------------|-------------------|-----------------|
+| Starter | 100,000 | 10 | 80% |
+| Professional | 500,000 | 30 | 80% |
+| Enterprise | 2,000,000 | 100 | 90% |
+
+**Verify:** Token usage tracked in `agent_token_usage` table. Alerts fire when `alert_at_percent` reached.
+
+---
+
+### Step 5: Validate Configuration
+
+Run the capability validation check:
+
+```bash
+# Check which capabilities are enabled and functional
+python -c "
+import yaml
+with open('args/cli_config.yaml') as f:
+    cfg = yaml.safe_load(f)
+for cap in ['cicd_automation', 'parallel_agents', 'container_execution', 'scripted_intake']:
+    proj = cfg['project'][cap]
+    ceiling = cfg['tenant_ceiling'][cap]
+    status = 'ENABLED' if proj['enabled'] and ceiling else 'DISABLED'
+    if proj['enabled'] and not ceiling:
+        status = 'BLOCKED (tenant ceiling)'
+    print(f'  {cap}: {status}')
+"
+```
+
+**Expected output:**
+```
+  cicd_automation: ENABLED
+  parallel_agents: DISABLED
+  container_execution: DISABLED
+  scripted_intake: DISABLED
+```
+
+---
+
+## Edge Cases
+
+| Situation | Handling |
+|-----------|---------|
+| CLI installed but API key missing | Disable all CLI capabilities, log error, fall back to extension |
+| Tenant ceiling blocks project toggle | Project toggle silently ignored, logged as "blocked by tenant ceiling" |
+| CI/CD runner has CLI but times out | Respect `timeout_seconds`, fail the pipeline stage, log to audit |
+| Parallel agents hit rate limit | Queue excess requests, log warning, reduce concurrency dynamically |
+| Batch intake with malformed document | Return parse error, do NOT partially import, preserve original session state |
+| Container image missing CLI | Build fails on startup, log error, pod restart with backoff |
+| Cost budget exhausted mid-pipeline | Stop CLI invocations, complete in-flight work, alert admin, log to audit |
+| Air-gapped environment with local Ollama | CLI works if `prefer_local: true` in `llm_config.yaml` — route to Ollama |
+
+---
+
+## Persona Guidance
+
+| Persona | Likely Capabilities | Notes |
+|---------|-------------------|-------|
+| **Developer** | parallel_agents, cicd_automation | Comfortable with CLI, wants speed |
+| **PM / Product Owner** | scripted_intake | Batch-process requirement docs, review output in dashboard |
+| **ISSO / Compliance Officer** | None (use dashboard/extension) | Prefers GUI, reviews artifacts not processes |
+| **DevOps Engineer** | cicd_automation, container_execution | Manages runners and K8s, CLI natural fit |
+| **System Integrator** | All four | Needs full automation for multi-project delivery |
+
+---
+
+## Related Goals
+
+| Goal | Relationship |
+|------|-------------|
+| CI/CD Integration | `cicd_automation` extends pipeline with Claude CLI stages |
+| Parallel CI/CD | `parallel_agents` builds on git worktree isolation |
+| Requirements Intake | `scripted_intake` adds batch mode to RICOAS intake |
+| SaaS Multi-Tenancy | Tenant ceiling enforced via SaaS platform settings |
+| Multi-Agent Orchestration | `container_execution` containerizes agent instances |
+
+---
+
+## Architecture Decision
+
+**D132:** CLI capabilities are optional per-project toggles with tenant-level ceiling. Tenant sets maximum allowed capabilities; project enables within ceiling. Default is all-disabled — VSCode extension provides full functionality. CLI adds headless/scripted/parallel/containerized execution modes for environments that support them. Cost controls enforce token budgets. Detection auto-checks CLI availability and falls back gracefully.

icdev/data/goals/cloud_agnostic.md

@@ -0,0 +1,312 @@
+# [TEMPLATE: CUI // SP-CTI]
+
+# Goal: Cloud-Agnostic Architecture
+
+## Purpose
+
+Enable ICDEV to deploy on any supported Cloud Service Provider (CSP) — or on-premises — using a single, unified abstraction layer. Cloud-specific details (endpoints, SDKs, regions, compliance certifications) are encapsulated behind provider ABCs so that the GOTCHA framework, compliance engine, and all tools operate identically regardless of the underlying infrastructure.
+
+**Why this matters:** Government and DoD customers deploy on different cloud environments — AWS GovCloud, Azure Government, GCP Assured Workloads, OCI Government Cloud, IBM Cloud for Government (IC4G), or fully air-gapped on-premises enclaves. ICDEV must support all of these without duplicating business logic. A single `cloud_config.yaml` setting switches the entire stack.
+
+---
+
+## When to Use
+
+- When deploying ICDEV to a new cloud environment
+- When generating Terraform, Helm, or K8s manifests for a specific CSP
+- When configuring LLM routing for multi-cloud AI providers
+- When validating region compliance certifications before deployment
+- When onboarding a new tenant with a specific CSP requirement (Phase 21 multi-tenancy)
+- When switching between government and commercial cloud modes
+- When operating in air-gapped or on-premises environments
+
+---
+
+## Prerequisites
+
+- [ ] Cloud configuration: `args/cloud_config.yaml` (CSP selection, cloud mode, region, per-service overrides)
+- [ ] CSP certifications registry: `context/compliance/csp_certifications.json`
+- [ ] LLM configuration: `args/llm_config.yaml` (multi-cloud LLM providers)
+- [ ] ICDEV database initialized (`python tools/db/init_icdev_db.py`)
+- [ ] CSP-specific SDK installed for target cloud (optional — graceful degradation per D231)
+
+---
+
+## Workflow
+
+### Step 1: Configure Cloud Mode
+
+Select the deployment cloud mode based on impact level and operational environment. The cloud mode drives endpoint selection, FIPS settings, and feature availability across all CSP providers.
+
+**Tool:** `tools/cloud/cloud_mode_manager.py`
+
+**Cloud modes (D232):**
+
+| Mode | Description | Internet | FIPS | Impact Levels |
+|------|-------------|----------|------|---------------|
+| commercial | Standard commercial cloud regions | Required | No | IL2 |
+| government | Government cloud with FedRAMP authorization | Required | Yes | IL2, IL4, IL5 |
+| on_prem | On-premises, optional cloud services | Optional | Yes | IL2–IL6 |
+| air_gapped | Fully air-gapped, no internet | No | Yes | IL2–IL6 |
+
+**CLI:**
+```bash
+python tools/cloud/cloud_mode_manager.py --status --json     # Current mode and config
+python tools/cloud/cloud_mode_manager.py --validate --json   # Validate against constraints
+python tools/cloud/cloud_mode_manager.py --eligible --json   # List eligible modes
+python tools/cloud/cloud_mode_manager.py --check-readiness   # Probe cloud services
+```
+
+**Output:** Validation results with errors (blocking) and warnings (advisory).
+
+**Error handling:**
+- Invalid cloud_mode → report error with valid options
+- CSP does not support mode → report with supported modes for that CSP
+- IL incompatible with mode → report with allowed modes for that IL
+
+---
+
+### Step 2: Resolve Cloud Providers
+
+The CSP Provider Factory (D225) resolves the correct implementation for each cloud service based on configuration. It supports per-service CSP overrides — e.g., use AWS for secrets but Azure for storage.
+
+**Tool:** `tools/cloud/provider_factory.py`
+
+**Service ABCs (6 services × 6 CSPs = 36 implementations):**
+
+| Service | ABC | AWS | Azure | GCP | OCI | IBM | Local |
+|---------|-----|-----|-------|-----|-----|-----|-------|
+| Secrets | `SecretsProvider` | Secrets Manager | Key Vault | Secret Manager | Vault | Secrets Manager | .env file |
+| Storage | `StorageProvider` | S3 | Blob Storage | GCS | Object Storage | Cloud Object Storage | Local filesystem |
+| KMS | `KMSProvider` | KMS | Key Vault | Cloud KMS | Key Management | Key Protect | Fernet |
+| Monitoring | `MonitoringProvider` | CloudWatch | Azure Monitor | Cloud Monitoring | Monitoring | LogDNA/Sysdig | Local log |
+| IAM | `IAMProvider` | IAM | Entra ID | Cloud IAM | Identity | IAM | Local RBAC |
+| Registry | `RegistryProvider` | ECR | ACR | Artifact Registry | OCIR | Container Registry | Docker |
+
+**Per-service override (D225):** Set `ICDEV_SECRETS_PROVIDER=azure` to use Azure Key Vault for secrets while all other services use the global provider.
+
+**CLI:** `python -c "from tools.cloud.provider_factory import CSPProviderFactory; f = CSPProviderFactory(); print(f.health_check())"`
+
+**Error handling:**
+- CSP SDK not installed → graceful degradation (D231), fall back to local provider
+- Config file missing → default to local provider with warning
+
+---
+
+### Step 3: Validate Deployment Region
+
+Before deploying, validate that the target CSP region holds all required compliance certifications for the project's impact level.
+
+**Tool:** `tools/cloud/region_validator.py`
+
+**Certification requirements by IL:**
+
+| Impact Level | Required Certifications |
+|-------------|------------------------|
+| IL2 | FedRAMP Moderate |
+| IL4 | FedRAMP Moderate, FIPS 140-2 |
+| IL5 | FedRAMP High, FIPS 140-2, DoD IL5 |
+| IL6 | FedRAMP High, FIPS 140-2, DoD IL6 |
+
+**Catalog:** `context/compliance/csp_certifications.json` — declarative registry of region-level certifications per CSP (D233).
+
+**CLI:**
+```bash
+python tools/cloud/region_validator.py --validate --csp aws --region us-gov-west-1 --required fedramp_high --json
+python tools/cloud/region_validator.py --eligible --csp azure --il IL5 --json
+python tools/cloud/region_validator.py --deployment-check --json
+```
+
+**Output:** Validation result with missing certifications.
+
+**Error handling:**
+- Region not in certifications catalog → reject deployment, suggest certified alternatives
+- Certifications file missing → warn, allow with manual override
+
+---
+
+### Step 4: Generate CSP-Specific IaC
+
+Generate Terraform modules tailored to the target CSP. Each generator produces compliant infrastructure matching the CSP's government or commercial region requirements.
+
+**Tools:**
+
+| Generator | Target CSP | Key Resources |
+|-----------|-----------|---------------|
+| `tools/infra/terraform_generator.py` | AWS GovCloud | VPC, EKS, RDS, ECR, Secrets Manager |
+| `tools/infra/terraform_generator_azure.py` | Azure Government | VNet, AKS, Azure SQL, ACR, Key Vault |
+| `tools/infra/terraform_generator_gcp.py` | GCP Assured Workloads | VPC, GKE, Cloud SQL, Artifact Registry |
+| `tools/infra/terraform_generator_oci.py` | OCI Government | VCN, OKE, Autonomous DB, OCIR, Vault |
+| `tools/infra/terraform_generator_ibm.py` | IBM Cloud (IC4G) | VPC, IKS, Databases for PostgreSQL, ICR |
+| `tools/infra/terraform_generator_onprem.py` | On-premises | Docker Compose, self-managed K8s |
+
+**Auto-dispatch (D227):** The Terraform dispatcher reads `cloud_config.yaml` or `ICDEV_CLOUD_PROVIDER` env var and delegates to the appropriate CSP-specific generator.
+
+**CLI:**
+```bash
+python tools/infra/terraform_generator.py --project-id "proj-123"                    # AWS (default)
+python tools/infra/terraform_generator_azure.py --project-id "proj-123" --json       # Azure
+python tools/infra/terraform_generator_gcp.py --project-id "proj-123" --json         # GCP
+python tools/infra/terraform_generator_oci.py --project-id "proj-123" --json         # OCI
+python tools/infra/terraform_generator_ibm.py --project-id "proj-123" --json         # IBM
+python tools/infra/terraform_generator_onprem.py --project-id "proj-123" --json      # On-prem
+```
+
+**Output:** Terraform `.tf` files with CSP-specific resources, FIPS endpoints, government regions, and compliance tags.
+
+**Error handling:**
+- CSP SDK not available → generate Terraform that uses CLI authentication instead
+- Region not certified → block generation, suggest alternative region
+
+---
+
+### Step 5: Configure Multi-Cloud LLM Routing
+
+Route LLM calls to the appropriate cloud AI service based on provider configuration. Each CSP has its own LLM service with government and commercial endpoint variants.
+
+**Tool:** `tools/llm/router.py` (LLMRouter)
+
+**LLM providers (D228):**
+
+| CSP | LLM Service | Government Endpoint | Models |
+|-----|------------|--------------------| -------|
+| AWS | Amazon Bedrock | bedrock.us-gov-west-1.amazonaws.com | Claude, Titan, Llama |
+| Azure | Azure OpenAI | *.openai.azure.us | GPT-4, GPT-4o |
+| GCP | Vertex AI | us-*-aiplatform.googleapis.com | Gemini, Claude-via-Vertex |
+| OCI | OCI GenAI | genai.*.oci.oraclecloud.com | Cohere, Llama |
+| IBM | watsonx.ai | watsonx.*.cloud.ibm.com | Granite, Llama, Slate (embed) |
+| Local | Ollama | localhost:11434 | Any local model |
+
+**Fallback chains (D37):** Configurable per CSP and cloud mode. Air-gapped deployments set `prefer_local: true` — chains end with local Ollama models.
+
+**CLI:** `python -c "from tools.llm.router import LLMRouter; r = LLMRouter(); print(r.get_provider_for_function('code_generation'))"`
+
+**Error handling:**
+- Primary LLM provider unavailable → fall through to next in fallback chain
+- All cloud providers down → fall back to Ollama local if available
+
+---
+
+### Step 6: Generate Helm Value Overlays
+
+Generate CSP-specific Helm value files for K8s deployment.
+
+**Overlays (D229):**
+
+| File | CSP | Key Settings |
+|------|-----|-------------|
+| `deploy/helm/values-aws.yaml` | AWS GovCloud | ECR registry, RDS endpoints, KMS ARN |
+| `deploy/helm/values-azure.yaml` | Azure Government | ACR registry, Azure SQL, Key Vault URI |
+| `deploy/helm/values-gcp.yaml` | GCP | Artifact Registry, Cloud SQL, KMS key |
+| `deploy/helm/values-oci.yaml` | OCI | OCIR registry, Autonomous DB, Vault OCID |
+| `deploy/helm/values-ibm.yaml` | IBM Cloud | ICR registry, PostgreSQL, Key Protect |
+| `deploy/helm/values-on-prem.yaml` | On-prem | Local registry, local DB, Fernet |
+| `deploy/helm/values-docker.yaml` | Docker Compose | Local development configuration |
+
+**CLI:** `helm install icdev deploy/helm/ -f deploy/helm/values-<csp>.yaml`
+
+---
+
+### Step 7: Monitor Cloud Service Health
+
+Continuously monitor all configured cloud services and detect CSP-level changes (API deprecations, new regions, compliance certification updates).
+
+**Tools:**
+- `tools/cloud/csp_health_checker.py` — Probe all CSP services, store in `cloud_provider_status` table (D230)
+- `tools/cloud/csp_monitor.py` — Monitor CSP service changes via RSS/API feeds (D239)
+- `tools/cloud/csp_changelog.py` — Generate changelog of CSP service changes
+
+**CLI:**
+```bash
+python tools/cloud/csp_health_checker.py --check-all --json              # Health check all services
+python tools/cloud/csp_health_checker.py --check-service secrets --json  # Check specific service
+python tools/cloud/csp_health_checker.py --history --hours 24 --json     # Health history
+python tools/cloud/csp_monitor.py --scan --all --json                    # Monitor CSP changes
+python tools/cloud/csp_changelog.py --generate --json                    # Generate changelog
+```
+
+**Integration:** CSP monitor feeds into Phase 35 Innovation Engine as an innovation signal source (D239).
+
+**Error handling:**
+- CSP service unreachable → mark as unhealthy, alert, do not block other services
+- Health check timeout → retry once, then mark degraded
+
+---
+
+## Outputs
+
+- CSP provider instances (Secrets, Storage, KMS, Monitoring, IAM, Registry)
+- Cloud mode validation results
+- Region certification validation results
+- CSP-specific Terraform modules (`.tf` files)
+- Helm value overlays (`values-<csp>.yaml`)
+- Health check records (`cloud_provider_status` table)
+- CSP change signals (Innovation Engine integration)
+- LLM routing configuration (per-function provider resolution)
+
+---
+
+## Error Handling
+
+- If CSP SDK is not installed: degrade gracefully to local provider (D231), warn in logs
+- If cloud_config.yaml is missing: default to local provider, warn
+- If region lacks required certifications: block deployment, suggest certified alternatives
+- If LLM provider is unavailable: fall through fallback chain (D37)
+- If health check fails: mark service unhealthy, continue with other services
+- If cloud mode is incompatible with impact level: error with valid mode options
+
+---
+
+## Architecture Decisions
+
+| ID | Decision | Rationale |
+|----|----------|-----------|
+| D225 | CSP abstraction uses ABC + 6 implementations per service | Interface + adapters isolate vendor logic; consistent with D66 provider pattern |
+| D226 | Multi-cloud Terraform generators produce CSP-specific IaC | Each CSP has unique resource types and naming; shared abstraction isn't possible for IaC |
+| D227 | Terraform dispatcher auto-detects CSP from config/env | Single entry point, automatic routing based on cloud_config.yaml |
+| D228 | LLM multi-cloud: Azure OpenAI, Vertex AI, OCI GenAI, IBM watsonx.ai | Best-of-breed LLM per CSP; fallback chains ensure availability |
+| D229 | Helm value overlays per CSP | Helm values are the standard K8s configuration mechanism; per-CSP overrides compose cleanly |
+| D230 | CSP health checker stores status in cloud_provider_status table | Enables trend analysis and alerting for cloud service degradation |
+| D231 | CSP SDKs are optional dependencies | Only install SDK for target CSP; avoid bloated requirements.txt |
+| D232 | cloud_mode controls endpoint selection per CSP | Single config field drives government/commercial/on-prem/air-gapped behavior |
+| D233 | CSP certifications as declarative JSON catalog | Consistent with D26 pattern; human-maintained, machine-validated |
+| D234 | Region validator blocks uncertified deployments | Prevents accidental deployment to non-compliant regions |
+| D236 | On-prem Terraform targets Docker Compose and self-managed K8s | No cloud provider block required; works fully offline |
+| D237 | IBM Cloud follows D66 ABC pattern with IBM SDKs | Consistent provider architecture; IBM COS uses S3-compatible ibm_boto3 |
+| D238 | IBM watsonx.ai LLM via ibm-watsonx-ai SDK | Granite + Llama model families; Slate for embeddings |
+| D239 | CSP monitor feeds into Innovation Engine | Reuses Phase 35 signal scoring and triage pipeline for CSP changes |
+
+---
+
+## GOTCHA Layer Mapping
+
+| Step | GOTCHA Layer | Component |
+|------|-------------|-----------|
+| Cloud Mode Selection | Tools | `cloud_mode_manager.py` |
+| Provider Resolution | Tools | `provider_factory.py` |
+| Region Validation | Tools | `region_validator.py` |
+| Terraform Generation | Tools | `terraform_generator_*.py` |
+| LLM Routing | Tools | `router.py` (LLMRouter) |
+| Health Monitoring | Tools | `csp_health_checker.py`, `csp_monitor.py` |
+| Cloud configuration | Args | `args/cloud_config.yaml` |
+| LLM configuration | Args | `args/llm_config.yaml` |
+| CSP monitor configuration | Args | `args/csp_monitor_config.yaml` |
+| Region certifications | Context | `context/compliance/csp_certifications.json` |
+| CSP MCP registry | Context | `context/agentic/csp_mcp_registry.yaml` |
+
+---
+
+## Related Files
+
+- **Goals:** `goals/deploy_workflow.md` (deployment pipeline), `goals/modular_installation.md` (installer cloud mode), `goals/saas_multi_tenancy.md` (per-tenant CSP)
+- **Tools:** `tools/cloud/` (provider factory, ABCs, health checker, region validator, monitor), `tools/infra/` (Terraform generators), `tools/llm/` (multi-cloud LLM router)
+- **Args:** `args/cloud_config.yaml`, `args/llm_config.yaml`, `args/csp_monitor_config.yaml`
+- **Context:** `context/compliance/csp_certifications.json`, `context/agentic/csp_mcp_registry.yaml`
+- **Helm:** `deploy/helm/values-*.yaml` (per-CSP overlays)
+- **Tests:** `tests/test_ibm_providers.py`, `tests/test_cloud_providers.py`
+
+---
+
+## Changelog
+
+- 2026-02-21: Initial creation — Cloud-Agnostic Architecture goal with 7-step workflow (cloud mode, provider resolution, region validation, IaC generation, LLM routing, Helm overlays, health monitoring), architecture decisions D225-D239