icdev 1.0.0__py3-none-any.whl

icdev/data/docs/features/phase-18-mbse-integration.md

@@ -0,0 +1,242 @@
+# Phase 18 — MBSE Integration
+
+**CUI // SP-CTI**
+
+| Field | Value |
+|-------|-------|
+| Phase | 18 |
+| Title | MBSE Integration |
+| Status | Implemented |
+| Priority | P0 |
+| Dependencies | Phase 11 (Compliance Workflow), Phase 12 (Build App / ATLAS Workflow) |
+| Author | ICDEV Architect Agent |
+| Date | 2026-02-23 |
+
+---
+
+## 1. Problem Statement
+
+DoDI 5000.87 mandates digital engineering for all DoD acquisition programs. Without model-code traceability, programs fail audits and cannot demonstrate that delivered code implements the authoritative design. The digital thread -- the end-to-end chain from requirements through models to code, tests, and compliance controls -- is the foundation of Digital Engineering Strategy (DES) compliance and Milestone B/C review readiness.
+
+Currently, SysML models authored in tools like Cameo Systems Modeler and requirements managed in IBM DOORS NG exist in isolation from the code that implements them. There is no automated mechanism to import model elements into the development environment, generate code scaffolding from model definitions, map model elements to NIST 800-53 security controls, detect drift between model and code, or capture point-in-time snapshots for SAFe PI boundaries.
+
+ICDEV needs an MBSE integration layer that extends the ATLAS workflow with a Model pre-phase (M-ATLAS), establishing bidirectional traceability from DOORS requirements through SysML models to generated code, test cases, and NIST compliance controls, with continuous drift detection and DES compliance assessment.
+
+---
+
+## 2. Goals
+
+1. Import SysML v1.6 models from Cameo Systems Modeler via XMI 2.5.1 format into the ICDEV database for downstream traceability and code generation
+2. Import requirements from IBM DOORS NG via ReqIF 1.2 format with diff-against-previous capability
+3. Build an end-to-end digital thread: Requirement -> Model Element -> Code Module -> Test Case -> NIST Control
+4. Generate code scaffolding from SysML block definitions, activities, state machines, and interfaces with traceability comments and CUI markings
+5. Map model elements to NIST 800-53 security controls via keyword-based and type-based matching rules
+6. Detect model-code drift continuously with bidirectional sync capabilities (model-to-code and code-to-model)
+7. Assess DES compliance against the 5 goals of DoDI 5000.87 for Milestone readiness
+8. Capture PI model snapshots with PI-over-PI comparison for trend tracking and audit
+
+---
+
+## 3. Architecture
+
+```
++-------------------+     +-------------------+     +-------------------+
+|  Cameo XMI 2.5.1  |---->|  XMI Parser       |---->|  sysml_elements   |
+|  (SysML Model)    |     |                   |     |  sysml_relations  |
++-------------------+     +-------------------+     +-------------------+
+                                                            |
++-------------------+     +-------------------+             |
+|  DOORS NG ReqIF   |---->|  ReqIF Parser     |---->doors_requirements
+|  (Requirements)   |     |                   |             |
++-------------------+     +-------------------+             |
+                                                            v
+                                                    +-------------------+
+                                                    |  Digital Thread   |
+                                                    |  (auto-link)      |
+                                                    +-------------------+
+                                                            |
+                          +----------------+----------------+----------------+
+                          |                |                |                |
+                          v                v                v                v
+                   +-----------+   +-----------+   +-----------+   +-----------+
+                   | Code Gen  |   | Control   |   | Drift     |   | DES       |
+                   | (classes, |   | Mapper    |   | Detector  |   | Assessor  |
+                   |  stubs)   |   | (NIST)    |   | (sync)    |   | (5000.87) |
+                   +-----------+   +-----------+   +-----------+   +-----------+
+                                                                        |
+                                                                        v
+                                                                 +-----------+
+                                                                 | PI Model  |
+                                                                 | Tracker   |
+                                                                 +-----------+
+```
+
+M-ATLAS extends the standard ATLAS workflow by adding a Model pre-phase. If no model exists, the system gracefully falls back to standard ATLAS. The pipeline processes:
+
+- **M (Model)** -- Import XMI/ReqIF, build digital thread, generate code scaffolding
+- **A (Architect)** -- System design informed by model elements (blocks, interfaces, behaviors)
+- **T (Trace)** -- Data schema, integrations, stack augmented with model traceability
+- **L (Link)** -- Validate model-to-code and requirement-to-test mappings
+- **A (Assemble)** -- Build with model-generated scaffolding as starting point
+- **S (Stress-test)** -- Test including model-generated stubs and traceability verification
+
+---
+
+## 4. Requirements
+
+### 4.1 Model Import
+
+#### REQ-18-001: SysML XMI Import
+The system SHALL parse SysML v1.6 models exported as XMI 2.5.1 from Cameo Systems Modeler, extracting: Block Definition Diagrams, Activity Diagrams, Requirement Diagrams, State Machine Diagrams, Use Case Diagrams, Internal Block Diagrams, and Parametric Diagrams.
+
+#### REQ-18-002: ReqIF Import
+The system SHALL parse requirements exported as ReqIF 1.2 from IBM DOORS NG, extracting SPEC-OBJECTs, SPEC-RELATIONs, ATTRIBUTE-DEFINITIONs, and SPEC-HIERARCHY with configurable field mappings.
+
+#### REQ-18-003: Import Diff
+The system SHALL support diff-against-previous import to show new, changed, and deleted elements since the last import.
+
+### 4.2 Digital Thread
+
+#### REQ-18-004: End-to-End Traceability
+The system SHALL establish a digital thread: Requirement (ReqIF) -> Model Element (XMI) -> Code Module (generated) -> Test Case (TDD) -> NIST Control (800-53).
+
+#### REQ-18-005: Auto-Link
+The system SHALL automatically link requirements to model elements using name/ID matching and NLP similarity, with a configurable confidence threshold (default 0.6, below which items are queued for manual review).
+
+#### REQ-18-006: Coverage Reporting
+The system SHALL report digital thread coverage percentages: requirements with model links, model elements with code links, code modules with test links, and end-to-end traced chains.
+
+### 4.3 Code Generation
+
+#### REQ-18-007: Model-Driven Code Generation
+The system SHALL generate code scaffolding from SysML elements: Blocks become classes, Activities become functions, State Machines become state pattern classes, Flow Ports become interfaces, and Constraint Blocks become validation functions.
+
+#### REQ-18-008: Traceability Comments
+All generated code SHALL include traceability comments (`# GENERATED FROM:`, `# TRACES TO:`) and CUI // SP-CTI markings.
+
+### 4.4 Control Mapping and Compliance
+
+#### REQ-18-009: NIST Control Mapping
+The system SHALL map model elements to NIST 800-53 controls using keyword-based and type-based matching rules with confidence scoring.
+
+#### REQ-18-010: DES Assessment
+The system SHALL assess compliance against the 5 goals of DoDI 5000.87 Digital Engineering Strategy and produce a DES compliance score with per-goal status.
+
+### 4.5 Drift Detection and Sync
+
+#### REQ-18-011: Drift Detection
+The system SHALL detect drift between model definitions and generated code by comparing class names, method signatures, properties, state transitions, and interface implementations.
+
+#### REQ-18-012: Bidirectional Sync
+The system SHALL support model-to-code and code-to-model sync directions with conflict detection for cases where both model and code have changed.
+
+### 4.6 PI Snapshots
+
+#### REQ-18-013: PI Model Snapshot
+The system SHALL capture point-in-time snapshots of model elements, requirements, digital thread coverage, drift status, NIST mapping, DES score, and SBOM at SAFe PI boundaries.
+
+#### REQ-18-014: PI Comparison
+The system SHALL support comparing two PI snapshots to show element deltas, coverage improvements, drift resolution progress, and compliance velocity.
+
+---
+
+## 5. Database Schema
+
+### Tables
+
+| Table | Purpose |
+|-------|---------|
+| `sysml_elements` | Imported model elements: element_id, type (block/activity/requirement/state_machine/use_case/constraint_block), name, properties_json |
+| `sysml_relationships` | Model relationships: source_id, target_id, type (connector/dependency/association), properties_json |
+| `doors_requirements` | Imported requirements: req_id, text, type, priority, status, parent_id |
+| `doors_req_links` | Requirement links: source_id, target_id, link_type (parent-child/derives/satisfies) |
+| `model_imports` | Import metadata: import_id, file_path, file_hash, element_count, timestamp |
+| `digital_thread_links` | Traceability links: source_type, source_id, target_type, target_id, link_type, confidence |
+| `model_control_mappings` | Model-to-NIST mappings: element_id, control_id, confidence, mapping_rule |
+| `pi_snapshots` | PI snapshots: pi_id, snapshot_data_json, coverage_pct, drift_count, des_score, timestamp |
+| `des_assessments` | DES compliance: project_id, goal_scores_json, overall_score, milestone_readiness |
+
+---
+
+## 6. Tools
+
+| Tool | Purpose |
+|------|---------|
+| `tools/mbse/xmi_parser.py` | Parse SysML XMI 2.5.1 into sysml_elements and sysml_relationships |
+| `tools/mbse/reqif_parser.py` | Parse DOORS NG ReqIF 1.2 into doors_requirements and doors_req_links |
+| `tools/mbse/digital_thread.py` | Auto-link, coverage, report, manual link for end-to-end traceability |
+| `tools/mbse/model_code_generator.py` | Generate code scaffolding from model elements with traceability |
+| `tools/mbse/model_control_mapper.py` | Map model elements to NIST 800-53 controls |
+| `tools/mbse/sync_engine.py` | Detect drift and sync model-to-code or code-to-model |
+| `tools/mbse/des_assessor.py` | Assess DoDI 5000.87 DES compliance (5 goals) |
+| `tools/mbse/des_report_generator.py` | Generate DES compliance report |
+| `tools/mbse/pi_model_tracker.py` | Create and compare PI model snapshots |
+| `tools/mbse/diagram_extractor.py` | Extract SysML elements from screenshot images via vision LLM |
+| `tools/mcp/mbse_server.py` | MCP server: import_xmi, import_reqif, trace_forward, trace_backward, generate_code, detect_drift, sync_model, des_assess, thread_coverage, model_snapshot |
+
+---
+
+## 7. Architecture Decisions
+
+| ID | Decision | Rationale |
+|----|----------|-----------|
+| D7 | Python stdlib `xml.etree.ElementTree` for XMI/ReqIF parsing | Zero external dependencies, air-gap safe |
+| D8 | Normalized DB tables for model elements | Enables SQL joins across the digital thread |
+| D9 | M-ATLAS adds "Model" pre-phase to ATLAS | Backward compatible -- skips if no model exists |
+| D10 | File-based sync only for Cameo | Air-gapped desktop, no API -- XMI export/import |
+| D11 | PI-snapshot versioning with SHA-256 content hashing | Drift detection between PI boundaries |
+| D12 | N:M digital thread links | One block can map to many code modules; one control to many requirements |
+| D86 | Vision diagram extraction is advisory-only | Requires `--store` flag to write to DB; human review gate before model contamination |
+
+---
+
+## 8. Security Gate
+
+**DES Gate:**
+- 0 non_compliant on critical DoDI 5000.87 Digital Engineering requirements
+- DES score < 70% flags project for program management review
+
+**Drift Gate:**
+- Drift > 20% blocks deployment -- model and code must be reconciled
+
+**Traceability Gate:**
+- No code merged without at least one requirement link in the digital thread
+
+**CUI Gate:**
+- All generated reports and code files must carry CUI // SP-CTI markings
+
+---
+
+## 9. Commands
+
+```bash
+# Import SysML model
+python tools/mbse/xmi_parser.py --project-id "proj-123" --file /path/to/model.xmi --json
+
+# Import DOORS requirements
+python tools/mbse/reqif_parser.py --project-id "proj-123" --file /path/to/reqs.reqif --json
+
+# Build digital thread
+python tools/mbse/digital_thread.py --project-id "proj-123" auto-link --json
+python tools/mbse/digital_thread.py --project-id "proj-123" coverage --json
+
+# Generate code from model
+python tools/mbse/model_code_generator.py --project-id "proj-123" --language python --output ./src
+
+# Map to NIST controls
+python tools/mbse/model_control_mapper.py --project-id "proj-123" --map-all --json
+
+# Detect drift
+python tools/mbse/sync_engine.py --project-id "proj-123" detect-drift --json
+python tools/mbse/sync_engine.py --project-id "proj-123" sync-model-to-code --json
+
+# DES assessment
+python tools/mbse/des_assessor.py --project-id "proj-123" --project-dir /path --json
+python tools/mbse/des_report_generator.py --project-id "proj-123" --output-dir /path
+
+# PI snapshot
+python tools/mbse/pi_model_tracker.py --project-id "proj-123" --pi PI-25.1 --snapshot
+
+# Extract diagram from screenshot
+python tools/mbse/diagram_extractor.py --image diagram.png --diagram-type block_definition --project-id "proj-123" --json
+```

