icdev 1.2.11__tar.gz → 1.2.12__tar.gz

icdev-1.2.12/CHANGELOG.md

@@ -0,0 +1,195 @@
+# [TEMPLATE: CUI // SP-CTI]
+
+# Changelog
+
+All notable changes to ICDEV™ are documented in this file.
+
+Format based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [1.2.8] - 2026-03-31
+
+### Added
+- **Network Design Canvas** — ACAS/Nessus vulnerability scan overlay with host-to-node matching and severity heat maps
+- **Network Design Canvas** — Natural language topology queries powered by deterministic graph algorithms (NetworkX) with local LLM fallback
+- **Network Design Canvas** — Cloud architecture diagram generation for all 6 CSPs
+- **Network Design Canvas** — Compliance audit page with per-device STIG tracking and exportable checklists
+- **Network Design Canvas** — 1,000+ device types, protocols, and interface constants
+- **Network Design Canvas** — Enhanced inventory export (CSV, JSON, YAML) with advanced filtering
+- **IBM Cloud IaC** — New Terraform generator for IBM Cloud (VPC, IKS, KMS, COS, LogDNA, SysDig)
+- **Azure IaC** — Major expansion: AKS, Key Vault, Front Door, Application Gateway, NSG rules
+- **GCP IaC** — Major expansion: GKE, Cloud KMS, Cloud Armor, VPC Service Controls
+- **OCI IaC** — Major expansion: OKE, Vault, WAF, Network Security Groups, Bastion
+- **SRE Operations** — Dashboard, runbook library, incident tracking, toil budgets, SLO monitoring
+- **Pipeline Canvas** — Visual CI/CD pipeline designer with drag-and-drop stages and YAML export
+
+## [Unreleased]
+
+### Added
+- Comprehensive test suite expansion (324+ new tests across 21 test files)
+- CI/CD pipeline for ICDEV™ itself (GitHub Actions + GitLab CI)
+- REST API endpoints for Phases 22-28 capabilities
+- Helm chart completion for all 15 agents
+- Project documentation (README, CONTRIBUTING, CHANGELOG)
+
+## [Phase 29-32] - 2026-02-XX
+
+### Added
+- Dashboard authentication with per-user API keys and SHA-256 hashing (D169-D172)
+- RBAC with 5 roles: admin, pm, developer, isso, co (D172)
+- Activity feed merging audit trail and hook events via UNION ALL query (D174)
+- BYOK (Bring Your Own Key) LLM key management with Fernet AES-256 encryption (D175-D178)
+- Usage tracking and cost dashboard per-user and per-provider (D177)
+- Spec-kit pattern tools: quality checker, consistency analyzer, constitution manager, clarification engine, spec organizer (D156-D161)
+- Proactive monitoring heartbeat daemon with 7 configurable checks (D162-D163)
+- Auto-resolver for webhook-triggered issue fix with branch/PR creation (D164-D166)
+- Selective skill injection via deterministic keyword-based category matching (D167)
+- Time-decay memory ranking with exponential formula and per-type half-lives (D168)
+- Resilience patterns: circuit breaker (3-state machine), retry with exponential backoff, correlation IDs (D146-D149)
+- Database migration runner with checksum validation and multi-tenant support (D150-D151)
+- Database backup and restore with optional AES-256-CBC encryption (D152)
+- OpenAPI 3.0.3 spec with Swagger UI for the API gateway (D153)
+- Prometheus metrics endpoint with 8 metrics (D154)
+- Cross-platform compatibility module for Windows, macOS, Linux (D145)
+- CUI markings added to all Python files
+
+### Changed
+- Dashboard login page updated for API key authentication flow
+- Settings page expanded with LLM key management section
+- Team management page updated with role-based controls
+
+## [Phase 23-28] - 2026-01-XX
+
+### Added
+- Universal Compliance Platform with 10 data categories and composable markings (D109)
+- Dual-hub crosswalk model: NIST 800-53 (US) + ISO 27001 (international) with bidirectional bridge (D111)
+- 6 Wave 1 compliance frameworks: CJIS, HIPAA, HITRUST CSF v11, SOC 2 Type II, PCI DSS v4.0, ISO/IEC 27001:2022 (D116)
+- Compliance auto-detection from data types with ISSO confirmation gate (D110)
+- Multi-regime assessment with crosswalk deduplication (D113)
+- BaseAssessor ABC pattern reducing per-framework code to approximately 60 LOC (D116)
+- DevSecOps profile management with 10 stages and 5 maturity levels (D119)
+- Pipeline security generation with Kyverno and OPA policy-as-code (D121)
+- Image signing and attestation management
+- Zero Trust Architecture: 7-pillar maturity scoring aligned to DoD ZTA Strategy (D120)
+- NIST SP 800-207 compliance assessment and gate (D118)
+- Service mesh generation for Istio and Linkerd (D121)
+- Network segmentation with namespace isolation and microsegmentation
+- PDP/PEP configuration for DISA ICAM, Zscaler, Palo Alto (D124)
+- ZTA posture score as cATO evidence dimension (D123)
+- DoD MOSA compliance framework (10 U.S.C. section 4401) via BaseAssessor pattern (D127)
+- Modularity analysis: coupling, cohesion, circular dependency detection (D129)
+- ICD and TSP document generation with CUI markings (D128)
+- MOSA code enforcement via static analysis (D129)
+- MOSA auto-trigger for DoD/IC customers during intake (D125)
+- CLI capabilities with 4 independent optional toggles and tenant ceiling (D132)
+- Remote Command Gateway with 5 channel adapters: Telegram, Slack, Teams, Mattermost, internal chat (D133)
+- 8-gate security chain for remote commands (D136)
+- IL-aware response filtering (D135)
+- User binding ceremony for remote command authorization (D136)
+- Air-gapped mode auto-disabling internet-dependent channels (D139)
+- Command allowlist with per-channel overrides (D137)
+- Auto-scaling: HPA manifests for all 15 agents + dashboard + API gateway (D141)
+- Pod Disruption Budgets with tier-based policies (D143)
+- Cross-AZ topology spread constraints (D144)
+- Cloud-agnostic node autoscaler reference (D142)
+
+## [Phase 19-22] - 2026-01-XX
+
+### Added
+- Agentic application generation producing mini-ICDEV™ clone child applications (D44-D53)
+- 6-dimension fitness scoring for agentic suitability assessment (D46)
+- Blueprint-driven generation with 12-step pipeline (D47)
+- Grandchild prevention mechanism (D52)
+- CSP MCP integration registry for AWS, GCP, Azure, Oracle
+- FIPS 199 security categorization with SP 800-60 information types and high watermark (D54)
+- FIPS 200 validation across all 17 minimum security areas (D55)
+- CNSSI 1253 overlay auto-application for IL6/SECRET (D57)
+- Dynamic SSP baseline selection from categorization (D56)
+- SaaS multi-tenancy platform with API gateway (D58-D65)
+- Per-tenant database isolation with strongest isolation model (D60)
+- 3 authentication methods: API key, OAuth 2.0/OIDC, CAC/PIV
+- 3 subscription tiers: Starter, Professional, Enterprise
+- REST API and MCP Streamable HTTP transport (D62)
+- Per-tenant K8s namespace provisioning (D63)
+- Offline license keys with RSA-SHA256 signatures for on-prem (D64)
+- Helm chart for on-prem deployment (D65)
+- Federated FORGE marketplace with 3-tier catalog (D74-D81)
+- 7-gate automated security scanning for marketplace assets (D76)
+- IL-aware compatibility checking with high-watermark consumption rule (D77)
+- Community ratings and reviews for marketplace assets
+- Marketplace SBOM generation for executable assets (D81)
+- LLM provider abstraction with vendor-agnostic routing (D66-D73)
+- Function-level LLM routing for best-of-breed model selection (D68)
+- Ollama support for air-gapped environments (D69)
+- Vision LLM support for diagram extraction and UI analysis (D82-D87)
+
+## [Phase 13-18] - 2025-XX-XX
+
+### Added
+- ATO acceleration: FedRAMP Moderate/High, CMMC Level 2/3, OSCAL generation (Phase 17)
+- eMASS bidirectional sync with hybrid mode
+- cATO continuous monitoring with evidence freshness tracking
+- PI compliance velocity tracking
+- Control crosswalk engine with dual-hub model
+- Classification manager for IL2 through IL6
+- MBSE integration: SysML XMI import, DOORS NG ReqIF import (Phase 18)
+- Digital thread with auto-linking and coverage reporting
+- Model-code generation from SysML block definitions
+- Model-code drift detection and sync engine
+- DoDI 5000.87 Digital Engineering Strategy compliance assessment
+- Diagram extraction from SysML screenshots via vision LLM
+- Application modernization: 7Rs assessment framework
+- Version migration (Python 2.7 to 3.11, Java 8 to 17, etc.)
+- Framework migration (Struts to Spring Boot, etc.)
+- Monolith decomposition with microservice extraction
+- Database migration DDL planning
+- Strangler fig pattern management
+- ATO compliance bridge for migration tracking
+
+## [Phase 7-12] - 2025-XX-XX
+
+### Added
+- RICOAS Requirements Intake: conversational AI-driven intake with 5-stage pipeline
+- Gap detection across 5 dimensions (completeness, clarity, feasibility, compliance, testability)
+- SAFe decomposition: Epic, Capability, Feature, Story, Enabler with WSJF scoring
+- Document extraction from SOW/CDD/CONOPS (shall/must/should statements)
+- ATO boundary impact assessment with 4-tier classification (GREEN/YELLOW/ORANGE/RED)
+- Supply chain intelligence: dependency graph, ISA lifecycle, SCRM assessment, CVE triage
+- Digital Program Twin simulation: 6-dimension what-if analysis
+- Monte Carlo estimation for schedule and cost
+- COA generation (Speed/Balanced/Comprehensive) with comparison and selection
+- External integration: bidirectional Jira, ServiceNow, GitLab sync
+- DOORS NG ReqIF export
+- Approval workflow management
+- RTM traceability builder
+- CI/CD integration: GitHub webhooks, GitLab webhooks, issue polling
+- Observability: hook-based agent monitoring, HMAC-signed events, SIEM forwarding
+- NLQ compliance queries via Bedrock with read-only SQL enforcement
+- Parallel CI/CD via git worktree task isolation
+
+## [Phase 1-6] - 2025-XX-XX
+
+### Added
+- Initial ICDEV™ platform with FORGE 6-layer agentic framework
+- ANVIL and M-ANVIL build workflows (Architect, Navigate, Verify, Integrate, Launch)
+- 15 multi-agent architecture across 3 tiers (Core, Domain, Support)
+- A2A protocol (JSON-RPC 2.0 over mutual TLS) for inter-agent communication
+- 14 MCP servers for Claude Code integration (stdio transport)
+- Memory system: dual storage (markdown + SQLite), hybrid search (BM25 + semantic)
+- Project management: create, list, status tracking
+- TDD workflow: RED, GREEN, REFACTOR cycle with 6 language support
+- Builder tools: scaffolding, code generation, linting, formatting
+- NIST 800-53 Rev 5 compliance: SSP, POAM, STIG checklist, SBOM generation
+- CUI marking system for IL4/IL5/IL6 artifacts
+- DoD CSSP (DI 8530.01) compliance assessment
+- CISA Secure by Design assessment
+- IEEE 1012 IV&V assessment
+- Security scanning: SAST (Bandit), dependency audit, secret detection, container scanning
+- Infrastructure generation: Terraform, Ansible, K8s manifests, CI/CD pipelines
+- Knowledge base with self-healing pattern detection
+- Monitoring: log analysis, metrics, alerts, health checks
+- Web dashboard with Flask (project status, compliance, security, agent management)
+- STIG-hardened Docker containers for all agents
+- Kubernetes manifests with network policies (default deny)
+- Audit trail: append-only, immutable, NIST AU compliant
+
+# [TEMPLATE: CUI // SP-CTI]

