icdev 0.0.3__py3-none-any.whl

goals/pr_intelligence.md

@@ -0,0 +1,78 @@
+# CUI // SP-CTI
+
+# F6: PR Intelligence
+
+## Purpose
+
+Analyze pull requests for security risks, compliance impact, and code quality before merge. Provides pre-merge risk scoring, automatic security prechecks, compliance policy validation, and consolidated reports for reviewers.
+
+## Prerequisites
+
+- `data/icdev.db` initialized with project and compliance tables
+- Git repository accessible from working directory
+- For auto-analysis: CI webhook configured via `tools/ci/triggers/webhook_server.py`
+
+## Workflow Steps
+
+### 1. Analyze PR
+```bash
+python tools/ci/pr_intelligence.py --analyze --project-id "sparkpilot" --pr-diff /path/to/diff --json
+```
+**Expected output:** JSON with risk score (0-100), changed file analysis, new dependency flags, API surface changes, and reviewer recommendations.
+
+### 2. Run Security Precheck
+```bash
+python tools/ci/pr_intelligence.py --security-precheck --project-id "sparkpilot" --pr-diff /path/to/diff --json
+```
+**Expected output:** JSON with secret detection results, dependency vulnerability scan, SAST findings, and pass/fail gate status.
+
+### 3. Run Compliance Precheck
+```bash
+python tools/ci/pr_intelligence.py --compliance-precheck --project-id "sparkpilot" --pr-diff /path/to/diff --json
+```
+**Expected output:** JSON with CUI marking check, control impact assessment, boundary change detection, and compliance gate status.
+
+### 4. Generate Report
+```bash
+python tools/ci/pr_intelligence.py --report --project-id "sparkpilot" --pr-id "PR-42" --json
+```
+**Expected output:** JSON with consolidated report including risk score, security findings, compliance impact, code quality metrics, and recommended actions.
+
+### 5. Get History
+```bash
+python tools/ci/pr_intelligence.py --history --project-id "sparkpilot" --last-n 20 --json
+```
+**Expected output:** JSON array of past PR analyses with risk trends and recurring issue patterns.
+
+## Decision Reference
+
+| Decision | Description |
+|----------|-------------|
+| D-INV-21 | Risk scoring uses weighted sum: security (0.4) + compliance (0.3) + complexity (0.2) + size (0.1) |
+| D-INV-22 | Security precheck reuses existing SAST, dep audit, and secret detection tools |
+| D-INV-23 | Compliance precheck checks boundary impact via boundary_analyzer.py |
+| D-INV-24 | PR analysis results stored in append-only table for trend analysis |
+
+## Edge Cases
+
+- Empty diff returns zero-risk score with note
+- Binary files in diff flagged but not analyzed for content
+- PR touching compliance tools triggers elevated review requirement
+- Missing project configuration returns setup instructions
+
+## Tier Gating
+
+| Capability | Community | Pro |
+|------------|-----------|-----|
+| Manual PR analysis | Yes | Yes |
+| Security precheck | Yes | Yes |
+| Compliance precheck | Yes | Yes |
+| Auto-analysis on PR open | No | Yes |
+| Compliance policy enforcement | No | Yes |
+
+## Security
+
+- PR analysis results are append-only (NIST AU compliant)
+- Secret detection runs before any content is logged
+- CUI markings applied to exported reports
+- Diff content never persisted -- only analysis results stored

goals/requirements_intake.md