icdev/data/docs/features/phase-19-agentic-generation.md

@@ -0,0 +1,202 @@
+# Phase 19 — Agentic Application Generation
+
+**CUI // SP-CTI**
+
+| Field | Value |
+|-------|-------|
+| Phase | 19 |
+| Title | Agentic Application Generation |
+| Status | Implemented |
+| Priority | P1 |
+| Dependencies | Phase 12 (Build App / ATLAS Workflow), Phase 11 (Compliance Workflow) |
+| Author | ICDEV Architect Agent |
+| Date | 2026-02-23 |
+
+---
+
+## 1. Problem Statement
+
+Organizations need multiple independent agentic systems -- one per program, per enclave, or per mission thread. Manually bootstrapping each system is error-prone and takes weeks. Each new agentic application requires the full GOTCHA framework (6 layers), ATLAS workflow, agent infrastructure, memory system, compliance scaffolding, CI/CD pipeline, and cloud provider integration -- all wired together correctly from day one.
+
+Without automated generation, teams either copy-paste from existing systems (creating drift and inconsistency) or build from scratch (wasting weeks of effort and introducing configuration errors). The result is a proliferation of inconsistent agentic systems that cannot be audited, updated, or governed centrally.
+
+ICDEV needs the ability to generate mini-ICDEV clone child applications that inherit the full GOTCHA framework, ATLAS workflow, own agents, memory system, and CI/CD -- everything except the ability to generate further children (grandchild prevention). These child applications must be fully autonomous, cloud-native systems capable of building, testing, deploying, and self-healing their own workloads, produced in minutes rather than weeks.
+
+---
+
+## 2. Goals
+
+1. Assess application specifications across 6 fitness dimensions (data complexity, decision complexity, user interaction, integration density, compliance sensitivity, scale variability) to recommend architecture type (full agent, hybrid, traditional)
+2. Generate a comprehensive blueprint from fitness scorecard and user decisions that drives all subsequent generation steps
+3. Scaffold child applications with the full GOTCHA directory structure (goals/, tools/, args/, context/, hardprompts/)
+4. Generate 5 core agents (Orchestrator, Architect, Builder, Knowledge, Monitor) plus up to 2 ATO agents (Compliance, Security) when compliance is required
+5. Produce dynamic CLAUDE.md via Jinja2 that documents only the capabilities present in the child application
+6. Generate standalone DB init scripts with core tables and capability-specific tables added via migration
+7. Integrate cloud provider MCP servers (AWS, GCP, Azure, Oracle, IBM) based on target cloud configuration
+8. Enforce 3-layer grandchild prevention: config flag, scaffolder stripping, CLAUDE.md documentation (D52)
+
+---
+
+## 3. Architecture
+
+```
++-------------------+     +-------------------+     +-------------------+
+|  User Spec        |---->|  Fitness Assessor  |---->|  User Decisions   |
+|  (interactive)    |     |  (6 dimensions)   |     |  (confirm/override)|
++-------------------+     +-------------------+     +-------------------+
+                                                            |
+                                                            v
+                                                    +-------------------+
+                                                    |  Blueprint Engine |
+                                                    |  (single source   |
+                                                    |   of truth)       |
+                                                    +-------------------+
+                                                            |
+                                                            v
+                                                    +-------------------+
+                                                    |  Scaffolder       |
+                                                    |  (--agentic flag) |
+                                                    +-------------------+
+                                                            |
+                     +------+------+------+------+------+---+---+
+                     |      |      |      |      |      |       |
+                     v      v      v      v      v      v       v
+                  GOTCHA  Agents Memory  Goals  CI/CD   DB    CLAUDE.md
+                  Dirs    Cards  System  Files  Pipeline Init  (Jinja2)
+```
+
+The generation pipeline follows 7 steps:
+
+1. **Gather Requirements** -- Interactive collection of app name, cloud provider, compliance needs, impact level, language, MBSE, and deployment target
+2. **Assess Fitness** -- Score across 6 weighted dimensions (>= 6.0 full agent, 4.0-5.9 hybrid, < 4.0 traditional)
+3. **User Decisions** -- Confirm architecture, MBSE, ATO, cloud provider, port offset, agent roster
+4. **Generate Blueprint** -- Single JSON blueprint drives all generators (capability map, agent roster, file manifest, CSP MCP servers, DB schema, memory config, CI/CD config, ATLAS config, classification)
+5. **Scaffold + Generate** -- Phase 1: base language scaffold (15+ files), Phase 2: agentic generation (12 steps)
+6. **Verify** -- Directory structure, content, and functional checks
+7. **Document and Register** -- Audit trail, generation summary, memory entry
+
+---
+
+## 4. Requirements
+
+### 4.1 Fitness Assessment
+
+#### REQ-19-001: 6-Dimension Fitness Scoring
+The system SHALL score application specifications across: data_complexity (10%), decision_complexity (25%), user_interaction (20%), integration_density (15%), compliance_sensitivity (15%), and scale_variability (15%).
+
+#### REQ-19-002: Architecture Recommendation
+The system SHALL recommend architecture based on score: >= 6.0 full agent, 4.0-5.9 hybrid, < 4.0 traditional. Users MAY override the recommendation with documented rationale.
+
+### 4.2 Blueprint Generation
+
+#### REQ-19-003: Blueprint as Single Source of Truth
+The blueprint JSON SHALL be the sole driver of all generation steps. No generator SHALL make hardcoded decisions outside the blueprint (D47).
+
+#### REQ-19-004: CSP MCP Server Selection
+The blueprint SHALL include cloud provider MCP server selections based on target cloud (AWS: 66+ servers, GCP: managed endpoints, Azure: catalog, Oracle: OCI servers, IBM: IC4G servers with watsonx.ai) from `context/agentic/csp_mcp_registry.yaml`.
+
+### 4.3 Child Application Generation
+
+#### REQ-19-005: GOTCHA Framework
+The child application SHALL include the complete GOTCHA directory structure: goals/, tools/, args/, context/, hardprompts/ with content adapted from ICDEV.
+
+#### REQ-19-006: Agent Roster
+The child application SHALL include 5 core agents (Orchestrator, Architect, Builder, Knowledge, Monitor) with configurable port offsets (default +1000). Up to 2 additional ATO agents (Compliance, Security) SHALL be included when compliance is required.
+
+#### REQ-19-007: Memory System
+The child application SHALL include a complete memory system: MEMORY.md, daily logs, SQLite database with embeddings, and semantic search capability.
+
+#### REQ-19-008: Dynamic CLAUDE.md
+The child application SHALL include a CLAUDE.md generated via Jinja2 template that documents only the capabilities present in that specific child application (D50).
+
+### 4.4 Governance
+
+#### REQ-19-009: Grandchild Prevention
+The system SHALL enforce 3-layer grandchild prevention (D52): config flag (`can_generate_children: false`), scaffolder stripping (generation tools excluded from child), and CLAUDE.md documentation ("CANNOT generate child applications").
+
+#### REQ-19-010: CUI Markings
+All generated files SHALL carry CUI // SP-CTI markings appropriate to the child application's impact level.
+
+#### REQ-19-011: Generation Audit Trail
+The system SHALL record all generation events in the append-only audit trail and store a `data/generation_summary.json` in each child application.
+
+---
+
+## 5. Database Schema
+
+### Tables
+
+| Table | Purpose |
+|-------|---------|
+| `child_app_registry` | Registered child apps: name, path, architecture, agent_count, compliance_level, genome_version |
+| `agentic_fitness_assessments` | Fitness scorecards: spec_json, dimension_scores, overall_score, recommendation |
+
+---
+
+## 6. Tools
+
+| Tool | Purpose |
+|------|---------|
+| `tools/builder/agentic_fitness.py` | 6-dimension fitness scoring engine |
+| `tools/builder/app_blueprint.py` | Blueprint generation from scorecard + user decisions |
+| `tools/builder/child_app_generator.py` | 12-step child application generation |
+| `tools/builder/claude_md_generator.py` | Dynamic CLAUDE.md via Jinja2 template rendering |
+| `tools/builder/goal_adapter.py` | Copy and adapt goals from ICDEV for child app context |
+| `tools/builder/db_init_generator.py` | Generate standalone DB init scripts with core + capability tables |
+| `tools/builder/scaffolder.py` | Base language scaffold with `--agentic` flag for full generation |
+
+---
+
+## 7. Architecture Decisions
+
+| ID | Decision | Rationale |
+|----|----------|-----------|
+| D44 | Flag-based (`--agentic`) for backward compatibility | Omitting flag produces identical output; existing scaffolding unchanged |
+| D45 | Copy-and-adapt over template library | ICDEV tools are the source of truth; no template drift |
+| D46 | Weighted rule-based fitness + optional LLM override | Deterministic scoring with human escape hatch |
+| D47 | Blueprint-driven generation | Single JSON config drives all generators; no hardcoded decisions |
+| D48 | ICDEV callback uses A2A protocol for child-to-parent communication | Standard protocol for all agent communication |
+| D50 | Dynamic CLAUDE.md via Jinja2 | Documents only what is present; no stale references |
+| D51 | Minimal DB + migration | Core tables first, expand as capabilities activate |
+| D52 | 3-layer grandchild prevention (config + scaffolder + CLAUDE.md) | Prevents uncontrolled proliferation of agentic systems |
+| D53 | Port offset for child agents (default +1000) | Avoids port conflicts when ICDEV and child run on same host |
+
+---
+
+## 8. Security Gate
+
+**Agentic Generation Gate:**
+- Fitness assessment completed with all 6 dimensions scored before generation proceeds
+- User decisions confirmed and logged in audit trail
+- Blueprint integrity verified (SHA-256 hash match)
+- Grandchild prevention verified: config flag set, generation tools excluded, CLAUDE.md contains prevention statement
+- CUI markings present on all generated files
+- Child database initializes successfully
+- No hardcoded ICDEV paths or ports in generated files
+
+---
+
+## 9. Commands
+
+```bash
+# Assess fitness
+python tools/builder/agentic_fitness.py --spec "..." --json
+
+# Generate blueprint
+python tools/builder/app_blueprint.py --fitness-scorecard sc.json \
+  --user-decisions '{}' --app-name "my-app" --json
+
+# Generate child application
+python tools/builder/child_app_generator.py --blueprint bp.json \
+  --project-path /tmp --name "my-app" --json
+
+# Scaffold with agentic flag
+python tools/builder/scaffolder.py --project-path /tmp --name "my-app" \
+  --type api --agentic --fitness-scorecard sc.json
+
+# Generate dynamic CLAUDE.md
+python tools/builder/claude_md_generator.py --blueprint bp.json --output CLAUDE.md
+
+# Initialize child database
+python tools/db/init_my_app_db.py
+```