icdev-1.2.12/CLAUDE.md

@@ -0,0 +1,210 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+---
+
+## Quick Reference
+
+### Essential Commands
+```bash
+# Initialize framework (first run)
+/initialize
+
+# Session start
+python tools/memory/memory_read.py --format markdown
+python tools/project/session_context_builder.py --format markdown
+
+# Memory
+python tools/memory/memory_write.py --content "text" --type event
+python tools/memory/hybrid_search.py --query "query"
+
+# LLM Provider
+python -c "from tools.llm.router import LLMRouter; r = LLMRouter(); print(r.get_provider_for_function('code_generation'))"
+# Config: args/llm_config.yaml — providers, models, routing, embeddings
+
+# Database
+python tools/db/init_icdev_db.py
+python tools/db/storage.py --health --json
+
+# Testing
+python tools/testing/health_check.py --json
+python tools/testing/test_orchestrator.py --project-dir /path/to/project
+python tools/testing/e2e_runner.py --run-all
+
+# Companion sync (ALWAYS after code changes)
+python tools/dx/companion.py --sync --write --json
+
+# Coherence check
+python tools/workflow/coherence_checker.py --all --fix --gate
+```
+
+### Python Dependencies
+See `requirements.txt`. Key: sqlite3, pathlib, json (stdlib); openai, anthropic, python-dotenv (optional); pyyaml, jinja2, flask, pytest (ICDEV™).
+
+> **Full command reference:** See [docs/reference/commands.md](docs/reference/commands.md) for all CLI commands across every ICDEV™ module.
+
+---
+
+## Architecture: FORGE Framework
+
+6-layer agentic system. AI orchestrates; tools execute deterministically.
+
+| Layer | Directory | Role |
+|-------|-----------|------|
+| **Goals** | `goals/` | Process definitions — what to achieve, which tools, expected outputs |
+| **Orchestration** | *(you)* | Read goal → decide tool order → apply args → handle errors |
+| **Tools** | `tools/` | Python scripts, one job each. Deterministic. Don't think, just execute. |
+| **Args** | `args/` | YAML/JSON behavior settings. Change behavior without editing goals/tools |
+| **Context** | `context/` | Static reference material (tone rules, writing samples, case studies) |
+| **Hard Prompts** | `hardprompts/` | Reusable LLM instruction templates |
+
+**Why:** LLMs are probabilistic. Business logic must be deterministic. 90% accuracy/step = ~59% over 5 steps.
+
+### Key Files
+- `goals/manifest.md` — Index of all goal workflows. Check before starting any task.
+- `tools/manifest.md` — Master list of all tools. Check before writing a new script.
+- `memory/MEMORY.md` — Curated long-term facts/preferences.
+- `.env` — API keys, LLM model names. **Admins configure LLM here, not in code.**
+- `.tmp/` — Disposable scratch work. Never store important data here.
+
+---
+
+## How to Operate
+
+1. **Check goals first** — Read `goals/manifest.md` before starting a task. If a goal exists, follow it.
+2. **Check tools first** — Read `tools/manifest.md` before writing new code. If you create a new tool, add it to the manifest.
+3. **When tools fail** — Read the error, fix the tool, update the goal with what you learned.
+4. **Goals are living docs** — Update when better approaches emerge. Never modify/create without permission.
+5. **When stuck** — Explain what's missing. Don't guess or invent capabilities.
+
+### Session Start Protocol
+1. Read `memory/MEMORY.md` for long-term context
+2. Read today's daily log (`memory/logs/YYYY-MM-DD.md`)
+3. Read yesterday's log for continuity
+4. Or run: `python tools/memory/memory_read.py --format markdown`
+5. Load project context: `python tools/project/session_context_builder.py --format markdown`
+
+### First Run
+If `memory/MEMORY.md` doesn't exist, this is a fresh environment. Run `/initialize`.
+
+---
+
+## Guardrails
+
+- Always check `tools/manifest.md` before writing a new script
+- Verify tool output format before chaining into another tool
+- Don't assume APIs support batch operations — check first
+- When a workflow fails mid-execution, preserve intermediate outputs before retrying
+- Read the full goal before starting a task — don't skim
+- **NEVER DELETE YOUTUBE VIDEOS** — Irreversible.
+- When adding an append-only/immutable DB table, ALWAYS add it to `APPEND_ONLY_TABLES` in `.claude/hooks/pre_tool_use.py`
+- When adding a new dashboard page route, ALWAYS add it to the `Pages:` line in `.claude/commands/start.md`
+- Screenshots: ALWAYS use `playwright/screenshots/<name>.png` as the filename
+- In Jinja2 templates, NEVER use `'%%.0f'|format(value)` — use `value|round(0)|int`
+- In Behave step definitions, match step text to tool return signatures
+- SQL CHECK constraints: derive from Python constants, never hardcode
+- Entity types: add to BOTH the Python constant AND the SQL CHECK constraint
+- Child apps: ALWAYS use `child_app_generator.py` + `forge_validator.py --gate`
+- Before writing tests: ALWAYS run `api_surface_extractor.py --file <module> --json`
+- **Cross-platform:** pathlib.Path, `encoding='utf-8'`, `tempfile.gettempdir()`, `datetime.now(timezone.utc)`, `hashlib.sha256` not md5
+- **LLM config via `.env`**, never hardcode model IDs in Python
+- **New tool/module registration checklist (8 points):**
+  1. `tools/manifest.md` — add tool entry
+  2. `CLAUDE.md` — add CLI commands to [docs/reference/commands.md](docs/reference/commands.md)
+  3. `args/security_gates.yaml` — add gate if blocking/warning conditions
+  4. `tools/mcp/tool_registry.py` + `gap_handlers.py` — register in MCP gateway
+  5. `.claude/hooks/pre_tool_use.py` — add append-only tables
+  6. `tests/conftest.py` — add new table schemas to MINIMAL_ICDEV_SCHEMA
+  7. `python tools/dx/companion.py --sync --write --json` — sync to all AI platforms
+  8. `python tools/workflow/coherence_checker.py --all --fix --gate` — coherence validation
+
+---
+
+## ICDEV™ System — Intelligent Certified Development
+
+Meta-builder that autonomously builds Gov/DoD applications using FORGE + ANVIL workflow. Full SDLC with TDD/BDD, NIST 800-53 RMF compliance, and self-healing.
+
+### Environment
+- **Classification:** CUI // SP-CTI (IL4/IL5), SECRET (IL6)
+- **Impact Levels:** IL2 (Public), IL4 (CUI/GovCloud), IL5 (CUI/Dedicated), IL6 (SECRET/SIPR)
+- **Cloud:** Multi-cloud — AWS GovCloud, Azure Government, GCP, OCI, IBM, Local
+- **LLM:** Multi-cloud — Bedrock, Azure OpenAI, Vertex AI, OCI GenAI, watsonx.ai, Ollama
+- **Languages:** Python, Java, JavaScript/TS, Go, Rust, C# (6 first-class)
+- **CI/CD:** GitLab | **Orchestration:** K8s/OpenShift | **IaC:** Terraform + Ansible
+
+### Multi-Agent Architecture
+15 agents across 3 tiers (Core, Domain, Support) on ports 8443-8458. See [docs/reference/architecture.md](docs/reference/architecture.md).
+
+### Memory System
+Dual storage: markdown (human-readable) + SQLite (searchable).
+- `data/memory.db` — entries, daily logs, access log
+- `data/activity.db` — task tracking
+- Types: fact, preference, event, insight, task, relationship
+- Search: hybrid_search.py (0.7 BM25 + 0.3 semantic)
+
+### Self-Healing
+- **≥ 0.7** confidence → auto-remediate (max 5/hour)
+- **0.3–0.7** → suggest fix, require approval
+- **< 0.3** → escalate with full context
+
+### Databases
+| Database | Purpose |
+|----------|---------|
+| `data/icdev.db` | Main operational DB (391 tables) |
+| `data/platform.db` | SaaS platform DB |
+| `data/tenants/{slug}.db` | Per-tenant isolated DB |
+| `data/memory.db` | Memory system |
+| `data/activity.db` | Task tracking |
+
+Audit trail is **append-only/immutable** (NIST AU). Full schema: [docs/reference/databases.md](docs/reference/databases.md).
+
+---
+
+## ICDEV™ Guardrails
+
+- All artifacts MUST include classification markings (CUI for IL4/IL5, SECRET for IL6)
+- Use `classification_manager.py` for markings — don't hard-code CUI banners
+- Audit trail is append-only — NEVER UPDATE/DELETE audit tables
+- Security gates block on: CAT1 STIG, critical/high vulns, failed tests, missing markings
+- When implementing NIST 800-53 control, call crosswalk engine for FedRAMP/CMMC auto-populate
+- Self-healing limited to confidence ≥ 0.7 and max 5/hour
+- All A2A uses mutual TLS; never store secrets in code
+- SBOM regenerated on every build; containers non-root, read-only rootfs
+- IL6/SECRET: SIPR-only, NSA Type 1 encryption, air-gapped CI/CD
+- **V&V before handoff** — if change affects UI, verify with Playwright MCP before reporting
+- **Playwright E2E after dashboard changes** — mandatory post-implementation verification
+- **Feature docs** — create `docs/features/phase-{N}-{slug}.md` after each phase
+
+---
+
+## Security Gates (Summary)
+
+Gates block on critical conditions. Full definitions: [docs/reference/compliance-security.md](docs/reference/compliance-security.md).
+
+Key gates: Code Review, Merge, Deploy, FedRAMP, CMMC, cATO, DES, Migration, RICOAS, Supply Chain, FIPS 199/200, Marketplace, Multi-Regime, DevSecOps, ZTA, MOSA, AI Security, RAG, Fine-Tuning, Coherence, Acceptance Validation.
+
+---
+
+## Reference Documentation
+
+Detailed reference material (read on-demand, not loaded automatically):
+
+| File | Contents |
+|------|----------|
+| [commands.md](docs/reference/commands.md) | All CLI commands for every ICDEV™ module |
+| [architecture.md](docs/reference/architecture.md) | Agents, MCP servers, languages, skills, deployment, scaling, installation |
+| [adrs.md](docs/reference/adrs.md) | All architecture decision records (D1–D360+) |
+| [compliance-security.md](docs/reference/compliance-security.md) | Compliance frameworks, crosswalk, security gates, args config |
+| [subsystems.md](docs/reference/subsystems.md) | Innovation, Creative, Research engines; RICOAS; SaaS; Marketplace; CI/CD |
+| [goals.md](docs/reference/goals.md) | All existing goal workflows with descriptions |
+| [testing.md](docs/reference/testing.md) | Testing framework, test commands, E2E specs |
+| [databases.md](docs/reference/databases.md) | Database tables, schemas, migration commands |
+
+---
+
+## Continuous Improvement
+
+Every failure strengthens the system: identify what broke → fix the tool → test it → update the goal → next run succeeds automatically.
+
+Be direct. Be reliable. Get shit done.

