icdev 1.0.0__py3-none-any.whl

icdev/data/docs/dx/icdev-yaml-spec.md

@@ -0,0 +1,219 @@
+# icdev.yaml Specification
+
+The `icdev.yaml` project manifest is the single configuration file that tells ICDEV everything about your project. Drop it in your repository root and ICDEV auto-configures everything — compliance posture, CI/CD pipeline, dev profiles, security scanning, and deployment.
+
+---
+
+## Minimal Example
+
+```yaml
+version: 1
+project:
+  name: my-app
+  type: api
+  language: python
+impact_level: IL4
+```
+
+This is enough to get started. ICDEV uses sensible defaults for everything else.
+
+---
+
+## Full Reference
+
+```yaml
+# icdev.yaml — Full specification
+version: 1
+
+# ─── Project Identity ───────────────────────────────────────
+project:
+  name: my-app                    # Human-readable project name
+  id: proj-my-app                 # Unique project ID (auto-generated if omitted)
+  type: microservice              # See "Project Types" below
+  language: python                # Primary language (see "Supported Languages")
+  description: "Mission planning API for SOF operations"
+
+# ─── Classification ─────────────────────────────────────────
+impact_level: IL4                 # IL2 | IL4 | IL5 | IL6
+classification:
+  level: CUI                     # UNCLASSIFIED | CUI | SECRET
+  category: SP-CTI               # CUI category (SP-CTI, SP-EXPT, etc.)
+  cui_markings: true              # Apply CUI banners to generated files
+
+# ─── Compliance ──────────────────────────────────────────────
+compliance:
+  frameworks:                     # One or more compliance frameworks
+    - fedramp_high
+    - cmmc_l2
+    - cjis
+  ato:
+    status: active                # active | conditional | expired | none
+    boundary: "System X ATO"      # ATO boundary name
+    continuous_monitoring: true    # Enable cATO evidence auto-refresh
+  fips199:
+    confidentiality: high         # low | moderate | high
+    integrity: moderate
+    availability: moderate
+
+# ─── Dev Profile ─────────────────────────────────────────────
+profile:
+  scope: project                  # platform | tenant | program | project | user
+  template: dod_baseline          # Starter template (see quickstart.md for list)
+  overrides:                      # Optional overrides on top of template
+    style:
+      line_length: 120
+      indent_size: 4
+    testing:
+      min_coverage: 90
+    git:
+      commit_format: "conventional"
+      branch_strategy: trunk_based
+
+# ─── CI/CD Pipeline ─────────────────────────────────────────
+pipeline:
+  platform: auto                  # auto | github | gitlab (auto-detects from remote)
+
+  on_pr:                          # Checks that run on every pull request
+    - sast                        # Static application security testing
+    - dependency_audit            # Known vulnerability scan
+    - secret_detection            # Hardcoded secrets/credentials
+    - cui_check                   # CUI marking validation
+    - stig_check                  # STIG compliance (CAT1/CAT2/CAT3)
+    - unit_tests                  # pytest / JUnit / go test
+    - bdd_tests                   # behave / Cucumber / godog
+    - lint                        # Language-specific linter
+    - format_check                # Code formatting validation
+
+  on_merge:                       # Actions on merge to main/master
+    - ssp_generate                # System Security Plan regeneration
+    - poam_generate               # Plan of Action & Milestones
+    - sbom_generate               # Software Bill of Materials (CycloneDX)
+    - deploy_staging              # Deploy to staging environment
+    - cato_refresh                # cATO evidence update
+
+  on_schedule:                    # Periodic checks (cron)
+    - cve_triage                  # New CVE scanning (daily)
+    - isa_check                   # ISA expiry monitoring (weekly)
+    - cato_refresh                # cATO evidence freshness (daily)
+    - dependency_freshness        # Outdated dependency check (weekly)
+
+  gates:                          # Override default gate thresholds
+    stig_max_cat1: 0              # Block on any CAT1 finding (default: 0)
+    stig_max_cat2: 5              # Allow up to 5 CAT2 findings (default: 0)
+    min_coverage: 80              # Minimum test coverage % (default: 80)
+    max_critical_vulns: 0         # Block on critical vulnerabilities (default: 0)
+
+# ─── Deployment ──────────────────────────────────────────────
+deployment:
+  cloud: aws_govcloud             # aws_govcloud | aws | gcp | azure | on_prem
+  region: us-gov-west-1
+  platform: k8s                   # k8s | docker | ecs | lambda
+  infra_as_code: terraform        # terraform | ansible | both
+  container:
+    base_image: python:3.11-slim  # Overridden by dev profile if set
+    non_root: true
+    read_only_rootfs: true
+
+# ─── Integrations ────────────────────────────────────────────
+integrations:
+  jira:
+    instance_url: https://org.atlassian.net
+    project_key: MYAPP
+    sync: bidirectional            # push | pull | bidirectional
+  gitlab:
+    instance_url: https://gitlab.org.mil
+    project_id: 123
+  servicenow:
+    instance_url: https://org.service-now.com
+```
+
+---
+
+## Project Types
+
+| Type | Description | Default Scaffold |
+|------|-------------|------------------|
+| `api` | REST/GraphQL API service | Flask/FastAPI + pytest + OpenAPI |
+| `microservice` | Containerized microservice | API + Dockerfile + K8s manifests |
+| `monolith` | Traditional monolithic application | Full MVC scaffold |
+| `cli` | Command-line tool | argparse + tests + man page |
+| `data-pipeline` | Data processing pipeline | ETL scaffold + data validation |
+| `frontend` | Web frontend | React/Vue + eslint + Playwright |
+| `library` | Reusable library/package | Package scaffold + docs + publish |
+
+---
+
+## Supported Languages
+
+| Language | Key | Scaffold Types |
+|----------|-----|----------------|
+| Python | `python` | python-backend, api, cli, data-pipeline |
+| Java | `java` | java-backend |
+| Go | `go` | go-backend |
+| Rust | `rust` | rust-backend |
+| C# | `csharp` | csharp-backend |
+| TypeScript | `typescript` | typescript-backend, javascript-frontend |
+
+---
+
+## Defaults
+
+When fields are omitted, ICDEV uses these defaults:
+
+| Field | Default |
+|-------|---------|
+| `project.id` | Auto-generated from project name |
+| `impact_level` | `IL4` |
+| `classification.cui_markings` | `true` for IL4+, `false` for IL2 |
+| `compliance.frameworks` | Inferred from impact level (IL4 = FedRAMP Moderate) |
+| `profile.template` | `dod_baseline` for IL4+, `startup` for IL2 |
+| `pipeline.platform` | Auto-detected from `git remote` |
+| `pipeline.on_pr` | All checks enabled |
+| `pipeline.on_merge` | SSP + SBOM + staging deploy |
+| `deployment.cloud` | `aws_govcloud` for IL4+, `aws` for IL2 |
+| `deployment.platform` | `k8s` |
+
+---
+
+## Environment Variable Overrides
+
+Any `icdev.yaml` field can be overridden by environment variables for CI/CD flexibility:
+
+```bash
+# Override impact level in CI
+ICDEV_IMPACT_LEVEL=IL5
+
+# Override deployment target
+ICDEV_DEPLOYMENT_CLOUD=aws_govcloud
+ICDEV_DEPLOYMENT_REGION=us-gov-west-1
+
+# Override gate thresholds for specific environments
+ICDEV_GATE_MIN_COVERAGE=90
+ICDEV_GATE_STIG_MAX_CAT2=0
+```
+
+Environment variables take precedence over `icdev.yaml` values, which take precedence over defaults.
+
+---
+
+## Validation
+
+ICDEV validates `icdev.yaml` on every run. Common validation errors:
+
+```
+ERROR: impact_level IL6 requires classification.level = SECRET
+ERROR: cjis framework requires impact_level >= IL4
+ERROR: fedramp_high + deployment.cloud = aws (must be aws_govcloud for IL4+)
+WARNING: No compliance frameworks specified for IL4 project
+WARNING: cui_markings disabled but impact_level = IL5 (CUI markings required)
+```
+
+To validate without running anything:
+
+```bash
+python tools/project/validate_manifest.py --file icdev.yaml --json
+```
+
+Or ask Claude:
+
+> Validate my icdev.yaml configuration

