icdev 1.0.0__py3-none-any.whl

icdev/data/docs/features/phase-26-dod-mosa.md

@@ -0,0 +1,205 @@
+# Phase 26 — DoD Modular Open Systems Approach (MOSA)
+
+**CUI // SP-CTI**
+
+| Field | Value |
+|-------|-------|
+| Phase | 26 |
+| Title | DoD Modular Open Systems Approach (MOSA) |
+| Status | Implemented |
+| Priority | P1 |
+| Dependencies | Phase 20 (Security Categorization), Phase 23 (Universal Compliance Platform) |
+| Author | ICDEV Architect Agent |
+| Date | 2026-02-23 |
+
+---
+
+## 1. Problem Statement
+
+10 U.S.C. Section 4401 mandates the Modular Open Systems Approach (MOSA) for all major defense acquisition programs, and DoDI 5000.87 reinforces this requirement for software-intensive systems on the Software Acquisition Pathway. Systems that fail to demonstrate modular design, open interfaces, and published standards risk acquisition milestone disapproval, vendor lock-in, and inability to integrate with future DoD enterprise services. Despite this mandate, most development teams treat MOSA as a last-minute documentation exercise rather than a continuous engineering practice, producing Interface Control Documents and Technical Standard Profiles that do not reflect the actual codebase.
+
+Prior to this phase, ICDEV had no mechanism to assess MOSA compliance, analyze modularity metrics (coupling, cohesion, circular dependencies), auto-generate ICDs from discovered interfaces, produce TSPs from detected technology standards, or enforce modular code structure through static analysis. MOSA-relevant requirements detected during intake had no workflow to follow, and there was no way to feed architecture evidence into the cATO pipeline for continuous authorization. DoD/IC customers were manually creating MOSA artifacts disconnected from the code they described.
+
+Phase 26 implements MOSA as a full compliance framework using the BaseAssessor pattern (D116), with 25 requirements across 6 families (Modularity, Open Interfaces, Standards Compliance, Interoperability, Reusability, Maintainability). It auto-detects MOSA applicability during RICOAS intake for all DoD/IC customers at IL4+, performs static analysis for coupling/cohesion/circular dependency metrics, auto-generates ICDs from OpenAPI/gRPC/REST endpoints, produces TSPs from the detected technology stack, enforces MOSA-compliant code structure, and optionally feeds architecture evidence into the cATO pipeline.
+
+---
+
+## 2. Goals
+
+1. **Auto-detect MOSA applicability** during RICOAS intake for DoD/IC customers at IL4+, with keyword detection for MOSA-specific terminology and DoDI 5000.87 references
+2. Assess **25 MOSA requirements** across 6 families (Modularity, Open Interfaces, Standards Compliance, Interoperability, Reusability, Maintainability) via the BaseAssessor pattern
+3. Perform **static modularity analysis** computing coupling scores, cohesion scores (LCOM), interface coverage, circular dependency detection, and module independence ratios
+4. **Auto-generate Interface Control Documents** for all external-facing interfaces discovered from OpenAPI specs, gRPC proto files, WSDL, and REST endpoints, with NIST 800-53 control mappings
+5. **Auto-generate Technical Standard Profiles** from the detected technology stack, flagging proprietary or non-standard technologies for review
+6. **Enforce MOSA-compliant code structure** through static analysis detecting tight coupling violations, boundary violations, missing interface specs, hardcoded dependencies, and circular imports
+7. Integrate MOSA architecture evidence (SA-3, SA-8, SA-17) into the **cATO monitoring pipeline** as an optional evidence dimension
+8. Store modularity metrics as **time-series data** for trend tracking and PI-over-PI improvement visualization
+
+---
+
+## 3. Architecture
+
+### 3.1 MOSA Assessment Flow
+
+```
+Intake Session (RICOAS)
+  |
+  v
+MOSA Signal Detection
+  |-- DoD/IC customer + IL4+ -> MOSA REQUIRED (auto-trigger)
+  |-- DoD/IC customer + IL2/IL3 -> MOSA RECOMMENDED (advisory)
+  |-- Non-DoD -> MOSA NOT REQUIRED (skip)
+  |
+  v
+MOSA Compliance Assessment (25 requirements / 6 families)
+  |
+  v
+Modularity Analysis (coupling, cohesion, circular deps, interface coverage)
+  |
+  +---> ICD Generation (auto-discover from OpenAPI/gRPC/REST)
+  +---> TSP Generation (auto-detect standards from tech stack)
+  +---> Code Enforcement (static analysis for MOSA violations)
+  |
+  v
+MOSA Gate Evaluation
+  |-- PASS -> proceed to deployment
+  |-- FAIL -> remediate blocking criteria -> re-run gate
+  |
+  v
+cATO Evidence (optional, SA-3, SA-8, SA-17)
+```
+
+### 3.2 MOSA Requirement Families
+
+| Family | Requirements | Focus |
+|--------|-------------|-------|
+| Modularity | 5 | Loose coupling, high cohesion, separation of concerns, encapsulation, composability |
+| Open Interfaces | 5 | Published APIs, standard protocols, documentation, backward compatibility, versioning |
+| Standards Compliance | 4 | Adherence to approved TSP standards, no proprietary lock-in, open data formats |
+| Interoperability | 4 | Cross-system data exchange, standard messaging, service discovery, federation |
+| Reusability | 4 | Component reuse, packaging, dependency isolation, externalized configuration |
+| Maintainability | 3 | Independent deployment, hot-swap capability, technology refresh readiness |
+
+---
+
+## 4. Requirements
+
+### 4.1 Detection
+
+#### REQ-26-001: MOSA Auto-Detection
+The system SHALL auto-detect MOSA applicability during RICOAS intake when the customer organization is DoD/IC and impact level is IL4+, triggering the MOSA workflow automatically.
+
+#### REQ-26-002: Keyword Detection
+The system SHALL detect MOSA-specific signals including terminology ("modular," "open architecture," "MOSA," "interoperability"), DoDI 5000.87 or 10 U.S.C. 4401 references, and existing ICD/TSP document references.
+
+### 4.2 Assessment
+
+#### REQ-26-003: 25-Requirement Assessment
+The system SHALL assess 25 MOSA requirements organized across 6 families with per-requirement status (satisfied, partial, not_satisfied, not_assessed).
+
+#### REQ-26-004: Modularity Metrics
+The system SHALL compute modularity metrics via static analysis: afferent/efferent coupling per module, LCOM cohesion score, interface coverage percentage, circular dependency detection, and module independence ratio.
+
+#### REQ-26-005: Time-Series Metrics
+The system SHALL store modularity metrics as time-series data in the `mosa_modularity_metrics` table for trend tracking across PIs.
+
+### 4.3 Artifact Generation
+
+#### REQ-26-006: ICD Auto-Generation
+The system SHALL auto-discover external-facing interfaces from OpenAPI/Swagger specs, gRPC proto files, WSDL, and REST endpoints, generating an ICD per interface with protocol, data format, authentication, versioning, SLA, error handling, and NIST control mappings (SC-7, SC-8, SA-9).
+
+#### REQ-26-007: TSP Auto-Generation
+The system SHALL auto-detect standards from the technology stack and generate a Technical Standard Profile documenting all communication protocols, data formats, authentication methods, encryption standards, and API specifications, flagging proprietary or non-standard technologies.
+
+#### REQ-26-008: Code Enforcement
+The system SHALL scan the codebase for MOSA violations including tight coupling (direct cross-module imports bypassing interfaces), boundary violations, missing interface specs, hardcoded dependencies, and circular imports, generating fix suggestions for each violation.
+
+### 4.4 Integration
+
+#### REQ-26-009: cATO Evidence (Optional)
+When `mosa_config.yaml` has `cato_integration.enabled: true`, the system SHALL collect MOSA architecture evidence for continuous authorization covering SA-3 (SDLC), SA-8 (Security Engineering Principles), and SA-17 (Architecture and Design).
+
+#### REQ-26-010: Non-DoD Advisory Mode
+For non-DoD projects, MOSA SHALL be available on-demand via `/icdev-mosa` in advisory mode (gate does not block deployment).
+
+---
+
+## 5. Database Schema
+
+### Tables
+
+| Table | Purpose |
+|-------|---------|
+| `mosa_assessments` | MOSA compliance assessment results (25 requirements, 6 families) |
+| `icd_documents` | Generated Interface Control Documents per interface |
+| `tsp_documents` | Generated Technical Standard Profiles |
+| `mosa_modularity_metrics` | Time-series modularity metrics (coupling, cohesion, deps, coverage) |
+
+---
+
+## 6. Tools
+
+| Tool | Purpose |
+|------|---------|
+| `tools/compliance/mosa_assessor.py` | MOSA assessment (25 reqs / 6 families) and gate evaluation |
+| `tools/mosa/modular_design_analyzer.py` | Static modularity analysis (coupling, cohesion, circular deps) |
+| `tools/mosa/icd_generator.py` | Auto-generate ICDs from discovered interfaces |
+| `tools/mosa/tsp_generator.py` | Auto-generate TSP from detected technology stack |
+| `tools/mosa/mosa_code_enforcer.py` | Static analysis for MOSA code violations with fix suggestions |
+| `tools/compliance/cato_monitor.py` | cATO evidence integration (extended for MOSA) |
+
+---
+
+## 7. Architecture Decisions
+
+| ID | Decision | Rationale |
+|----|----------|-----------|
+| D125 | MOSA auto-triggers for all DoD/IC projects at IL4+ | 10 U.S.C. 4401 mandate; no opt-out for applicable programs |
+| D126 | Software development principles only (no FACE/VICTORY/SOSA hardware profiles) | Hardware MOSA is out of scope for a software-focused platform |
+| D127 | Full compliance framework via BaseAssessor pattern (D116) | Crosswalk integration, gate evaluation, CLI for ~60 LOC per framework |
+| D128 | ICD and TSP as generated artifacts (auto-discovered from code) | Documents reflect actual codebase, not manually authored assumptions |
+| D129 | Static analysis for enforcement using Python ast, import graph, regex (D13) | Air-gap safe, zero external dependencies, deterministic |
+| D130 | cATO evidence is optional (config flag) | Not all projects use cATO; evidence collection should not be forced |
+| D131 | Modularity metrics stored as time-series | Enables trend tracking and PI-over-PI improvement visualization |
+
+---
+
+## 8. Security Gate
+
+**MOSA Gate:**
+- 0 external interfaces without an ICD (blocking)
+- 0 circular module dependencies (blocking)
+- Modularity score >= 0.6 (blocking)
+- 0 direct coupling violations (blocking at > 5)
+- Interface coverage >= 80% (warning)
+- TSP generated and current (blocking)
+- 0 proprietary standards without documented justification (warning)
+
+---
+
+## 9. Commands
+
+```bash
+# MOSA assessment
+python tools/compliance/mosa_assessor.py --project-id "proj-123" --json
+python tools/compliance/mosa_assessor.py --project-id "proj-123" --gate
+
+# Modularity analysis
+python tools/mosa/modular_design_analyzer.py --project-dir /path \
+  --project-id "proj-123" --store --json
+
+# ICD generation
+python tools/mosa/icd_generator.py --project-id "proj-123" --all --json
+python tools/mosa/icd_generator.py --project-id "proj-123" \
+  --interface-id "iface-1" --json
+
+# TSP generation
+python tools/mosa/tsp_generator.py --project-id "proj-123" --json
+
+# Code enforcement
+python tools/mosa/mosa_code_enforcer.py --project-dir /path \
+  --fix-suggestions --json
+
+# cATO MOSA evidence
+python tools/compliance/cato_monitor.py --project-id "proj-123" --mosa-evidence
+```

