icdev 0.0.3__py3-none-any.whl

docs/adr/sbd-decisions.md

@@ -0,0 +1,109 @@
+# CUI // SP-CTI
+# Secure by Design — Architecture Decision Records
+
+**Total decisions:** 7
+**Last updated:** 2026-03-08
+
+| ID | Status | Decision |
+|----|--------|----------|
+| D-SBD-1 | Accepted | Cloudyrion 8-Pillar SbD Framework mapped to all 35 SBD requirements via `sbd_pillars` field |
+| D-SBD-2 | Accepted | Security exception registry in `sbd_exceptions` table (active/expired/renewed lifecycle, max 365 days) |
+| D-SBD-3 | Accepted | Exception aging gate: expired exceptions block deployment (Cloudyrion anti-pattern: lingering exceptions) |
+| D-SBD-4 | Accepted | CISA SbD added to crosswalk engine as `cisa_sbd` framework key (implement once, satisfy many) |
+| D-SBD-5 | Accepted | Golden Path child apps auto-inherit SECURITY.md, .well-known/security.txt, and args/sbd_gates.yaml |
+| D-SBD-6 | Accepted | Developer Scorecard expanded to 6 dimensions (sbd_posture=0.20 weight, penalizes expired exceptions) |
+| D-SBD-7 | Accepted | SbD goal workflow: 7-step assess-review-remediate-report cycle with Cloudyrion pillar alignment |
+
+---
+
+## D-SBD-1: Cloudyrion 8-Pillar SbD Framework mapped to all 35 SBD requirements
+
+**Status:** Accepted
+**Date:** 2026-03-08
+**Context:** CISA Secure by Design requirements need organizational alignment through a structured framework. Cloudyrion's 8-Pillar model provides this structure.
+**Decision:** Cloudyrion 8-Pillar SbD Framework mapped to all 35 SBD requirements via `sbd_pillars` field
+**Consequences:**
+- All 35 SBD requirements tagged with their Cloudyrion pillar.
+- Pillar-level rollup reporting enabled.
+- Framework alignment visible in assessment output.
+
+---
+
+## D-SBD-2: Security exception registry in `sbd_exceptions` table
+
+**Status:** Accepted
+**Date:** 2026-03-08
+**Context:** Security exceptions must be tracked with clear lifecycle management to prevent indefinite waivers.
+**Decision:** Security exception registry in `sbd_exceptions` table (active/expired/renewed lifecycle, max 365 days)
+**Consequences:**
+- Three lifecycle states: active, expired, renewed.
+- Maximum 365-day exception duration prevents permanent waivers.
+- Exception history preserved for audit.
+
+---
+
+## D-SBD-3: Exception aging gate blocks deployment
+
+**Status:** Accepted
+**Date:** 2026-03-08
+**Context:** Security posture must be maintained. Lingering expired exceptions represent unmitigated security risks (Cloudyrion anti-pattern).
+**Decision:** Exception aging gate: expired exceptions block deployment (Cloudyrion anti-pattern: lingering exceptions)
+**Consequences:**
+- Expired exceptions are hard blockers for deployment.
+- Forces timely exception renewal or remediation.
+- Prevents the "lingering exception" anti-pattern.
+
+---
+
+## D-SBD-4: CISA SbD added to crosswalk engine
+
+**Status:** Accepted
+**Date:** 2026-03-08
+**Context:** CISA Secure by Design must integrate with existing compliance crosswalk for unified control mapping.
+**Decision:** CISA SbD added to crosswalk engine as `cisa_sbd` framework key (implement once, satisfy many)
+**Consequences:**
+- Implementing NIST controls auto-populates SbD status via crosswalk.
+- Single implementation satisfies multiple framework requirements.
+- Consistent with existing crosswalk patterns (FedRAMP, CMMC, 800-171).
+
+---
+
+## D-SBD-5: Golden Path child apps auto-inherit security artifacts
+
+**Status:** Accepted
+**Date:** 2026-03-08
+**Context:** Scaffolded child applications must inherit security posture from the parent to maintain SbD compliance from day one.
+**Decision:** Golden Path child apps auto-inherit SECURITY.md, .well-known/security.txt, and args/sbd_gates.yaml
+**Consequences:**
+- Child apps start with security artifacts pre-configured.
+- SECURITY.md provides vulnerability disclosure policy.
+- security.txt follows RFC 9116 standard.
+- SbD gates enforced from first deployment.
+
+---
+
+## D-SBD-6: Developer Scorecard expanded to 6 dimensions
+
+**Status:** Accepted
+**Date:** 2026-03-08
+**Context:** Security posture must be visible in project health scoring. SbD compliance is a first-class quality dimension.
+**Decision:** Developer Scorecard expanded to 6 dimensions (sbd_posture=0.20 weight, penalizes expired exceptions)
+**Consequences:**
+- SbD posture is 20% of overall health score.
+- Expired exceptions reduce the score.
+- Incentivizes proactive security exception management.
+
+---
+
+## D-SBD-7: SbD goal workflow: 7-step cycle
+
+**Status:** Accepted
+**Date:** 2026-03-08
+**Context:** Secure by Design assessment needs a structured workflow that aligns with Cloudyrion's pillar model.
+**Decision:** SbD goal workflow: 7-step assess-review-remediate-report cycle with Cloudyrion pillar alignment
+**Consequences:**
+- Seven-step cycle provides structured remediation path.
+- Cloudyrion pillar alignment in each step.
+- Report generation at cycle end for stakeholder review.
+
+---

