icdev 1.0.0__py3-none-any.whl

icdev/data/docs/features/phase-03-tdd-bdd-testing.md

@@ -0,0 +1,261 @@
+# Phase 3 — TDD/BDD Testing Framework
+
+**CUI // SP-CTI**
+
+| Field | Value |
+|-------|-------|
+| Phase | 3 |
+| Title | TDD/BDD Testing Framework |
+| Status | Implemented |
+| Priority | P0 |
+| Dependencies | Phase 1 (GOTCHA Framework Foundation), Phase 2 (ATLAS Build Workflow) |
+| Author | ICDEV Architect Agent |
+| Date | 2026-02-23 |
+
+---
+
+## 1. Problem Statement
+
+Code without tests is a liability. In government and DoD environments, untested code does not ship. The cost of defects increases exponentially the later they are discovered in the development lifecycle -- a bug caught during testing costs 10x less than one caught in production, and 100x less than one discovered during an Authority to Operate (ATO) assessment or post-deployment incident.
+
+Most AI-assisted development workflows generate code first and tests as an afterthought (if at all). This produces tests that merely confirm the implementation rather than defining the contract. The resulting code is brittle, untestable by design, and fails to meet the coverage requirements mandated by DoD quality standards.
+
+ICDEV enforces strict Test-Driven Development (TDD) with the iron rule: **no code is written until a failing test demands it**. This is implemented through a RED-GREEN-REFACTOR cycle where Gherkin/BDD feature files define behavior in business language, pytest test cases provide technical verification, and implementation code is generated as the minimum needed to satisfy the tests. The cycle is logged to an immutable audit trail for compliance traceability.
+
+---
+
+## 2. Goals
+
+1. Enforce strict TDD discipline: write failing tests first (RED), write minimum code to pass (GREEN), then clean up (REFACTOR)
+2. Generate Gherkin/BDD feature files from requirements with minimum 3 scenarios per feature (happy path, error case, edge case)
+3. Generate pytest test cases following the Arrange-Act-Assert pattern with independent, behavior-named tests
+4. Require 0 test failures and minimum 80% code coverage (target 90%+) before proceeding
+5. Integrate linting (flake8/ruff) and formatting (black/prettier) in the REFACTOR phase with mandatory test re-run after cleanup
+6. Log every TDD cycle to the append-only audit trail for compliance traceability (NIST AU controls)
+7. Support 6 first-class languages: Python, Java, JavaScript/TypeScript, Go, Rust, C#
+
+---
+
+## 3. Architecture
+
+### 3.1 TDD Cycle
+
+```
++-------------------------------------------------------------------+
+|                        TDD CYCLE                                   |
+|                                                                    |
+|  +-------------------+                                             |
+|  |    RED            |  1. Write Gherkin feature file              |
+|  |    (Write Tests)  |  2. Generate pytest test cases              |
+|  |                   |  3. Run tests -- ALL MUST FAIL              |
+|  +--------+----------+                                             |
+|           |                                                        |
+|           v                                                        |
+|  +-------------------+                                             |
+|  |    GREEN          |  4. Generate minimum implementation code    |
+|  |    (Make Pass)    |  5. Run tests -- ALL MUST PASS              |
+|  |                   |     Coverage >= 80%                         |
+|  +--------+----------+                                             |
+|           |                                                        |
+|           v                                                        |
+|  +-------------------+                                             |
+|  |    REFACTOR       |  6. Lint (flake8/ruff) + Format (black)     |
+|  |    (Clean Up)     |     Re-run tests -- STILL MUST PASS         |
+|  |                   |  7. Log to audit trail                      |
+|  +--------+----------+                                             |
+|           |                                                        |
+|           v                                                        |
+|     Next requirement                                               |
+|     or Feature complete                                            |
++-------------------------------------------------------------------+
+```
+
+### 3.2 Tool Pipeline
+
+```
+Orchestrator
+    |
+    +--> test_writer.py (Gherkin + pytest generation)
+    |       |
+    |       +--> Feature file: features/<name>.feature
+    |       +--> Unit tests: tests/unit/test_<name>.py
+    |       +--> Integration tests: tests/integration/test_<name>_integration.py
+    |       +--> Step definitions: tests/features/steps/<name>_steps.py
+    |
+    +--> pytest (RED: verify all tests FAIL)
+    |
+    +--> code_generator.py (minimum implementation)
+    |       |
+    |       +--> src/<module>.py
+    |
+    +--> pytest + coverage (GREEN: verify all tests PASS, >= 80%)
+    |
+    +--> linter.py (flake8/ruff with --fix)
+    |
+    +--> formatter.py (black/prettier)
+    |
+    +--> pytest (REFACTOR: verify tests STILL pass)
+    |
+    +--> audit_logger.py (log TDD cycle to audit trail)
+```
+
+### 3.3 Multi-Language Support
+
+| Language | Test Framework | BDD Framework | Linter | Formatter |
+|----------|---------------|---------------|--------|-----------|
+| Python | pytest | behave | flake8/ruff | black+isort |
+| Java | JUnit | Cucumber-JVM | checkstyle/PMD | google-java-format |
+| JavaScript/TS | Jest/Mocha | cucumber-js | eslint+tsc | prettier |
+| Go | go test | godog | golangci-lint | gofmt |
+| Rust | cargo test | cucumber-rs | clippy | rustfmt |
+| C# | NUnit/xUnit | SpecFlow | dotnet analyzers | dotnet format |
+
+---
+
+## 4. Requirements
+
+### 4.1 RED Phase (Test Writing)
+
+#### REQ-03-001: Gherkin Feature Generation
+The system SHALL generate Gherkin feature files from requirements with minimum 3 scenarios: happy path, error case, and edge case.
+
+#### REQ-03-002: Scenario Structure
+Each Gherkin scenario SHALL follow Given-When-Then structure with specific preconditions, actions, and expected results.
+
+#### REQ-03-003: Test Case Generation
+The system SHALL generate pytest test cases following the Arrange-Act-Assert pattern with independent tests (no shared mutable state).
+
+#### REQ-03-004: Test Naming Convention
+Test names SHALL describe the behavior being tested, not the implementation details.
+
+#### REQ-03-005: RED Verification
+All generated tests MUST fail when first run. If any test passes unexpectedly, the system SHALL stop and diagnose why before proceeding.
+
+### 4.2 GREEN Phase (Implementation)
+
+#### REQ-03-006: Minimum Implementation
+The code generator SHALL produce the minimum code required to make all tests pass (YAGNI principle -- You Ain't Gonna Need It).
+
+#### REQ-03-007: Test Pass Gate
+ALL tests MUST pass with 0 failures before proceeding to the REFACTOR phase.
+
+#### REQ-03-008: Coverage Gate
+Code coverage SHALL be at least 80% (target 90%+). Coverage below 80% blocks progression.
+
+#### REQ-03-009: Code Conventions
+Generated code SHALL follow project language conventions, include type hints (Python) or JSDoc (JavaScript), and use configuration from `args/` rather than hardcoded values.
+
+### 4.3 REFACTOR Phase
+
+#### REQ-03-010: Lint Clean
+Linting SHALL produce 0 remaining issues after the `--fix` pass.
+
+#### REQ-03-011: Post-Refactor Verification
+Tests MUST still pass after refactoring. If refactoring breaks tests, the refactoring SHALL be reverted.
+
+#### REQ-03-012: Behavior Preservation
+Refactoring SHALL be behavior-preserving only: extract functions, rename variables, reduce complexity, remove dead code, add docstrings.
+
+### 4.4 Audit and Logging
+
+#### REQ-03-013: Audit Trail Entry
+Every completed TDD cycle SHALL be logged to the append-only audit trail with event type, actor, project, test count, and coverage percentage.
+
+#### REQ-03-014: Memory Entry
+Every completed TDD cycle SHALL be recorded in the memory system for session continuity.
+
+---
+
+## 5. Database Schema
+
+### Tables
+
+| Table | Purpose |
+|-------|---------|
+| `audit_trail` | Append-only log of TDD cycle completions with test counts and coverage |
+| `memory_entries` | Memory records of TDD events for session continuity |
+| `projects` | Project metadata tracking test status and coverage history |
+
+---
+
+## 6. Tools
+
+| Tool | Purpose |
+|------|---------|
+| `tools/builder/test_writer.py` | Generate Gherkin feature files and pytest test cases from requirements |
+| `tools/builder/code_generator.py` | Generate minimum implementation code from test specifications |
+| `tools/builder/linter.py` | Run language-appropriate linting with auto-fix (flake8/ruff, eslint, checkstyle) |
+| `tools/builder/formatter.py` | Run language-appropriate code formatting (black, prettier, gofmt) |
+| `tools/builder/language_support.py` | Detect project languages and list supported language profiles |
+| `tools/audit/audit_logger.py` | Log TDD cycle completions to append-only audit trail |
+| `tools/memory/memory_write.py` | Record TDD events in memory system |
+| `tools/testing/test_orchestrator.py` | Full test pipeline: unit + BDD + E2E + gates |
+
+---
+
+## 7. Architecture Decisions
+
+| ID | Decision | Rationale |
+|----|----------|-----------|
+| D13 | Python `ast` module for Python analysis; regex-based parsing for Java/C# | Air-gap safe, zero external dependencies for code analysis |
+| D155 | Shared conftest.py with fixtures centralizes test DB setup | Prevents fixture duplication across 60+ test files; security-critical paths tested first |
+
+---
+
+## 8. Security Gate
+
+**Merge Gate (enforced during TDD):**
+- All tests pass (0 failures)
+- Coverage >= 80%
+- 0 CAT1 STIG findings
+- 0 critical vulnerabilities
+- SBOM current
+
+**Testing Architecture Pipeline (9 steps):**
+1. `py_compile` -- Python syntax validation
+2. Ruff -- Ultra-fast linter (replaces flake8+isort+black)
+3. pytest -- Unit/integration tests with coverage
+4. behave/Gherkin -- BDD scenario tests
+5. Bandit -- SAST security scan
+6. Playwright MCP -- Browser E2E tests
+7. Vision validation -- LLM-based screenshot analysis (optional)
+8. Acceptance validation -- Deterministic V&V criteria check
+9. Security + Compliance gates -- CUI, STIG, secrets
+
+---
+
+## 9. Commands
+
+```bash
+# TDD Workflow
+python tools/builder/test_writer.py --feature "user auth" --project-dir "/path" --language python
+python tools/builder/code_generator.py --test-file "/path/to/test.py" --project-dir "/path" --language python
+
+# Run tests
+pytest tests/ -v --tb=short                          # Run all tests
+pytest tests/ -v --tb=short --cov=src --cov-report=term-missing  # With coverage
+
+# BDD tests
+behave features/ --dry-run                            # Validate Gherkin syntax
+behave features/                                       # Run BDD scenarios
+
+# Lint and format
+python tools/builder/linter.py --project-dir "/path" --fix
+python tools/builder/formatter.py --project-dir "/path"
+
+# Full test orchestrator (unit + BDD + E2E + gates)
+python tools/testing/test_orchestrator.py --project-dir /path/to/project
+python tools/testing/test_orchestrator.py --project-dir /path --skip-e2e --project-id "proj-123"
+
+# Audit logging
+python tools/audit/audit_logger.py --event-type "tdd_cycle_complete" --actor "builder-agent" \
+  --action "Completed TDD cycle" --project-id "proj-123"
+
+# Language support
+python tools/builder/language_support.py --detect "/path/to/project"
+python tools/builder/language_support.py --list
+
+# Skills
+/icdev-test     # Run full test suite (pytest + behave BDD)
+/icdev-build    # Build code using true TDD (RED->GREEN->REFACTOR) via M-ATLAS
+```

icdev/data/docs/features/phase-04-nist-compliance.md

@@ -0,0 +1,255 @@
+# Phase 4 — NIST 800-53 Compliance
+
+**CUI // SP-CTI**
+
+| Field | Value |
+|-------|-------|
+| Phase | 4 |
+| Title | NIST 800-53 Compliance & ATO Artifact Generation |
+| Status | Implemented |
+| Priority | P0 |
+| Dependencies | Phase 1 (GOTCHA Framework Foundation), Phase 3 (TDD/BDD Testing Framework) |
+| Author | ICDEV Architect Agent |
+| Date | 2026-02-23 |
+
+---
+
+## 1. Problem Statement
+
+No Authority to Operate (ATO) means no deployment. Government and DoD systems cannot operate without demonstrated compliance with NIST 800-53 Rev 5 security controls. An ATO package requires multiple interrelated artifacts: a System Security Plan (SSP), Plan of Action and Milestones (POAM), STIG checklists, Software Bill of Materials (SBOM), CUI markings, and NIST control mappings. These artifacts must be accurate, current, traceable, and internally consistent -- not boilerplate.
+
+Manually assembling ATO packages is a 3-6 month endeavor that delays every project. Artifacts become stale within days of creation. Control mappings drift from implementation. Evidence links break. Assessors find gaps that could have been caught programmatically. The compliance burden is the single largest schedule risk for government software programs.
+
+ICDEV automates the entire ATO artifact generation pipeline: from FIPS 199 security categorization through SSP generation, POAM creation from security findings, STIG evaluation, SBOM generation in CycloneDX format, CUI marking application, and NIST 800-53 control mapping with implementation evidence. Every artifact is generated from live project data, every finding is traceable to its source, and every document carries classification markings applied at generation time (not post-processing).
+
+---
+
+## 2. Goals
+
+1. Generate a complete System Security Plan (SSP) with all 17 required sections populated from project data
+2. Generate a Plan of Action and Milestones (POAM) from security scan findings with severity-based timelines (CAT1: 30 days, CAT2: 90 days, CAT3: 180 days)
+3. Run STIG compliance checks against applicable profiles (OS, container, database, orchestrator) with 0 CAT1 tolerance
+4. Generate a Software Bill of Materials (SBOM) in CycloneDX 1.5 format with all direct and transitive dependencies
+5. Apply CUI markings to all compliance artifacts at generation time using `classification_manager.py`
+6. Map NIST 800-53 control families (18 families) to implementation evidence with no control marked "Implemented" without linked evidence
+7. Generate a consolidated compliance status report showing ATO readiness
+8. Support NIST lookup for individual control details
+
+---
+
+## 3. Architecture
+
+### 3.1 Compliance Pipeline (19 Steps)
+
+```
++------------------+    +------------------+
+| FIPS 199         |--->| FIPS 200         |
+| Categorize       |    | Validate         |
+| (Step 0a)        |    | (Step 0b)        |
++------------------+    +--------+---------+
+                                 |
+                                 v
++------+  +------+  +------+  +------+  +------+  +------+  +------+  +------+
+| SSP  |  | POAM |  | STIG |  | SBOM |  | CUI  |  | CTRL |  | RPT  |  | LOG  |
+| Step |  | Step |  | Step |  | Step |  | Step |  | Step |  | Step |  | Step |
+|  1   |  |  2   |  |  3   |  |  4   |  |  5   |  |  6   |  |  7   |  |  8   |
++------+  +------+  +------+  +------+  +------+  +------+  +------+  +------+
+                                                                 |
+                              +----------------------------------+
+                              v
++------+  +------+  +------+  +------+  +------+  +------+
+| CSSP |  | SIEM |  | IR   |  | EVID |  | CSSP |  |XACTA|
+| Step |  | Step |  | Step |  | Step |  | RPT  |  | Step|
+|  9   |  | 10   |  | 11   |  | 12   |  | 13   |  | 14  |
++------+  +------+  +------+  +------+  +------+  +------+
+                              |
+                              v
+              +------+  +------+  +------+  +------+  +------+
+              | SbD  |  | SbD  |  | RTM  |  | IVV  |  | IVV  |
+              | Step |  | RPT  |  | Step |  | Step |  | RPT  |
+              | 15   |  | 16   |  | 17   |  | 18   |  | 19   |
+              +------+  +------+  +------+  +------+  +------+
+```
+
+### 3.2 Artifact Dependencies
+
+```
+FIPS 199 --> FIPS 200 --> SSP
+                          |
+              STIG -------+--> POAM
+              SBOM -------+
+                          |
+                          v
+                      CUI Markings --> Controls --> Status Report --> Audit
+```
+
+### 3.3 Control Crosswalk
+
+The crosswalk engine uses a dual-hub model:
+- **US Hub**: NIST 800-53 Rev 5 -- domestic frameworks map directly
+- **International Hub**: ISO/IEC 27001:2022 -- international frameworks map via bridge
+- Implementing AC-2 satisfies FedRAMP AC-2, 800-171 3.1.1, CMMC AC.L2-3.1.1
+
+---
+
+## 4. Requirements
+
+### 4.1 System Security Plan
+
+#### REQ-04-001: SSP Completeness
+The SSP generator SHALL produce a document with all 17 required sections: System Name, Categorization, Owner/AO, Description, Boundary, Architecture, Data Flow, Ports/Protocols, Interconnections, Laws/Regulations, Control Implementation, Minimum Controls, Contingency Plan, Incident Response, Configuration Management, Continuous Monitoring, Appendices.
+
+#### REQ-04-002: SSP Data Source
+The SSP SHALL be generated from live project data in the database, not from static templates with placeholder text.
+
+#### REQ-04-003: Classification Marking
+Every compliance artifact SHALL carry appropriate classification markings (CUI banner for IL4/IL5, SECRET for IL6) applied at generation time using `classification_manager.py`.
+
+### 4.2 POAM
+
+#### REQ-04-004: Finding Import
+The POAM generator SHALL import findings from all security scanners (SAST, dependency audit, STIG, container scan) and deduplicate by CVE/CWE ID.
+
+#### REQ-04-005: Severity Timelines
+POAM entries SHALL include severity-based remediation deadlines: CAT1 (Critical) due in 30 days, CAT2 (High) due in 90 days, CAT3 (Medium/Low) due in 180 days.
+
+#### REQ-04-006: Remediation Plans
+Every POAM entry SHALL include a finding description, affected component, remediation plan, milestone dates, responsible party, and status.
+
+### 4.3 STIG
+
+#### REQ-04-007: Multi-Profile Support
+The STIG checker SHALL support multiple profiles: OS (RHEL8), container (Docker), orchestrator (K8s), database (PostgreSQL).
+
+#### REQ-04-008: Zero CAT1 Gate
+The system SHALL enforce 0 CAT1 (Critical) STIG findings as a blocking gate for deployment.
+
+#### REQ-04-009: DISA Format
+STIG results SHALL match the DISA STIG Viewer export format for assessor compatibility.
+
+### 4.4 SBOM
+
+#### REQ-04-010: CycloneDX Format
+The SBOM generator SHALL produce output in CycloneDX 1.5 format with all direct and transitive dependencies.
+
+#### REQ-04-011: License Scanning
+The SBOM SHALL include license information for all components, flagging GPL and unknown licenses for review.
+
+#### REQ-04-012: Vulnerability Correlation
+The SBOM SHALL cross-reference components against known vulnerability databases.
+
+### 4.5 Control Mapping
+
+#### REQ-04-013: 18 Control Families
+The control mapper SHALL support all 18 NIST 800-53 Rev 5 control families (AC, AT, AU, CA, CM, CP, IA, IR, MA, MP, PE, PL, PM, PS, RA, SA, SC, SI).
+
+#### REQ-04-014: Evidence Linking
+No control SHALL be marked "Implemented" without linked implementation evidence (SSP sections, STIG checks, code review records, audit trail entries, scan results).
+
+#### REQ-04-015: NIST Lookup
+The system SHALL support individual control lookup via `nist_lookup.py` returning control details, baseline applicability, and implementation guidance.
+
+---
+
+## 5. Database Schema
+
+### Tables
+
+| Table | Purpose |
+|-------|---------|
+| `projects` | Project metadata including FIPS categorization and ATO status |
+| `nist_controls` | NIST 800-53 control implementations per project |
+| `stig_findings` | STIG check results by profile (CAT1/CAT2/CAT3) |
+| `security_findings` | Aggregated findings from all scanners |
+| `sbom_components` | SBOM component inventory with licenses and vulnerabilities |
+| `audit_trail` | Append-only compliance artifact generation log |
+| `fips199_categorizations` | FIPS 199 security categorization records |
+| `project_information_types` | SP 800-60 information types assigned to projects |
+| `fips200_assessments` | FIPS 200 minimum security area assessments |
+| `cssp_assessments` | CSSP (DI 8530.01) assessment results |
+
+---
+
+## 6. Tools
+
+| Tool | Purpose |
+|------|---------|
+| `tools/compliance/ssp_generator.py` | Generate System Security Plan with all 17 sections |
+| `tools/compliance/poam_generator.py` | Generate POAM from aggregated security findings |
+| `tools/compliance/stig_checker.py` | Run STIG compliance checks against applicable profiles |
+| `tools/compliance/sbom_generator.py` | Generate CycloneDX 1.5 SBOM with dependency analysis |
+| `tools/compliance/cui_marker.py` | Apply CUI markings to files and directories |
+| `tools/compliance/control_mapper.py` | Map NIST 800-53 controls to implementation evidence |
+| `tools/compliance/nist_lookup.py` | Look up individual NIST 800-53 control details |
+| `tools/compliance/compliance_status.py` | Generate consolidated compliance status report |
+| `tools/compliance/classification_manager.py` | Generate classification markings by impact level |
+| `tools/compliance/fips199_categorizer.py` | FIPS 199 security categorization with SP 800-60 types |
+| `tools/compliance/fips200_validator.py` | FIPS 200 minimum security area validation |
+| `tools/compliance/crosswalk_engine.py` | Dual-hub control crosswalk (NIST + ISO) |
+| `tools/audit/audit_logger.py` | Log compliance events to append-only audit trail |
+
+---
+
+## 7. Architecture Decisions
+
+| ID | Decision | Rationale |
+|----|----------|-----------|
+| D5 | CUI markings applied at generation time (inline, not post-processing) | Prevents unmarked artifacts from existing even temporarily |
+| D54 | FIPS 199 uses high watermark across SP 800-60 information types | Conservative approach required for government categorization |
+| D55 | FIPS 200 validates all 17 areas against baseline from FIPS 199 | Ensures minimum security requirements met at correct impact level |
+| D56 | SSP baseline selection is dynamic: query DB for categorization first | Categorization drives everything; stale baselines produce incorrect SSPs |
+| D111 | Dual-hub crosswalk: NIST 800-53 (US) + ISO 27001 (international) | Implement once at either hub, cascade to all mapped frameworks |
+| D112 | Framework catalogs versioned independently | Update one framework without touching others |
+
+---
+
+## 8. Security Gate
+
+**Compliance Gate (Merge Gate contribution):**
+- 0 CAT1 STIG findings
+- SBOM current (generated within 30 days)
+- CUI markings present on all compliance documents
+- NIST 800-53 controls mapped with implementation evidence
+
+**FIPS 199 Gate:**
+- Categorization required for all ATO projects
+- IL6 projects must have CNSSI 1253 overlay applied
+- Categorization must be approved before SSP generation
+
+**FIPS 200 Gate:**
+- 0 not_satisfied requirement areas
+- All 17 minimum security areas assessed
+- Coverage >= 80%
+
+---
+
+## 9. Commands
+
+```bash
+# Security categorization (foundation step)
+python tools/compliance/fips199_categorizer.py --project-id "proj-123" --categorize --json
+python tools/compliance/fips200_validator.py --project-id "proj-123" --json
+
+# Core ATO artifacts
+python tools/compliance/ssp_generator.py --project-id "proj-123"
+python tools/compliance/poam_generator.py --project-id "proj-123"
+python tools/compliance/stig_checker.py --project-id "proj-123"
+python tools/compliance/sbom_generator.py --project-dir "/path/to/project"
+
+# CUI markings
+python tools/compliance/cui_marker.py --file "/path/to/file" --marking "CUI // SP-CTI"
+
+# NIST control mapping
+python tools/compliance/control_mapper.py --activity "code.commit" --project-id "proj-123"
+python tools/compliance/nist_lookup.py --control "AC-2"
+
+# Crosswalk
+python tools/compliance/crosswalk_engine.py --control AC-2
+python tools/compliance/crosswalk_engine.py --project-id "proj-123" --coverage
+
+# Classification
+python tools/compliance/classification_manager.py --impact-level IL5
+
+# Compliance skill
+/icdev-comply    # Generate ATO artifacts (SSP, POAM, STIG, SBOM)
+```