icdev/data/docs/features/phase-27-cli-capabilities.md

@@ -0,0 +1,222 @@
+# Phase 27 — CLI Capabilities
+
+**CUI // SP-CTI**
+
+| Field | Value |
+|-------|-------|
+| Phase | 27 |
+| Title | Optional Claude Code CLI Capabilities |
+| Status | Implemented |
+| Priority | P2 |
+| Dependencies | Phase 21 (SaaS Multi-Tenancy), Phase 15 (CI/CD Integration) |
+| Author | ICDEV Architect Agent |
+| Date | 2026-02-23 |
+
+---
+
+## 1. Problem Statement
+
+The VSCode extension and the Claude Code CLI use the same engine (same model, same tools, same capabilities), but the CLI unlocks headless, scripted, parallel, and containerized execution modes that certain environments require. Forcing CLI capabilities on all customers creates friction for teams that prefer GUI-based workflows, while disabling CLI everywhere limits power users who need automated pipeline integration, batch document processing, or concurrent agent execution. Without independent toggles, every project must either accept all CLI capabilities or none, and there is no mechanism to enforce organizational limits on token consumption or concurrent invocations.
+
+In SaaS multi-tenant deployments, different subscription tiers should grant different CLI capability ceilings: a Starter tier customer should not be able to enable container-based agent execution (which requires dedicated K8s resources), while an Enterprise tier customer should have access to all four capabilities. Without tenant-level ceilings, subscription tiers lose meaningful differentiation for power users, and cost controls become unenforceable across the organization. Projects within a tenant also need different configurations: a CI/CD pipeline project needs automation enabled, while a requirements gathering project only needs scripted intake.
+
+Phase 27 introduces four independently toggleable CLI capabilities (CI/CD pipeline automation, parallel agent execution, container-based execution, scripted batch intake) with per-project configuration and tenant-level ceilings in SaaS deployments. Each capability has clear prerequisites, environment requirements, and cost controls. Auto-detection checks CLI availability on first use and falls back gracefully when the CLI is not installed or API credentials are unavailable.
+
+---
+
+## 2. Goals
+
+1. Define **4 independently toggleable CLI capabilities** (CI/CD automation, parallel agents, container execution, scripted intake) that extend the standard VSCode extension experience
+2. Enforce **tenant-level ceilings** in SaaS deployments so subscription tiers control the maximum CLI capabilities available to any project within the organization
+3. Implement **per-project configuration** via `args/cli_config.yaml` where each capability is enabled/disabled with capability-specific settings
+4. Provide **cost controls** (daily token budgets, hourly invocation limits, alert thresholds) to prevent runaway API consumption from automated CLI usage
+5. **Auto-detect CLI availability** on first use, checking for CLI installation, API credentials, and network connectivity to LLM endpoints
+6. Provide **clear decision guidance** per persona (developer, PM, ISSO, DevOps engineer, system integrator) on which capabilities to enable
+7. Support **air-gapped environments** where CLI routes to local Ollama via `prefer_local: true` in `llm_config.yaml`
+
+---
+
+## 3. Architecture
+
+### 3.1 Capability Overview
+
+```
++-----------------------------------------------------------------------+
+|                     Claude Code CLI Capabilities                       |
+|                                                                       |
+|  +-------------------+  +-------------------+                         |
+|  | CI/CD Automation  |  | Parallel Agents   |                         |
+|  | (pipeline stages) |  | (concurrent SDLC) |                         |
+|  +-------------------+  +-------------------+                         |
+|                                                                       |
+|  +-------------------+  +-------------------+                         |
+|  | Container Exec    |  | Scripted Intake   |                         |
+|  | (K8s agent pods)  |  | (batch documents) |                         |
+|  +-------------------+  +-------------------+                         |
+|                                                                       |
+|  Controls: Tenant Ceiling -> Project Toggle -> Cost Budget -> Detect  |
++-----------------------------------------------------------------------+
+```
+
+### 3.2 Enforcement Hierarchy
+
+```
+Tenant Ceiling (SaaS tier maximum)
+  |
+  v
+Project Toggle (args/cli_config.yaml per capability)
+  |
+  v
+Cost Controls (daily token budget, hourly invocation limit)
+  |
+  v
+Environment Detection (CLI installed? API key? Network?)
+  |
+  v
+Capability Active or Graceful Fallback
+```
+
+### 3.3 Subscription Tier Ceilings
+
+| Feature | Starter | Professional | Enterprise |
+|---------|---------|-------------|------------|
+| cicd_automation | No | Yes | Yes |
+| parallel_agents | No | Yes | Yes |
+| container_execution | No | No | Yes |
+| scripted_intake | Yes | Yes | Yes |
+
+---
+
+## 4. Requirements
+
+### 4.1 Capability Toggles
+
+#### REQ-27-001: Independent Toggles
+The system SHALL provide 4 independently toggleable CLI capabilities: CI/CD pipeline automation, parallel agent execution, container-based execution, and scripted batch intake.
+
+#### REQ-27-002: Default Disabled
+All CLI capabilities SHALL default to disabled. The VSCode extension provides full functionality without any CLI capability enabled.
+
+#### REQ-27-003: Per-Project Configuration
+Each capability SHALL be configurable per project in `args/cli_config.yaml` with capability-specific settings (allowed commands, runner type, max concurrent, etc.).
+
+### 4.2 Tenant Governance
+
+#### REQ-27-004: Tenant Ceiling Enforcement
+In SaaS deployments, the system SHALL enforce tenant-level ceilings so no project can enable a CLI capability that exceeds the tenant's subscription tier allowance.
+
+#### REQ-27-005: Silent Blocking
+When a project toggle is enabled but the tenant ceiling blocks it, the system SHALL silently ignore the project toggle and log the event as "blocked by tenant ceiling."
+
+### 4.3 Cost Controls
+
+#### REQ-27-006: Token Budget
+The system SHALL enforce daily token budgets per project with configurable thresholds by subscription tier (Starter: 100K, Professional: 500K, Enterprise: 2M).
+
+#### REQ-27-007: Invocation Limits
+The system SHALL enforce hourly CLI invocation limits per project with configurable thresholds by subscription tier.
+
+#### REQ-27-008: Budget Exhaustion
+When a cost budget is exhausted mid-pipeline, the system SHALL stop new CLI invocations, complete in-flight work, alert the admin, and log to the audit trail.
+
+### 4.4 Environment Detection
+
+#### REQ-27-009: Auto-Detection
+The system SHALL auto-detect CLI availability on first use by checking for CLI installation, API credentials, and network connectivity to LLM endpoints.
+
+#### REQ-27-010: Graceful Fallback
+When the CLI is not available, the system SHALL fall back to extension mode with a warning logged to the audit trail.
+
+---
+
+## 5. Database Schema
+
+### Tables
+
+| Table | Purpose |
+|-------|---------|
+| `agent_token_usage` | Token consumption tracking per project, per user (extended with user_id) |
+
+Configuration is primarily file-based (`args/cli_config.yaml`) with tenant ceilings stored in `platform.db` -> `tenants` table `settings_json` column for SaaS deployments.
+
+---
+
+## 6. Tools
+
+| Tool | Purpose |
+|------|---------|
+| `args/cli_config.yaml` | Per-project CLI capability configuration (4 toggles, cost controls, detection) |
+| `tools/testing/health_check.py` | Includes CLI capability status in health check output |
+| `tools/agent/token_tracker.py` | Token usage tracking and cost breakdown |
+
+---
+
+## 7. Architecture Decisions
+
+| ID | Decision | Rationale |
+|----|----------|-----------|
+| D132 | CLI capabilities are optional per-project toggles with tenant-level ceiling | Default all-disabled; VSCode extension provides full functionality; CLI adds headless/scripted/parallel/containerized execution |
+| D132 | Tenant sets maximum allowed capabilities; project enables within ceiling | Prevents Starter-tier customers from using Enterprise-tier features |
+| D132 | Cost controls enforce token budgets with auto-detection fallback | Prevents runaway API costs from automated CLI invocations |
+| D132 | Detection auto-checks CLI availability and falls back gracefully | No hard failures when CLI is unavailable; extension always works |
+
+---
+
+## 8. Security Gate
+
+**CLI Cost Control Gate:**
+- Daily token budget not exceeded (blocking: CLI invocations stop)
+- Hourly invocation limit not exceeded (blocking: new invocations queued)
+- API credentials valid and accessible (blocking: CLI disabled)
+
+**CLI Tenant Ceiling Gate:**
+- Project capabilities within tenant subscription tier ceiling
+- Container execution requires Enterprise tier (blocking)
+
+---
+
+## 9. Commands
+
+```bash
+# Environment detection
+claude --version
+claude --help
+python --version
+
+# Check CLI configuration
+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}')
+"
+
+# Token usage tracking
+python tools/agent/token_tracker.py --action summary --project-id "proj-123"
+python tools/agent/token_tracker.py --action cost --project-id "proj-123"
+
+# Example CI/CD pipeline stage (GitLab CI)
+# icdev-review:
+#   stage: review
+#   image: icdev/agent-base:latest
+#   script:
+#     - claude -p "/icdev-review" --no-interactive --output-format json
+#   variables:
+#     ANTHROPIC_API_KEY: $ANTHROPIC_API_KEY
+
+# Batch intake
+python tools/requirements/intake_engine.py \
+  --project-id "proj-123" --customer-name "Jane Smith" \
+  --customer-org "DoD PEO" --impact-level IL5 --json > session.json
+SESSION_ID=$(jq -r '.session_id' session.json)
+claude -p "/icdev-intake --session-id $SESSION_ID --batch" < sow.txt
+
+# Health check (includes CLI status)
+python tools/testing/health_check.py --json
+```