docs/adr/scale-engine-decisions.md

@@ -0,0 +1,108 @@
+# CUI // SP-CTI
+# Scale Engine — Architecture Decision Records
+
+**Total decisions:** 7
+**Last updated:** 2026-03-08
+
+| ID | Status | Decision |
+|----|--------|----------|
+| D-SC-1 | Accepted | Scale Engine uses ThreadPoolExecutor wrapping existing sync connectors (no ABC changes) |
+| D-SC-2 | Accepted | Per-connector-type connection pools (key = connector_name) |
+| D-SC-3 | Accepted | WAL + batch flush for sync log and audit writes (single writer thread) |
+| D-SC-4 | Accepted | Fixed limits (configurable max_workers, max_concurrent_syncs via YAML) |
+| D-SC-5 | Accepted | Semaphore enforces max_concurrent_syncs (makes existing config value real) |
+| D-SC-6 | Accepted | stdlib only (concurrent.futures, threading, queue); psutil optional for backpressure |
+| D-SC-7 | Accepted | Append-only audit trail preserved (INSERT only in WriteBatcher, NIST AU) |
+
+---
+
+## D-SC-1: Scale Engine uses ThreadPoolExecutor wrapping existing sync connectors
+
+**Status:** Accepted
+**Date:** 2026-03-08
+**Context:** Sync connectors need parallel execution without modifying existing connector abstract base classes.
+**Decision:** Scale Engine uses ThreadPoolExecutor wrapping existing sync connectors (no ABC changes)
+**Consequences:**
+- Existing connectors work without modification.
+- ThreadPoolExecutor provides parallel execution.
+- No changes to connector ABC or existing implementations.
+
+---
+
+## D-SC-2: Per-connector-type connection pools
+
+**Status:** Accepted
+**Date:** 2026-03-08
+**Context:** Different connector types have different connection characteristics and limits.
+**Decision:** Per-connector-type connection pools (key = connector_name)
+**Consequences:**
+- Each connector type maintains its own connection pool.
+- Pool sizes can be tuned per connector type.
+- Prevents one connector type from exhausting shared resources.
+
+---
+
+## D-SC-3: WAL + batch flush for sync log and audit writes
+
+**Status:** Accepted
+**Date:** 2026-03-08
+**Context:** High-throughput sync operations generate many log entries. Individual writes create I/O bottlenecks.
+**Decision:** WAL + batch flush for sync log and audit writes (single writer thread)
+**Consequences:**
+- Write-Ahead Logging reduces I/O contention.
+- Batch flush aggregates writes for efficiency.
+- Single writer thread prevents lock contention.
+
+---
+
+## D-SC-4: Fixed limits (configurable max_workers, max_concurrent_syncs via YAML)
+
+**Status:** Accepted
+**Date:** 2026-03-08
+**Context:** Configuration and templates must follow GOTCHA separation of concerns. Resource limits must be configurable per deployment.
+**Decision:** Fixed limits (configurable max_workers, max_concurrent_syncs via YAML)
+**Consequences:**
+- Resource limits defined in YAML configuration.
+- max_workers controls thread pool size.
+- max_concurrent_syncs controls parallel sync operations.
+
+---
+
+## D-SC-5: Semaphore enforces max_concurrent_syncs
+
+**Status:** Accepted
+**Date:** 2026-03-08
+**Context:** The max_concurrent_syncs config value existed but was not enforced at runtime. Actual enforcement was needed.
+**Decision:** Semaphore enforces max_concurrent_syncs (makes existing config value real)
+**Consequences:**
+- Threading semaphore provides hard limit on concurrent syncs.
+- Existing config value now has runtime enforcement.
+- Prevents resource exhaustion under load.
+
+---
+
+## D-SC-6: stdlib only; psutil optional for backpressure
+
+**Status:** Accepted
+**Date:** 2026-03-08
+**Context:** The system must operate in air-gapped environments without external dependencies for core scale engine functionality.
+**Decision:** stdlib only (concurrent.futures, threading, queue); psutil optional for backpressure
+**Consequences:**
+- No external network dependencies required at runtime.
+- Core functionality uses Python stdlib only.
+- psutil provides optional CPU/memory backpressure when available.
+
+---
+
+## D-SC-7: Append-only audit trail preserved
+
+**Status:** Accepted
+**Date:** 2026-03-08
+**Context:** Federal compliance requirements (NIST 800-53 AU controls) mandate immutable audit records even in high-throughput batch scenarios.
+**Decision:** Append-only audit trail preserved (INSERT only in WriteBatcher, NIST AU)
+**Consequences:**
+- Historical records cannot be modified or deleted.
+- WriteBatcher uses INSERT only operations.
+- Satisfies NIST AU compliance requirements.
+
+---