@@ -0,0 +1,213 @@
+# Goal: Requirements Intake & Decomposition (RICOAS Phase 1)
+
+## Purpose
+
+Transform vague customer requirements into structured, decomposed, MBSE-traced, compliance-validated work items through AI-driven conversational intake.
+
+## When to Use
+
+- Customer provides new requirements (SOW, CDD, CONOPS, verbal)
+- Existing requirements need refinement or gap analysis
+- Requirements need SAFe decomposition (Epic > Feature > Story)
+- BDD acceptance criteria generation needed
+- Readiness assessment before proceeding to architecture/build
+
+## Workflow
+
+### Stage 1: Session Setup
+
+1. Create intake session: `create_intake_session` (MCP) or `python tools/requirements/intake_engine.py --project-id <id> --customer-name <name> --json`
+2. Session stores: customer info, impact level (IL2-IL6), classification, ATO context
+
+### Stage 2: Conversational Intake
+
+1. Process customer messages via `process_intake_turn` (MCP) or CLI `--message`
+2. Engine extracts requirements from each turn automatically
+3. Detects ambiguities in real-time (patterns from context/requirements/ambiguity_patterns.json)
+4. Detects gap signals (security, performance, data, compliance)
+5. Detects ATO boundary impact signals
+6. Every 5 turns (configurable), auto-runs gap detection and readiness scoring
+
+### Stage 3: Document Upload (Optional)
+
+1. Customer uploads SOW/CDD/CONOPS via `upload_document`
+2. Extract requirements via `extract_document`
+3. Extracted requirements merge into session's requirement set
+4. Supports: PDF (pypdf), DOCX (python-docx), TXT, MD
+
+### Stage 4: Gap Detection & Readiness Scoring
+
+1. Run gap detection: `detect_gaps` — checks security, compliance, testability, interfaces, data
+2. Gaps reference NIST 800-53 controls and provide remediation recommendations
+3. Run readiness scoring: `score_readiness` — 5 dimensions (completeness, clarity, feasibility, compliance, testability)
+4. Thresholds: 0.7 = proceed to decomposition, 0.8 = proceed to COA, 0.9 = proceed to implementation
+5. Score trend tracked across turns to show progress
+
+### Stage 5: SAFe Decomposition
+
+1. Decompose requirements: `decompose_requirements` with target level (epic/feature/story)
+2. Generates SAFe hierarchy: Epic > Capability > Feature > Story > Enabler
+3. T-shirt size estimation per item (XS through XXL)
+4. WSJF scoring for prioritization
+5. Optional BDD acceptance criteria (Gherkin Given/When/Then)
+
+### Stage 6: Export & Handoff
+
+1. Export requirements: `python tools/requirements/intake_engine.py --session-id <id> --export --json`
+2. Decomposed items ready for Architect agent (ATLAS workflow)
+3. Requirements link to digital thread for MBSE traceability
+4. Audit trail records all intake events
+
+---
+
+## Visual Workflow
+
+### Intake Pipeline Flowchart
+
+```mermaid
+flowchart TD
+    A["Stage 1: Session Setup"] --> B["Stage 2: Conversational Intake"]
+    B --> C["Stage 3: Document Upload"]
+    C --> D["Stage 4: Gap Detection & Readiness"]
+    D --> E{Readiness Score?}
+    E -->|"score < 0.7"| B
+    E -->|"score >= 0.7"| F["Stage 5: SAFe Decomposition"]
+    F --> G["Stage 6: Export & Handoff"]
+
+    style A fill:#1a3a5c,stroke:#4a90d9,color:#e0e0e0
+    style B fill:#1a3a5c,stroke:#4a90d9,color:#e0e0e0
+    style C fill:#1a3a5c,stroke:#4a90d9,color:#e0e0e0
+    style D fill:#3a3a1a,stroke:#ffc107,color:#e0e0e0
+    style E fill:#3a2a1a,stroke:#e8590c,color:#e0e0e0
+    style F fill:#1a3a5c,stroke:#4a90d9,color:#e0e0e0
+    style G fill:#1a3a2d,stroke:#28a745,color:#e0e0e0
+```
+
+### SAFe Hierarchy
+
+```mermaid
+classDiagram
+    Epic "1" --> "*" Capability : decomposes into
+    Capability "1" --> "*" Feature : decomposes into
+    Feature "1" --> "*" Story : decomposes into
+    Feature "1" --> "*" Enabler : decomposes into
+
+    class Epic {
+        +String id
+        +String title
+        +String description
+        +String wsjf_score
+        +String t_shirt_size
+    }
+
+    class Capability {
+        +String id
+        +String title
+        +String epic_id
+        +String priority
+    }
+
+    class Feature {
+        +String id
+        +String title
+        +String capability_id
+        +String acceptance_criteria
+        +String t_shirt_size
+    }
+
+    class Story {
+        +String id
+        +String title
+        +String feature_id
+        +String bdd_scenarios
+        +String story_points
+    }
+
+    class Enabler {
+        +String id
+        +String title
+        +String feature_id
+        +String enabler_type
+        +String t_shirt_size
+    }
+```
+
+---
+
+## Tools Used
+
+| Tool | Purpose |
+|------|---------|
+| tools/requirements/intake_engine.py | Conversational intake, session management |
+| tools/requirements/gap_detector.py | Gap and ambiguity detection |
+| tools/requirements/readiness_scorer.py | 5-dimension readiness scoring |
+| tools/requirements/decomposition_engine.py | SAFe hierarchy decomposition |
+| tools/requirements/document_extractor.py | Document upload and extraction |
+| tools/mcp/requirements_server.py | MCP server (10 tools) |
+
+## Args
+
+- `args/ricoas_config.yaml` — Readiness weights, thresholds, gap detection settings, cost models
+
+## Context
+
+- `context/requirements/gap_patterns.json` — 10 gap detection patterns with NIST mappings
+- `context/requirements/ambiguity_patterns.json` — 15 ambiguity patterns with clarification suggestions
+- `context/requirements/safe_templates.json` — SAFe hierarchy templates and WSJF formula
+- `context/requirements/document_extraction_rules.json` — Extraction rules per document type
+- `context/requirements/readiness_rubric.json` — 5-dimension scoring rubric
+
+## Hard Prompts
+
+- `hardprompts/requirements/intake_conversation.md` — Intake agent system prompt
+- `hardprompts/requirements/gap_detection.md` — Gap analysis prompt
+- `hardprompts/requirements/decomposition.md` — SAFe decomposition prompt
+- `hardprompts/requirements/document_extraction.md` — Document extraction prompt
+- `hardprompts/requirements/bdd_generation.md` — BDD criteria generation prompt
+- `hardprompts/requirements/readiness_assessment.md` — Readiness scoring prompt
+
+---
+
+## Edge Cases
+
+- Customer provides contradictory requirements → flag as gap with both references
+- Document extraction finds 0 requirements → suggest different document type or manual entry
+- Readiness score stuck below threshold → show trend, suggest specific areas to address
+- Session resumed after long gap → summarize previous context to customer
+- Impact level change mid-session → re-run boundary analysis on all requirements
+
+---
+
+## Success Criteria
+
+- All requirements captured with type, priority, and source
+- Readiness score >= 0.7 before decomposition
+- Zero unresolved critical gaps
+- SAFe items have acceptance criteria and estimates
+- Full audit trail of intake process
+
+---
+
+## GOTCHA Layer Mapping
+
+| Intake Stage | GOTCHA Layer |
+|--------------|--------------|
+| Session Setup | Goals (define what to capture) |
+| Conversational Intake | Orchestration (AI guides conversation) |
+| Document Upload | Tools (extraction scripts) |
+| Gap Detection | Context (gap patterns, ambiguity patterns) |
+| Readiness Scoring | Args (thresholds, weights) |
+| SAFe Decomposition | Hard Prompts (decomposition templates) |
+
+---
+
+## Related Files
+
+- **Goal:** `goals/build_app.md` — ATLAS workflow (receives decomposed requirements)
+- **Goal:** `goals/mbse_integration.md` — MBSE digital thread (links to requirements)
+- **Goal:** `goals/compliance_workflow.md` — Compliance artifacts (informed by gap analysis)
+- **Skill:** `.claude/skills/sparkpilot-intake/SKILL.md` — Claude Code slash command
+
+---
+
+## Changelog