icdev-1.2.12/CONTRIBUTING.md

@@ -0,0 +1,271 @@
+# Contributing to ICDEV™
+
+Thank you for contributing to ICDEV™. This document covers the development setup,
+coding standards, testing patterns, and contribution workflow.
+
+## Developer Certificate of Origin (DCO)
+
+All contributions to this project **must** be signed off under the
+[Developer Certificate of Origin (DCO) v1.1](https://developercertificate.org/).
+
+By making a contribution, you certify that you have the right to submit it
+under the Apache 2.0 license and that you have not incorporated code from
+incompatible licenses (GPL, AGPL, SSPL — see [Dependency Guidelines](#dependency-guidelines)).
+
+### How to Sign Off
+
+Add a `Signed-off-by` line to every commit message:
+
+```
+Signed-off-by: Your Name <your.email@example.com>
+```
+
+You can do this automatically with `git commit -s`:
+
+```bash
+git commit -s -m "feat: add new compliance framework assessor"
+```
+
+**Commits without a DCO sign-off will not be accepted.**
+
+## Development Setup
+
+### Prerequisites
+
+- Python 3.9 or later
+- Git
+- (Optional) Node.js 18+ for Playwright E2E tests
+
+### Installation
+
+```bash
+git clone <repository-url>
+cd ICDev
+pip install -r requirements.txt
+```
+
+### First Run
+
+If `memory/MEMORY.md` does not exist, this is a fresh environment. Run `/initialize` in Claude Code to set up all directories, manifests, memory files, and databases.
+
+### Verify Installation
+
+```bash
+# Run the test suite
+pytest tests/ -v --tb=short
+
+# Check platform compatibility
+python tools/testing/platform_check.py
+
+# Full system health check
+python tools/testing/health_check.py
+```
+
+## Adding a New Tool
+
+1. **Check the manifest first.** Read `tools/manifest.md` to confirm a similar tool does not already exist.
+2. **Create the tool** in the appropriate domain directory under `tools/<domain>/`.
+3. **Add a template classification header** as the first line of the file:
+   ```python
+   # [TEMPLATE: CUI // SP-CTI]
+   ```
+   This is a template marker showing the format ICDEV™ applies to generated
+   artifacts. It does NOT indicate the file itself is CUI. See
+   [Classification Markers](#classification-markers) below.
+4. **Add the tool to `tools/manifest.md`** with its name, path, purpose, and CLI usage.
+5. **Write tests** in `tests/test_<name>.py`.
+6. **Update `CLAUDE.md`** — add the tool's CLI commands to the appropriate section.
+7. **Support `--json` output** for programmatic usage and `--human` for colored terminal output.
+
+### Tool Design Principles
+
+- **One job per tool.** Tools are deterministic Python scripts. They do not think; they execute.
+- **No side effects.** Tools should not modify state outside their declared scope.
+- **Audit trail.** Any state-changing operation must log to the append-only audit trail.
+- **Air-gap safe.** Use only Python stdlib or approved dependencies. No internet-dependent features in core logic.
+- **Classification markings for generated output.** Use `classification_manager.py` for all marking generation in artifacts ICDEV™ produces — do not hard-code CUI banners.
+
+## Test Patterns
+
+ICDEV™ uses a 9-step testing pipeline:
+
+1. **py_compile** — Python syntax validation (catches missing colons, bad indentation before tests run)
+2. **Ruff** (`ruff>=0.12`) — Ultra-fast Python linter (replaces flake8+isort+black)
+3. **pytest** (`tests/`) — Unit and integration tests with coverage
+4. **behave/Gherkin** (`features/`) — BDD scenario tests for business requirements
+5. **Bandit** — SAST security scan (SQL injection, XSS, hardcoded secrets)
+6. **Playwright MCP** (`.claude/commands/e2e/*.md`) — Browser automation E2E tests
+7. **Vision validation** (optional) — LLM-based screenshot analysis
+8. **Acceptance validation** (V&V) — Deterministic acceptance criteria verification
+9. **Security + Compliance gates** — CUI markings on generated artifacts, STIG (0 CAT1), secret detection
+
+### Writing a Test File
+
+```python
+# [TEMPLATE: CUI // SP-CTI]
+"""Tests for <module_name>."""
+
+import os
+import sys
+import pytest
+
+# Import guard for optional dependencies
+try:
+    from tools.some_module import SomeClass
+except ImportError:
+    pytestmark = pytest.mark.skip(reason="Missing dependency")
+
+
+class TestSomeFeature:
+    """Tests for the SomeFeature behavior group."""
+
+    def test_basic_operation(self, tmp_path):
+        """Verify basic operation succeeds."""
+        result = SomeClass().do_something(tmp_path)
+        assert result["status"] == "success"
+
+    def test_error_handling(self, tmp_path):
+        """Verify errors are handled gracefully."""
+        result = SomeClass().do_something_invalid(tmp_path)
+        assert result["status"] == "error"
+        assert "message" in result
+```
+
+**Key conventions:**
+
+- **Header:** `# [TEMPLATE: CUI // SP-CTI]` as the first line.
+- **Import guard:** Use `try/except ImportError` with `pytestmark = pytest.mark.skip()` for optional dependencies.
+- **One class per behavior group.** Group related tests in a class.
+- **Plain assert statements.** Do not use `unittest`-style `self.assert*` methods.
+- **Use `tmp_path`** for filesystem operations. Use the `icdev_db` fixture for database tests.
+- **Use the shared fixtures** from `conftest.py`: `icdev_db`, `platform_db`, `api_gateway_app`, `dashboard_app`, `auth_headers`.
+
+### Running Tests
+
+```bash
+# All tests
+pytest tests/ -v --tb=short
+
+# Single test file
+pytest tests/test_rest_api.py -v
+
+# Single test
+pytest tests/test_rest_api.py::TestSomeClass::test_method -v
+
+# With coverage
+pytest tests/ --cov=tools --cov-report=term-missing
+
+# BDD tests
+behave features/
+
+# E2E tests
+python tools/testing/e2e_runner.py --run-all
+```
+
+## Adding BDD Scenarios
+
+1. **Add a scenario** to `features/<name>.feature` using Gherkin syntax:
+   ```gherkin
+   Feature: User authentication
+     Scenario: Valid API key grants access
+       Given a valid API key exists
+       When the user authenticates with the key
+       Then the response status is 200
+   ```
+
+2. **Create or update step definitions** in `features/steps/<name>_steps.py`.
+
+3. **Use `subprocess.run`** for tool invocation in step definitions to keep BDD tests isolated from internal imports.
+
+4. **Run BDD tests:**
+   ```bash
+   behave features/
+   behave features/<name>.feature
+   ```
+
+## Adding a Compliance Framework
+
+1. **Create the catalog** as a JSON file in `context/compliance/`.
+2. **Create an assessor** that inherits from `BaseAssessor` (see `tools/compliance/base_assessor.py`).
+3. **Add crosswalk mappings** to the dual-hub model (NIST 800-53 US hub or ISO 27001 international hub).
+4. **Register in `args/framework_registry.yaml`**.
+5. **Add data type triggers** in `args/classification_config.yaml` if applicable.
+6. **Write tests** in `tests/test_<framework>_assessor.py`.
+7. **Update `CLAUDE.md`** with the new framework's commands and gate conditions.
+
+The `BaseAssessor` pattern (D116) provides crosswalk integration, gate evaluation, and CLI support in approximately 60 lines of code per new framework.
+
+## Commit Message Format
+
+```
+<agent>: <type>: <message>
+
+Signed-off-by: Your Name <your.email@example.com>
+```
+
+**Types:**
+- `feat` — A new feature
+- `fix` — A bug fix
+- `chore` — Maintenance, refactoring, documentation
+
+**Examples:**
+```
+icdev_builder: feat: Add CJIS assessor framework
+
+Signed-off-by: Jane Doe <jane@example.com>
+```
+
+## Classification Markers
+
+ICDEV™ source files use **template markers** in their headers:
+
+```python
+# [TEMPLATE: CUI // SP-CTI]
+```
+
+These template markers demonstrate the classification format that ICDEV™ applies
+to artifacts it generates for its users. **They do NOT indicate that the source
+file itself is CUI or classified.** See the [README.md](README.md) disclaimer.
+
+When ICDEV™ generates artifacts for a project (SSPs, POAMs, code files, etc.),
+it applies actual classification markings appropriate to the project's impact
+level using `tools/compliance/classification_manager.py`. The template markers
+in the ICDEV™ source code itself serve as documentation of this format.
+
+## Dependency Guidelines
+
+- Prefer Python stdlib where possible (air-gap safe)
+- **Do not add GPL, AGPL, or SSPL licensed dependencies** without explicit
+  discussion and approval. ICDEV™ blocks copyleft licenses (see D202 in CLAUDE.md).
+- New dependencies must be added to `requirements.txt` with version pins.
+- Run `pip-licenses -f markdown` to verify license compatibility before submitting.
+
+## Security Guidelines
+
+- **Never store secrets** in code or config files. Use AWS Secrets Manager or K8s secrets.
+- **Audit trail is append-only.** Never add UPDATE or DELETE operations to audit tables.
+- **All containers** must run as non-root with read-only root filesystem.
+- **SBOM** must be regenerated on every build.
+- **Security gates block on:** CAT1 STIG findings, critical/high vulnerabilities, failed tests, detected secrets.
+
+## Architecture Decision Records
+
+Key decisions are documented as numbered records (D1, D2, ...) in `CLAUDE.md`. When making architectural choices, reference existing ADRs or propose new ones. Important patterns:
+
+- **D6:** Audit trail is append-only/immutable (no UPDATE/DELETE)
+- **D26:** Declarative JSON/YAML for configuration (add rules without code changes)
+- **D58:** SaaS layer wraps existing tools, does not rewrite them
+- **D66:** Provider abstraction pattern (ABC + implementations)
+- **D116:** BaseAssessor ABC pattern for compliance frameworks
+
+## Getting Help
+
+- Read `CLAUDE.md` for the complete architecture documentation and command reference.
+- Read `goals/manifest.md` for the index of all workflow goals.
+- Read `tools/manifest.md` for the master list of all tools.
+- Open an issue for questions or proposals.
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the
+Apache License, Version 2.0. See [LICENSE](LICENSE).