icdev/data/docs/dx/integration-tiers.md

@@ -0,0 +1,279 @@
+# Integration Tiers
+
+ICDEV abstracts its complexity through three tiers. Each tier gives developers a different level of interaction — from fully invisible to fully explicit. Most teams combine Tier 1 (automatic pipeline) with Tier 2 (Claude Code conversations).
+
+---
+
+## Tier 1: Invisible (Zero Developer Interaction)
+
+### Concept
+
+ICDEV runs as infrastructure. Developers push code. Compliance, security, testing, and artifact generation happen automatically in the CI/CD pipeline. The developer never types an ICDEV command.
+
+### How It Works
+
+```
+Developer pushes code
+        |
+        v
+  CI/CD Pipeline (GitHub Actions / GitLab CI)
+        |
+        +-- SAST scan (bandit/gosec/eslint-security)
+        +-- Dependency audit (pip-audit/npm audit/govulncheck)
+        +-- Secret detection (detect-secrets)
+        +-- CUI marking validation
+        +-- STIG compliance check
+        +-- Unit + BDD test execution
+        +-- SBOM generation (CycloneDX)
+        |
+        v
+  PR Status Checks (pass/fail)
+        |
+  On merge to main:
+        |
+        +-- SSP regeneration
+        +-- POAM update
+        +-- cATO evidence refresh
+        +-- Deployment pipeline trigger
+```
+
+### Setup
+
+1. Drop an [`icdev.yaml`](icdev-yaml-spec.md) in your repo root
+2. Add the ICDEV GitHub Action or GitLab CI include (see [CI/CD Integration](ci-cd-integration.md))
+3. Push. That's it.
+
+### What the Developer Sees
+
+- Green/red status checks on PRs
+- Inline PR comments for security findings
+- Automated compliance reports in the `artifacts/` directory
+- Nothing else. ICDEV is invisible.
+
+### When to Use
+
+- You want compliance as a zero-effort default
+- Your team shouldn't need to think about NIST 800-53, STIG, or CUI markings
+- You want every push automatically validated against your security posture
+- You're running cATO and need evidence to stay current continuously
+
+---
+
+## Tier 2: Conversational (Natural Language via Claude Code)
+
+### Concept
+
+Developers talk to Claude Code in plain English. Claude reads the project's `icdev.yaml`, dev profile, and compliance posture, then orchestrates the right ICDEV tools automatically. The developer never calls a Python script.
+
+### How It Works
+
+```
+Developer: "Build a REST API for user management with RBAC"
+        |
+        v
+  Claude Code reads:
+    - icdev.yaml (project config)
+    - Dev profile (coding standards via cascade resolution)
+    - CLAUDE.md (orchestration instructions)
+    - goals/build_app.md (ATLAS workflow)
+        |
+        v
+  Claude orchestrates (developer doesn't see this):
+    1. tools/builder/test_writer.py      -- TDD RED phase
+    2. tools/builder/code_generator.py   -- TDD GREEN phase
+    3. tools/builder/linter.py           -- REFACTOR phase
+    4. tools/security/sast_runner.py     -- Security scan
+    5. tools/compliance/control_mapper.py -- Map to NIST controls
+    6. tools/compliance/cui_marker.py    -- Apply CUI markings
+        |
+        v
+  Developer gets: working code, tests, compliance artifacts
+```
+
+### Common Conversations
+
+**Building features:**
+> Build a user authentication module with CAC/PIV support
+
+**Checking compliance:**
+> What's our FedRAMP compliance status? Are there any open POAM items?
+
+**Fixing issues:**
+> Fix the failing STIG check on the database module
+
+**Running security scans:**
+> Run a full security scan and fix any critical findings
+
+**Managing dev profiles:**
+> Show me our project's coding standards. Update the line length to 120.
+
+**Generating artifacts:**
+> Generate our SSP and SBOM for the next ATO review
+
+**Intake and planning:**
+> We need a mission planning tool for IL5. Start the requirements intake.
+
+### Slash Commands (Shortcuts)
+
+For frequently used workflows, ICDEV provides slash commands that are shorthand for common requests:
+
+| Command | What It Does | Equivalent Natural Language |
+|---------|-------------|----------------------------|
+| `/icdev-build` | TDD build cycle | "Build this feature using TDD" |
+| `/icdev-test` | Run full test suite | "Run all tests" |
+| `/icdev-comply` | Generate ATO artifacts | "Generate compliance artifacts" |
+| `/icdev-secure` | Security scanning | "Run security scans" |
+| `/icdev-deploy` | Generate IaC + pipeline | "Deploy this to staging" |
+| `/icdev-intake` | Requirements intake | "Start requirements intake" |
+| `/icdev-status` | Project dashboard | "Show project status" |
+| `/icdev-review` | Code review gates | "Review this code for merge" |
+
+You don't need to memorize these. Just talk to Claude naturally — it knows when to use them.
+
+### When to Use
+
+- Day-to-day feature development
+- Exploring compliance status or fixing findings
+- Requirements intake with stakeholders
+- Any task where you'd normally need to look up which ICDEV tool to run
+
+---
+
+## Tier 3: Programmatic (REST API / MCP / Direct CLI)
+
+### Concept
+
+For teams building automation on top of ICDEV — custom CI/CD scripts, integration tools, or batch operations — ICDEV exposes its full capability through REST API, MCP Streamable HTTP, and direct Python CLI.
+
+### REST API
+
+The SaaS API gateway exposes all ICDEV functionality via standard HTTP:
+
+```bash
+# Authenticate
+export ICDEV_TOKEN="icdev_abc123..."
+
+# Create a project
+curl -X POST https://icdev.example.com/api/v1/projects \
+  -H "Authorization: Bearer $ICDEV_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"name": "my-app", "type": "microservice", "impact_level": "IL4"}'
+
+# Run compliance assessment
+curl https://icdev.example.com/api/v1/projects/proj-123/compliance \
+  -H "Authorization: Bearer $ICDEV_TOKEN"
+
+# Generate SSP
+curl -X POST https://icdev.example.com/api/v1/compliance/ssp \
+  -H "Authorization: Bearer $ICDEV_TOKEN" \
+  -d '{"project_id": "proj-123"}'
+
+# Resolve dev profile
+curl https://icdev.example.com/api/v1/dev-profiles/resolve/project/proj-123 \
+  -H "Authorization: Bearer $ICDEV_TOKEN"
+```
+
+Full API documentation: Swagger UI at `/api/v1/docs` when running the API gateway.
+
+### MCP Streamable HTTP
+
+For Claude Code clients connecting to ICDEV as an MCP server:
+
+```
+POST /mcp/v1/
+Content-Type: application/json
+
+{"jsonrpc": "2.0", "method": "tools/call", "params": {"name": "scaffold", "arguments": {"type": "python-backend", "name": "my-app"}}, "id": 1}
+```
+
+14 MCP servers expose 100+ tools. See CLAUDE.md for the full tool list.
+
+### Direct Python CLI
+
+Every ICDEV tool can be called directly. This is the lowest-level interface:
+
+```bash
+# Scaffold a project
+python tools/builder/scaffolder.py --type python-backend --name my-app
+
+# Run compliance scan
+python tools/compliance/ssp_generator.py --project-id proj-123
+
+# Resolve dev profile cascade
+python tools/builder/dev_profile_manager.py --scope project --scope-id proj-123 --resolve --json
+
+# Auto-detect coding standards from repo
+python tools/builder/profile_detector.py --repo-path /path/to/repo --json
+```
+
+### When to Use
+
+- Custom CI/CD pipeline scripts
+- Integration with external tools (Jira, ServiceNow, GitLab)
+- Batch operations across multiple projects
+- Building custom dashboards or reporting tools
+- Automated testing of ICDEV itself
+
+---
+
+## Choosing Your Tier
+
+```
+                              Developer Effort
+                    Low ◄─────────────────────► High
+
+Tier 1 (Invisible)  ████░░░░░░░░░░░░░░░░░░░░░░
+Tier 2 (Claude)     ░░░░████████░░░░░░░░░░░░░░
+Tier 3 (API/CLI)    ░░░░░░░░░░░░░░████████████
+
+                              Control & Flexibility
+                    Low ◄─────────────────────► High
+
+Tier 1 (Invisible)  ████████░░░░░░░░░░░░░░░░░░
+Tier 2 (Claude)     ░░░░░░████████████░░░░░░░░
+Tier 3 (API/CLI)    ░░░░░░░░░░░░░░░░██████████
+```
+
+### Recommended Combinations
+
+| Team Profile | Recommended Tiers | Why |
+|-------------|-------------------|-----|
+| **App Dev Team** | Tier 1 + Tier 2 | Pipeline auto-runs compliance; Claude handles feature building |
+| **DevSecOps Team** | Tier 1 + Tier 3 | Pipeline enforces gates; API for custom tooling and reporting |
+| **Platform Team** | Tier 2 + Tier 3 | Claude for exploration; API for multi-tenant management |
+| **ISSO/Compliance** | Tier 2 | Claude for querying compliance status, generating reports |
+| **Solo Developer** | Tier 2 | Just talk to Claude. It handles everything. |
+
+---
+
+## How the Tiers Connect
+
+All three tiers ultimately call the same underlying ICDEV tools. The difference is the interface:
+
+```
+Tier 1 (Pipeline)     Tier 2 (Claude)     Tier 3 (API)
+      |                     |                   |
+      v                     v                   v
++----------------------------------------------------------+
+|                    GOTCHA Framework                        |
+|  Goals -> Orchestration -> Tools -> Args -> Context       |
++----------------------------------------------------------+
+      |
+      v
++----------------------------------------------------------+
+|              Deterministic Python Tools                    |
+|  (Same tools, same outputs, regardless of entry point)   |
++----------------------------------------------------------+
+      |
+      v
++----------------------------------------------------------+
+|                    SQLite / PostgreSQL                     |
+|  (146 tables: compliance, security, profiles, audit)      |
++----------------------------------------------------------+
+```
+
+This means:
+- A compliance artifact generated by the pipeline (Tier 1) is identical to one generated by Claude (Tier 2) or the API (Tier 3)
+- Dev profile resolution works the same everywhere
+- Audit trail captures actions from all tiers
+- Security gates enforce the same rules regardless of entry point