goals/secure_by_design.md

@@ -0,0 +1,135 @@
+# CUI // SP-CTI
+# Goal: Secure by Design Assessment & Remediation
+
+## Purpose
+Assess, remediate, and maintain CISA Secure by Design compliance aligned with
+Cloudyrion's 8-Pillar SbD Framework. Applies to ICDEV, all modules, and child apps.
+
+## When to Use
+- New project initialization (post-Golden Path scaffold)
+- Pre-ATO compliance workflow (Step 15 of compliance_workflow.md)
+- After significant architectural changes
+- Quarterly SbD posture review
+- When onboarding a new child application
+
+## Prerequisites
+- Project registered in icdev.db
+- Project directory accessible for auto-checks
+- SECURITY.md and .well-known/security.txt present (CISA Commitment 5)
+
+---
+
+## Workflow Steps
+
+### Step 1: Run SbD Assessment
+```bash
+python tools/compliance/sbd_assessor.py \
+  --project-id "<project_id>" \
+  --project-dir "<path>" \
+  --gate \
+  --json
+```
+**Expected:** JSON with 35 requirement results, domain summary, gate result.
+**Gate criteria:** 0 critical-priority requirements with status `not_satisfied`.
+
+### Step 2: Review CISA 7 Commitments Status
+Check these specifically (all must be satisfied for CISA pledge compliance):
+1. **MFA** (SBD-01) — Multi-factor authentication enforced
+2. **Default Passwords** (SBD-02) — Zero hardcoded credentials
+3. **Vuln Class Reduction** (SBD-03, SBD-04) — Memory-safe language + tooling
+4. **Security Patching** (SBD-05) — Dependabot/Renovate configured
+5. **Vuln Disclosure** (SBD-06) — SECURITY.md present
+6. **CVE Transparency** (SBD-07) — CVE tracking process documented
+7. **Intrusion Evidence** (SBD-08, SBD-09, SBD-10) — Audit logging complete
+
+### Step 3: Review Exception Registry
+```bash
+python tools/compliance/sbd_assessor.py \
+  --project-id "<project_id>" \
+  --list-exceptions \
+  --json
+```
+**Check for:**
+- Expired exceptions (must be renewed or remediated)
+- Exceptions aging > 90 days (Cloudyrion anti-pattern: lingering exceptions)
+- High/critical blast-radius exceptions without compensating controls
+
+### Step 4: Remediate Findings
+For each `not_satisfied` requirement:
+1. Identify the root cause from evidence/details
+2. Implement the fix
+3. Re-run the specific domain assessment to verify
+4. If remediation is not feasible, register an exception:
+```bash
+python tools/compliance/sbd_assessor.py \
+  --project-id "<project_id>" \
+  --register-exception \
+  --requirement-id "SBD-XX" \
+  --title "Description" \
+  --justification "Why this cannot be remediated now" \
+  --owner "person@org" \
+  --duration-days 90 \
+  --blast-radius medium
+```
+
+### Step 5: Generate SbD Report
+```bash
+python tools/compliance/sbd_report_generator.py \
+  --project-id "<project_id>" \
+  --json
+```
+
+### Step 6: Update Developer Scorecard
+```bash
+python tools/analytics/scorecard.py \
+  --project-id "<project_id>" \
+  --compute \
+  --json
+```
+**Check:** `sbd_posture` dimension score >= 80 for Level 3 compliance.
+
+### Step 7: Cross-Framework Mapping (Optional)
+```bash
+python tools/compliance/crosswalk_engine.py \
+  --framework cisa_sbd \
+  --project-id "<project_id>" \
+  --coverage
+```
+
+---
+
+## Cloudyrion 8-Pillar Alignment
+
+| Pillar | ICDEV Implementation | Key Tools |
+|--------|---------------------|-----------|
+| P1: Proactive Design | Threat modeling at project kickoff | `threat_modeler.py` |
+| P2: Holistic Stack | SBOM + supply chain + firmware SBOM | `sbom_generator.py`, `scrm_assessor.py` |
+| P3: Shared Ownership | Security champion per project | Developer Scorecard `sbd_posture` |
+| P4: Adaptive Architecture | Plugin MCP architecture, GOTCHA layers | `golden_path.py` |
+| P5: Assume Breach | ZTA 7-pillar, mTLS, NetworkPolicy | `zta_maturity_scorer.py` |
+| P6: Risk-Driven | Readiness scoring, Monte Carlo | `readiness_scorer.py`, `monte_carlo.py` |
+| P7: Customer-First | Secure defaults, progressive compliance | `golden_path.py`, SECURITY.md |
+| P8: Continuous Improvement | Harness trace analyzer, knowledge self-heal | `trace_analyzer.py` |
+
+## Gates
+- **SbD gate blocks on:** critical SBD requirements not satisfied, default credentials, no MFA, no VDP, stack traces in production
+- **Exception gate blocks on:** any expired exceptions (must renew or remediate)
+- **Scorecard gate:** `sbd_posture` score < 60 = FAIL
+
+## Child App Inheritance
+Every child app scaffolded via Golden Path automatically receives:
+- `SECURITY.md` (vulnerability disclosure policy)
+- `.well-known/security.txt` (RFC 9116)
+- `args/sbd_gates.yaml` (SbD gate configuration)
+- CUI markings on all generated files
+- `.gitignore` excluding secrets
+
+## Related Goals
+- `compliance_workflow.md` — SbD is Step 15 of the ATO pipeline
+- `security_scan.md` — SAST, dependency audit, secret detection
+- `zero_trust_architecture.md` — ZTA 7-pillar maturity
+- `harness_engineering.md` — Maturity assessment, trace analysis
+
+////////////////////////////////////////////////////////////////////
+CUI // SP-CTI | Department of Defense
+////////////////////////////////////////////////////////////////////