icdev/data/docs/features/phase-20-fips-security-categorization.md

@@ -0,0 +1,198 @@
+# Phase 20 — FIPS 199/200 Security Categorization
+
+**CUI // SP-CTI**
+
+| Field | Value |
+|-------|-------|
+| Phase | 20 |
+| Title | FIPS 199/200 Security Categorization |
+| Status | Implemented |
+| Priority | P0 |
+| Dependencies | Phase 17 (Multi-Framework Compliance) |
+| Author | ICDEV Architect Agent |
+| Date | 2026-02-23 |
+
+---
+
+## 1. Problem Statement
+
+FIPS 199 security categorization is Step 1 of the NIST Risk Management Framework (RMF). Every downstream compliance decision -- SSP control selection, NIST 800-53 baseline, FedRAMP level, CMMC maturity, and deployment architecture -- depends on correct categorization. An incorrect categorization means wrong controls, which means failed ATO. Yet most organizations perform categorization manually as a one-time paper exercise with no connection to the automated compliance pipeline.
+
+The categorization process itself is non-trivial. Organizations must identify all information types their system processes, stores, or transmits using the NIST SP 800-60 Volume 2 catalog (hundreds of types across defense, government resource management, and internal risk management categories). Each type carries provisional Confidentiality, Integrity, and Availability (CIA) impact levels that may need organizational adjustment. The overall categorization uses a high watermark across all assigned types.
+
+For IL6/SECRET national security systems, CNSSI 1253 overlays must be applied on top of FIPS 199, elevating minimum CIA floors per overlay rules. Additionally, FIPS 200 mandates validation across 17 minimum security requirement areas before any system can receive authorization. Without automation, these interdependent processes are error-prone, inconsistent, and disconnected from downstream artifact generation.
+
+---
+
+## 2. Goals
+
+1. Provide a browsable SP 800-60 Volume 2 information type catalog with filtering by category (D.1 Services Delivery, D.2 Government Resource Management, D.3 Internal Risk Management)
+2. Support assigning multiple information types to a project with per-type organizational impact adjustments and mandatory written justification
+3. Compute FIPS 199 categorization using the high watermark method across all assigned types for Confidentiality, Integrity, and Availability
+4. Automatically apply CNSSI 1253 overlays for IL6/SECRET national security systems, elevating minimum CIA floor per overlay rules
+5. Validate all 17 FIPS 200 minimum security requirement areas (AC, AT, AU, CA, CM, CP, IA, IR, MA, MP, PE, PL, PS, RA, SA, SC, SI) against the computed baseline
+6. Dynamically drive SSP baseline selection from categorization results (replacing static IL-based mapping)
+7. Support manual categorization override with required justification
+8. Integrate with the crosswalk engine to cascade categorization-driven baseline changes across all mapped frameworks
+
+---
+
+## 3. Architecture
+
+```
++-------------------+     +-------------------+     +-------------------+
+|  SP 800-60        |     |  Type Assignment  |     |  FIPS 199         |
+|  Catalog Browse   |---->|  (per project)    |---->|  Categorizer      |
+|  (D.1, D.2, D.3) |     |  + adjustments    |     |  (high watermark) |
++-------------------+     +-------------------+     +-------------------+
+                                                            |
+                                    +-----------------------+
+                                    |                       |
+                                    v                       v
+                           +----------------+      +----------------+
+                           | CNSSI 1253     |      | FIPS 200       |
+                           | Overlay        |      | Validator      |
+                           | (IL6/SECRET)   |      | (17 areas)     |
+                           +----------------+      +----------------+
+                                    |                       |
+                                    v                       v
+                           +----------------+      +----------------+
+                           | SSP Baseline   |      | Gate            |
+                           | Selection      |      | Evaluation      |
+                           | (dynamic)      |      |                 |
+                           +----------------+      +----------------+
+```
+
+The categorization pipeline follows 6 steps:
+
+1. **Browse Catalog** -- Review SP 800-60 Vol 2 types filtered by category
+2. **Assign Types** -- Add information types to project with optional CIA adjustments
+3. **Categorize** -- Compute high watermark across all types; apply CNSSI 1253 if IL6
+4. **Validate FIPS 200** -- Check all 17 minimum security areas against computed baseline
+5. **Drive SSP** -- SSP generator reads categorization from DB for dynamic baseline selection
+6. **Review and Approve** -- Categorization starts as draft; AO approves after verification
+
+---
+
+## 4. Requirements
+
+### 4.1 Information Type Catalog
+
+#### REQ-20-001: SP 800-60 Catalog
+The system SHALL provide a browsable NIST SP 800-60 Volume 2 information type catalog stored in `context/compliance/nist_sp_800_60_types.json`, with filtering by category prefix (D.1, D.2, D.3).
+
+#### REQ-20-002: Provisional Impact Levels
+Each information type SHALL carry provisional Confidentiality, Integrity, and Availability impact levels as defined by SP 800-60.
+
+### 4.2 Type Assignment and Adjustment
+
+#### REQ-20-003: Multiple Type Assignment
+The system SHALL support assigning multiple information types to a single project, stored in the `project_information_types` table.
+
+#### REQ-20-004: Impact Adjustment
+The system SHALL support organizational adjustments to provisional impact levels with mandatory written justification. Adjustments SHALL only raise impact levels, not lower below provisional.
+
+### 4.3 Categorization
+
+#### REQ-20-005: High Watermark Method
+The system SHALL compute the overall system categorization as the maximum impact level across all assigned information types for each CIA objective: SC = {(C, max), (I, max), (A, max)}.
+
+#### REQ-20-006: CNSSI 1253 Overlay
+For IL6/SECRET national security systems, the system SHALL automatically apply CNSSI 1253 overlays from `context/compliance/cnssi_1253_overlay.json`, elevating minimum CIA floor per overlay rules.
+
+#### REQ-20-007: Manual Override
+The system SHALL support manual categorization override via `--method manual` with `--manual-c`, `--manual-i`, `--manual-a` flags and mandatory justification.
+
+### 4.4 FIPS 200 Validation
+
+#### REQ-20-008: 17-Area Validation
+The system SHALL validate all 17 FIPS 200 minimum security requirement areas (AC, AT, AU, CA, CM, CP, IA, IR, MA, MP, PE, PL, PS, RA, SA, SC, SI) against the baseline derived from FIPS 199 categorization.
+
+#### REQ-20-009: FIPS 200 Gate
+The system SHALL evaluate a gate requiring 0 not_satisfied requirement areas, all 17 areas assessed, and coverage >= 80%.
+
+### 4.5 SSP Integration
+
+#### REQ-20-010: Dynamic Baseline Selection
+The SSP generator SHALL dynamically read categorization from the database to determine the correct NIST 800-53 baseline, replacing static IL-based mapping (D56).
+
+#### REQ-20-011: SSP Section Population
+The SSP SHALL include actual C/I/A impact levels in Section 2, correct baseline applicability in Section 12, dynamic control baseline in Section 13, and all 17 FIPS 200 families in Section 15.
+
+---
+
+## 5. Database Schema
+
+### Tables
+
+| Table | Purpose |
+|-------|---------|
+| `fips199_categorizations` | Categorization results: project_id, method, confidentiality, integrity, availability, overall, cnssi_applied, status (draft/approved), approved_by |
+| `project_information_types` | Assigned types: project_id, type_id, provisional_c/i/a, adjusted_c/i/a, adjustment_justification |
+| `fips200_assessments` | FIPS 200 validation results: project_id, area (17 values), status, baseline_requirement, evidence |
+
+---
+
+## 6. Tools
+
+| Tool | Purpose |
+|------|---------|
+| `tools/compliance/fips199_categorizer.py` | Catalog browse, type assignment, categorization, CNSSI 1253 overlay, gate evaluation |
+| `tools/compliance/fips200_validator.py` | Validate 17 FIPS 200 minimum security areas against baseline, gate evaluation |
+| `tools/compliance/ssp_generator.py` | SSP generation with dynamic baseline from categorization (enhanced) |
+
+---
+
+## 7. Architecture Decisions
+
+| ID | Decision | Rationale |
+|----|----------|-----------|
+| D54 | FIPS 199 uses high watermark across SP 800-60 information types | Provisional levels are defaults, adjustable per organization; watermark ensures system categorized to highest need |
+| D55 | FIPS 200 validates all 17 areas against baseline from FIPS 199, not impact level alone | Baseline drives control selection, not raw impact level |
+| D56 | SSP baseline selection is dynamic: query DB first, fall back to IL mapping | Ensures SSP always reflects actual categorization, not a static assumption |
+| D57 | CNSSI 1253 auto-applies for IL6/SECRET; elevates minimum C/I/A floor | National security systems require overlay per CNSSI guidance; auto-detection prevents omission |
+
+---
+
+## 8. Security Gate
+
+**FIPS 199 Gate:**
+- Categorization required for all ATO-tracked projects
+- IL6 projects must have CNSSI 1253 overlay applied
+- Categorization must be in approved status (not draft) before ATO proceeds
+- At least one information type must be assigned
+
+**FIPS 200 Gate:**
+- 0 not_satisfied requirement areas
+- All 17 minimum security areas assessed
+- Coverage >= 80%
+
+---
+
+## 9. Commands
+
+```bash
+# Browse SP 800-60 catalog
+python tools/compliance/fips199_categorizer.py --list-catalog
+python tools/compliance/fips199_categorizer.py --list-catalog --category D.1 --json
+
+# Assign information types
+python tools/compliance/fips199_categorizer.py --project-id "proj-123" --add-type "D.1.1.1"
+python tools/compliance/fips199_categorizer.py --project-id "proj-123" --add-type "D.2.3.4" --adjust-c High
+
+# List assigned types
+python tools/compliance/fips199_categorizer.py --project-id "proj-123" --list-types --json
+
+# Run categorization
+python tools/compliance/fips199_categorizer.py --project-id "proj-123" --categorize --json
+
+# Force CNSSI 1253 method
+python tools/compliance/fips199_categorizer.py --project-id "proj-123" --categorize --method cnssi_1253
+
+# Gate evaluation
+python tools/compliance/fips199_categorizer.py --project-id "proj-123" --gate
+
+# FIPS 200 validation
+python tools/compliance/fips200_validator.py --project-id "proj-123" --json
+python tools/compliance/fips200_validator.py --project-id "proj-123" --gate --json
+```