icdev/data/docs/features/phase-28-remote-command-gateway.md

@@ -0,0 +1,235 @@
+# Phase 28 — Remote Command Gateway
+
+**CUI // SP-CTI**
+
+| Field | Value |
+|-------|-------|
+| Phase | 28 |
+| Title | Remote Command Gateway |
+| Status | Implemented |
+| Priority | P2 |
+| Dependencies | Phase 21 (SaaS Multi-Tenancy), Phase 24 (DevSecOps Pipeline Security) |
+| Author | ICDEV Architect Agent |
+| Date | 2026-02-23 |
+
+---
+
+## 1. Problem Statement
+
+Field users, PMs, and ISSOs often need to issue ICDEV commands without access to a full development environment. A PM checking project status from a mobile device, an ISSO reviewing compliance posture from a tablet, or a field analyst requesting a quick security scan should not need VPN access, SSH tunnels, or the VSCode extension installed. Messaging platforms (Slack, Teams, Mattermost) are already the primary communication channels for most government and defense teams, making them a natural interface for lightweight command access.
+
+However, exposing a powerful agentic system to messaging channels introduces significant security risks. Without proper identity verification, an attacker could impersonate a legitimate user and execute commands. Without classification filtering, CUI or SECRET content could leak to channels not authorized for that classification level. Without command allowlists, destructive operations (deploy, delete) could be triggered from low-security channels. Without rate limiting, a compromised account could flood the system with automated requests. The challenge is enabling convenience without compromising the security posture that ICDEV's entire architecture is designed to protect.
+
+Phase 28 implements a Remote Command Gateway (port 8458) that receives commands from 5 messaging channels (Telegram, Slack, Teams, Mattermost, internal chat) and validates every request through an 8-gate security chain (signature, bot/replay, identity, authentication, classification, RBAC, rate limit, domain authority). Responses are filtered by Impact Level so content above a channel's maximum classification is redacted with a dashboard link. User binding is mandatory before any command execution, with a challenge-response ceremony for connected environments and admin pre-provisioning for air-gapped deployments. Air-gapped mode (`environment.mode: air_gapped`) auto-disables internet-dependent channels (Telegram, Slack, Teams), leaving only Mattermost and internal chat available.
+
+---
+
+## 2. Goals
+
+1. Enable users to **issue ICDEV commands from messaging channels** (Telegram, Slack, Teams, Mattermost, internal chat) with full security validation and audit trail
+2. Implement an **8-gate security chain** that validates every command: signature verification, bot/replay rejection, identity resolution, authentication, classification check, RBAC, rate limiting, and domain authority
+3. Enforce **IL-aware response filtering** so content above a channel's maximum classification level is redacted and replaced with a dashboard link
+4. Require **mandatory user binding** before command execution, with challenge-response ceremony (connected mode) and admin pre-provisioning (air-gapped mode)
+5. Support **air-gapped mode** (`environment.mode: air_gapped`) that auto-disables internet-dependent channels and restricts to Mattermost + internal chat
+6. Maintain a **YAML-driven command allowlist** with per-channel overrides, blocking destructive operations (deploy, init) on all remote channels by default
+7. Implement channel adapters using the **ABC pattern** (D66) so new messaging channels can be added without modifying gateway core logic
+8. Log all command executions to the **append-only audit trail** with full identity chain and classification filtering actions
+
+---
+
+## 3. Architecture
+
+### 3.1 Command Execution Flow
+
+```
+[User Message in Slack/Teams/Mattermost/Telegram/Internal Chat]
+  |
+  v
+[Channel Webhook / Adapter]
+  |
+  v
+[8-Gate Security Chain]
+  |-- Gate 1: Signature (HMAC verification of webhook payload)
+  |-- Gate 2: Bot/Replay (reject bots, reject timestamps >5min old)
+  |-- Gate 3: Identity (resolve channel user -> ICDEV user binding)
+  |-- Gate 4: Authentication (validate user is active)
+  |-- Gate 5: Classification (reject commands above channel max_il)
+  |-- Gate 6: RBAC (check role permissions for command category)
+  |-- Gate 7: Rate Limit (30/user/min, 100/channel/min)
+  |-- Gate 8: Domain Authority (check agent veto rights)
+  |
+  v
+[Command Router] -> [Tool Execution]
+  |
+  v
+[Response Filter (IL-aware redaction)]
+  |
+  v
+[Channel Reply]
+```
+
+### 3.2 Channel Support Matrix
+
+| Channel | IL Range | Environment | Identity |
+|---------|----------|-------------|----------|
+| Telegram | IL2-IL4 | Connected only | Binding ceremony (HTTPS) |
+| Slack | IL2-IL5 | Connected only | Binding ceremony (HTTPS) |
+| Teams | IL2-IL5 | Connected only | Binding ceremony (HTTPS) |
+| Mattermost | IL2-IL6 | Connected + Air-gapped | Admin pre-provision or binding |
+| Internal Chat | IL2-IL6 | Always available | Admin pre-provision / CAC-PIV |
+
+### 3.3 Air-Gapped vs Connected
+
+```
+Connected Mode:                    Air-Gapped Mode:
++-------------+                    +-------------+
+| Telegram    | <-- auto-disabled  | Telegram    | X
+| Slack       | <-- auto-disabled  | Slack       | X
+| Teams       | <-- auto-disabled  | Teams       | X
+| Mattermost  | <-- available      | Mattermost  | <-- available (REST API)
+| Internal    | <-- available      | Internal    | <-- available
++-------------+                    +-------------+
+    Config: environment.mode:          Config: environment.mode:
+            connected                          air_gapped
+```
+
+---
+
+## 4. Requirements
+
+### 4.1 Security Chain
+
+#### REQ-28-001: 8-Gate Validation
+The system SHALL validate every incoming command through an 8-gate security chain: signature verification, bot/replay rejection, identity resolution, authentication, classification check, RBAC, rate limiting, and domain authority.
+
+#### REQ-28-002: HMAC Signature Verification
+Gate 1 SHALL verify HMAC-SHA256 signatures on webhook payloads to prevent tampering.
+
+#### REQ-28-003: Replay Prevention
+Gate 2 SHALL reject commands with timestamps older than 300 seconds (5 minutes) to prevent replay attacks.
+
+#### REQ-28-004: Rate Limiting
+Gate 7 SHALL enforce per-user rate limits (30 requests/minute) and per-channel rate limits (100 requests/minute).
+
+### 4.2 Identity and Binding
+
+#### REQ-28-005: Mandatory User Binding
+The system SHALL require a verified user binding (channel user ID to ICDEV user) before any command execution. Unbound users are rejected at Gate 3 with instructions to initiate binding.
+
+#### REQ-28-006: Binding Ceremony (Connected)
+In connected environments, user binding SHALL use a challenge-response ceremony: user sends `/bind`, gateway returns an 8-character hex challenge code with 10-minute TTL, user enters the code in the ICDEV dashboard.
+
+#### REQ-28-007: Admin Pre-Provisioning (Air-Gapped)
+In air-gapped environments, the system SHALL support admin pre-provisioning of user bindings via CLI (`user_binder.py --provision`) without requiring internet connectivity.
+
+### 4.3 Classification Filtering
+
+#### REQ-28-008: IL-Aware Response Filtering
+The system SHALL detect the classification level of response content and redact any content above the channel's maximum IL, replacing it with a dashboard link.
+
+#### REQ-28-009: Never Upgrade Classification
+Response filtering SHALL never upgrade content classification. If response IL exceeds channel max_il, the content is redacted, never transmitted.
+
+### 4.4 Command Control
+
+#### REQ-28-010: YAML-Driven Allowlist
+The system SHALL maintain a YAML-driven command allowlist (`args/remote_gateway_config.yaml`) with per-channel overrides, enabling command permission changes without code modifications.
+
+#### REQ-28-011: Deploy Disabled
+The `icdev-deploy` and `icdev-init` commands SHALL be disabled on all remote channels by default. Destructive operations require dashboard or CLI access.
+
+#### REQ-28-012: Confirmation for Execute Commands
+Commands in the Execute category (icdev-test, icdev-secure, icdev-build) SHALL require user confirmation before execution on remote channels.
+
+### 4.5 Air-Gapped Mode
+
+#### REQ-28-013: Auto-Disable Internet Channels
+When `environment.mode: air_gapped`, the system SHALL auto-disable internet-dependent channels (Telegram, Slack, Teams) without requiring manual per-channel configuration.
+
+#### REQ-28-014: Mattermost REST API
+The Mattermost adapter SHALL use REST API (not WebSocket) for compatibility with proxied and air-gapped deployments (D140).
+
+---
+
+## 5. Database Schema
+
+### Tables
+
+| Table | Purpose |
+|-------|---------|
+| `remote_user_bindings` | Channel user ID to ICDEV user mappings with TTL and status |
+| `remote_command_log` | Append-only command execution log (NIST AU compliant) |
+| `remote_command_allowlist` | Per-channel command permissions and restrictions |
+
+---
+
+## 6. Tools
+
+| Tool | Purpose |
+|------|---------|
+| `tools/gateway/gateway_agent.py` | Flask gateway app on port 8458 with webhook routes |
+| `tools/gateway/security_chain.py` | 8-gate security validation pipeline |
+| `tools/gateway/command_router.py` | Command dispatch to ICDEV tools |
+| `tools/gateway/response_filter.py` | IL-aware content redaction |
+| `tools/gateway/user_binder.py` | User binding management (ceremony + pre-provision) |
+| `tools/gateway/adapters/` | Channel adapters (ABC pattern: Telegram, Slack, Teams, Mattermost, Internal) |
+
+---
+
+## 7. Architecture Decisions
+
+| ID | Decision | Rationale |
+|----|----------|-----------|
+| D133 | Channel adapters are ABC + implementations (D66 pattern) | Add new channels without modifying gateway core |
+| D134 | Air-gapped environments use internal chat + Mattermost only | IL6/SIPR cannot reach Telegram/Slack/Teams APIs |
+| D135 | Response filter strips content above channel max_il, never upgrades | Prevents CUI/SECRET leaking to unauthorized channels |
+| D136 | User binding mandatory before any command execution | Full identity chain; no anonymous remote commands |
+| D137 | Command allowlist is YAML-driven with per-channel overrides | Add/remove commands without code changes (D26 pattern) |
+| D138 | Deploy commands disabled by default on all remote channels | Destructive operations require dashboard/CLI access |
+| D139 | `environment.mode: air_gapped` auto-disables internet channels | Single config toggle; no per-channel manual disable needed |
+| D140 | Mattermost adapter uses REST API (no WebSocket) | Consistent with D20; simpler; works behind proxies |
+
+---
+
+## 8. Security Gate
+
+**Remote Command Gate:**
+- User binding required (no anonymous commands)
+- Signature verification on all webhooks (HMAC-SHA256)
+- Replay window 300 seconds maximum
+- Rate limit: 30/user/min + 100/channel/min
+- `icdev-deploy` and `icdev-init` blocked on all remote channels
+- `icdev-test`, `icdev-secure`, `icdev-build` require user confirmation
+- Response content never exceeds channel maximum IL
+- All commands logged to append-only audit trail
+
+---
+
+## 9. Commands
+
+```bash
+# Start the gateway
+python tools/gateway/gateway_agent.py
+
+# User binding management
+python tools/gateway/user_binder.py --provision \
+  --channel mattermost --channel-user-id "user123" \
+  --icdev-user-id "analyst@enclave.mil" --json
+python tools/gateway/user_binder.py --list --json
+python tools/gateway/user_binder.py --revoke <binding-id>
+
+# Gateway status
+# GET http://localhost:8458/.well-known/agent.json
+
+# Available commands from messaging channels:
+#   icdev-status     (Read, all channels, no confirmation)
+#   icdev-monitor    (Read, all channels, no confirmation)
+#   icdev-knowledge  (Read, all channels, no confirmation)
+#   icdev-comply     (Read, Slack/Teams/MM/Internal, no confirmation)
+#   icdev-query      (Read, Slack/Teams/MM/Internal, no confirmation)
+#   icdev-test       (Execute, Slack/Teams/MM/Internal, confirmation required)
+#   icdev-secure     (Execute, Slack/Teams/MM/Internal, confirmation required)
+#   icdev-intake     (Write, Internal only, confirmation required)
+#   icdev-build      (Execute, Internal only, confirmation required)
+#   icdev-deploy     (Execute, DISABLED on all remote channels)
+```