docs/adr/writeguard-decisions.md

@@ -0,0 +1,136 @@
+# CUI // SP-CTI
+# WriteGuard — Architecture Decision Records
+
+**Total decisions:** 9
+**Last updated:** 2026-03-08
+
+| ID | Status | Decision |
+|----|--------|----------|
+| D-WG-1 | Accepted | Independent `tools/writing/` directory for marketplace portability |
+| D-WG-2 | Accepted | Deterministic-first pipeline (regex before LLM) -- air-gap safe, reproducible |
+| D-WG-3 | Accepted | 5-layer style guide cascade with ISSO locks (Platform->Tenant->Program->Project->User) |
+| D-WG-5 | Accepted | Plagiarism via RAG similarity (0.85 threshold) |
+| D-WG-6 | Accepted | AI detection is deterministic (advisory-only) -- perplexity, burstiness, n-gram stats |
+| D-WG-7 | Accepted | Snippets follow knowledge_base.py CRUD + hybrid search pattern |
+| D-WG-8 | Accepted | GovProposal via read-only bridge -- never writes to proposal tables |
+| D-WG-9 | Accepted | Append-only analysis results (NIST AU compliant) |
+| D-WG-12 | Accepted | Two-tier routing per function -- grammar/readability deterministic, tone scanner, rewrite/coherence worker |
+
+---
+
+## D-WG-1: Independent `tools/writing/` directory for marketplace portability
+
+**Status:** Accepted
+**Date:** 2026-03-08
+**Context:** WriteGuard must be extractable as a standalone marketplace module without pulling in unrelated ICDEV dependencies.
+**Decision:** Independent `tools/writing/` directory for marketplace portability
+**Consequences:**
+- WriteGuard code is self-contained in `tools/writing/`.
+- Can be packaged independently for marketplace distribution.
+- Minimal coupling to other ICDEV modules.
+
+---
+
+## D-WG-2: Deterministic-first pipeline (regex before LLM)
+
+**Status:** Accepted
+**Date:** 2026-03-08
+**Context:** The system must operate in air-gapped environments. Writing analysis must be reproducible without LLM availability.
+**Decision:** Deterministic-first pipeline (regex before LLM) -- air-gap safe, reproducible
+**Consequences:**
+- No external network dependencies required for basic analysis.
+- Results are reproducible across runs.
+- LLM enhances but is not required for core functionality.
+
+---
+
+## D-WG-3: 5-layer style guide cascade with ISSO locks
+
+**Status:** Accepted
+**Date:** 2026-03-08
+**Context:** Style guide management must support organizational hierarchy with security officer override capability.
+**Decision:** 5-layer style guide cascade with ISSO locks (Platform->Tenant->Program->Project->User)
+**Consequences:**
+- Five priority levels for style guide resolution.
+- ISSO can lock style guides to prevent unauthorized changes.
+- Cascade resolution: higher layers override lower layers.
+
+---
+
+## D-WG-5: Plagiarism via RAG similarity (0.85 threshold)
+
+**Status:** Accepted
+**Date:** 2026-03-08
+**Context:** Plagiarism detection must use existing RAG infrastructure for similarity comparison.
+**Decision:** Plagiarism via RAG similarity (0.85 threshold)
+**Consequences:**
+- 0.85 cosine similarity threshold for plagiarism flagging.
+- Reuses existing RAG embedding infrastructure.
+- Threshold is configurable per project.
+
+---
+
+## D-WG-6: AI detection is deterministic (advisory-only)
+
+**Status:** Accepted
+**Date:** 2026-03-08
+**Context:** AI content detection must be reproducible and clearly advisory, not authoritative.
+**Decision:** AI detection is deterministic (advisory-only) -- perplexity, burstiness, n-gram stats
+**Consequences:**
+- Results are reproducible across runs.
+- Three statistical measures: perplexity, burstiness, n-gram analysis.
+- Advisory-only: does not block or modify content.
+
+---
+
+## D-WG-7: Snippets follow knowledge_base.py CRUD + hybrid search pattern
+
+**Status:** Accepted
+**Date:** 2026-03-08
+**Context:** Writing snippets must use the same storage and search patterns as the knowledge base for consistency.
+**Decision:** Snippets follow knowledge_base.py CRUD + hybrid search pattern
+**Consequences:**
+- Consistent CRUD interface across knowledge base and snippets.
+- Hybrid search (keyword + semantic) for snippet retrieval.
+- Reuses existing infrastructure.
+
+---
+
+## D-WG-8: GovProposal via read-only bridge
+
+**Status:** Accepted
+**Date:** 2026-03-08
+**Context:** WriteGuard integration with GovProposal must not risk corrupting proposal data.
+**Decision:** GovProposal via read-only bridge -- never writes to proposal tables
+**Consequences:**
+- WriteGuard can read proposal content for analysis.
+- No write operations to proposal tables.
+- Bridge pattern ensures data integrity.
+
+---
+
+## D-WG-9: Append-only analysis results
+
+**Status:** Accepted
+**Date:** 2026-03-08
+**Context:** Federal compliance requirements (NIST 800-53 AU controls) mandate immutable analysis records.
+**Decision:** Append-only analysis results (NIST AU compliant)
+**Consequences:**
+- Historical records cannot be modified or deleted.
+- Complete history of analysis results preserved.
+- Satisfies NIST AU compliance requirements.
+
+---
+
+## D-WG-12: Two-tier routing per function
+
+**Status:** Accepted
+**Date:** 2026-03-08
+**Context:** Different WriteGuard functions have different accuracy requirements. Grammar checking is deterministic; rewriting needs LLM.
+**Decision:** Two-tier routing per function -- grammar/readability deterministic, tone scanner, rewrite/coherence worker
+**Consequences:**
+- Grammar and readability analysis run deterministically (no LLM cost).
+- Tone scanning uses scanner-tier LLM.
+- Rewrite and coherence checking use worker-tier LLM.
+
+---