icdev 1.2.18__tar.gz → 1.2.20__tar.gz

icdev-1.2.20/CHANGELOG.md

@@ -0,0 +1,222 @@
+# [TEMPLATE: CUI // SP-CTI]
+
+# Changelog
+
+All notable changes to ICDEV™ are documented in this file.
+
+Format based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [1.2.19] - 2026-04-17
+
+### Added
+- **Failure Triage Reflex** (`tools/genesis/reflexes/failure_triage.py`) — wires `failure_triage.triage_once` into the Genesis daemon on a 30-min cadence (`args/genesis_config.yaml`). YELLOW tier. With `ICDEV_AUTOFIX_ENABLED=true` in `.env`, auto-review of failed kanban tasks now runs without manual invocation.
+
+### Changed
+- **Task-type whitelist** corrected from `{build, bug, chore, test, research}` → `{build, chore, fix, research, test}`. Counts from the live table (2026-04-17): `chore=742, build=307, fix=200, test=89, research=49, deploy=12`. `bug` had zero instances; `fix` was the third-most-common type but incorrectly excluded. `deploy` stays excluded — higher blast radius.
+
+## [1.2.18] - 2026-04-17
+
+### Added
+- **Failure Triage — Worktree-Apply Stage** (`tools/workflow/failure_triage.py`) — `apply_patch_in_worktree()` completes the auto-fix loop. Creates an isolated worktree at `.tmp/autofix/<task>__<sig>/` on branch `autofix/<task>-<sig>`, applies the LLM patch, runs the verification command, commits on success, rolls back the whole worktree + branch on failure. Pre-apply validation rejects: shell metacharacters / non-allowlisted prefixes in `verification_command`; path traversal, nonexistent files, files not in `diag.suspect_files`, non-unique `old_string`, deny-list prefix matches. Rate budget is only consumed after validation passes. Audit trail at `.tmp/kanban/autofix-audit/<task>__<sig>.json`.
+- **Second opt-in: `ICDEV_AUTOFIX_AUTOMERGE`** — even when a patch applies cleanly and verifies green, the `autofix/*` branch is NOT fast-forward merged into main unless this env is also set. Default off. Refuses to merge from a non-main checkout or a dirty working tree.
+
+### Tests
+- 35 unit tests (up from 20) — full coverage of the apply stage validation (allowlist, traversal, uniqueness, deny-list) and rejection paths (validation failures must not consume rate budget or create worktrees).
+
+## [1.2.17] - 2026-04-17
+
+### Added
+- **Failure Triage** (`tools/workflow/failure_triage.py`) — LLM-assisted review of kanban failures bridging the gap between `self_debug.py` (recurrence-only) and manual intervention. Two-tier LLM routing: Claude for diagnose (`failure_triage_diagnose`), Ollama for patch generation (`failure_triage_patch`). Conservative defaults — `ICDEV_AUTOFIX_ENABLED=false` by default, `--dry-run` default, confidence threshold 0.85, task-type whitelist, file deny-list, rolling 5-apply/hour rate cap. Generated patches are attached to `status='suggested'` Oracle cards for human review — auto-apply dispatcher is a separate follow-up.
+
+### Fixed
+- **NIST AI 600-1 Assessor** (`tools/compliance/nist_ai_600_1_assessor.py`) — typo `self._db_path` → `self.db_path`. Was being swallowed by broad `except Exception: pass`; every GAI-* check silently returned empty. Surfaced via regression pytest `-x` hitting `test_confabulation_check_satisfied_with_data`.
+- **Kanban depends-on E2E** (`tests/e2e_kanban_depends_on.py`) — step 5 (unblock-on-parent-done) now passes `bypass_verification: true` + audit reason to satisfy guard-22 (the move→done verification gate added 2026-04-14).
+
+## [1.2.8] - 2026-03-31
+
+### Added
+- **Network Design Canvas** — ACAS/Nessus vulnerability scan overlay with host-to-node matching and severity heat maps
+- **Network Design Canvas** — Natural language topology queries powered by deterministic graph algorithms (NetworkX) with local LLM fallback
+- **Network Design Canvas** — Cloud architecture diagram generation for all 6 CSPs
+- **Network Design Canvas** — Compliance audit page with per-device STIG tracking and exportable checklists
+- **Network Design Canvas** — 1,000+ device types, protocols, and interface constants
+- **Network Design Canvas** — Enhanced inventory export (CSV, JSON, YAML) with advanced filtering
+- **IBM Cloud IaC** — New Terraform generator for IBM Cloud (VPC, IKS, KMS, COS, LogDNA, SysDig)
+- **Azure IaC** — Major expansion: AKS, Key Vault, Front Door, Application Gateway, NSG rules
+- **GCP IaC** — Major expansion: GKE, Cloud KMS, Cloud Armor, VPC Service Controls
+- **OCI IaC** — Major expansion: OKE, Vault, WAF, Network Security Groups, Bastion
+- **SRE Operations** — Dashboard, runbook library, incident tracking, toil budgets, SLO monitoring
+- **Pipeline Canvas** — Visual CI/CD pipeline designer with drag-and-drop stages and YAML export
+
+## [Unreleased]
+
+### Added
+- **IQE v0.1 — ICDEV Query Engine** (`tools/iqe/`) — declarative `foreach / where / select` DSL for running compliance and network-health checks across all seven design-canvas databases. Ships with: hand-rolled recursive-descent parser (`parser.py`), typed AST dataclasses (`ast_nodes.py`), adapter-dispatching executor with SQL-injection-safe fallback (`executor.py`), and a 5-query NDC seed library under `context/iqe/queries/network/` (vendor inventory, BGP peer asymmetry, admin/oper mismatch, CAT I STIG open findings, capacity threshold). See `docs/features/phase-iqe-v0-1.md`.
+- Comprehensive test suite expansion (324+ new tests across 21 test files)
+- CI/CD pipeline for ICDEV™ itself (GitHub Actions + GitLab CI)
+- REST API endpoints for Phases 22-28 capabilities
+- Helm chart completion for all 15 agents
+- Project documentation (README, CONTRIBUTING, CHANGELOG)
+
+## [Phase 29-32] - 2026-02-XX
+
+### Added
+- Dashboard authentication with per-user API keys and SHA-256 hashing (D169-D172)
+- RBAC with 5 roles: admin, pm, developer, isso, co (D172)
+- Activity feed merging audit trail and hook events via UNION ALL query (D174)
+- BYOK (Bring Your Own Key) LLM key management with Fernet AES-256 encryption (D175-D178)
+- Usage tracking and cost dashboard per-user and per-provider (D177)
+- Spec-kit pattern tools: quality checker, consistency analyzer, constitution manager, clarification engine, spec organizer (D156-D161)
+- Proactive monitoring heartbeat daemon with 7 configurable checks (D162-D163)
+- Auto-resolver for webhook-triggered issue fix with branch/PR creation (D164-D166)
+- Selective skill injection via deterministic keyword-based category matching (D167)
+- Time-decay memory ranking with exponential formula and per-type half-lives (D168)
+- Resilience patterns: circuit breaker (3-state machine), retry with exponential backoff, correlation IDs (D146-D149)
+- Database migration runner with checksum validation and multi-tenant support (D150-D151)
+- Database backup and restore with optional AES-256-CBC encryption (D152)
+- OpenAPI 3.0.3 spec with Swagger UI for the API gateway (D153)
+- Prometheus metrics endpoint with 8 metrics (D154)
+- Cross-platform compatibility module for Windows, macOS, Linux (D145)
+- CUI markings added to all Python files
+
+### Changed
+- Dashboard login page updated for API key authentication flow
+- Settings page expanded with LLM key management section
+- Team management page updated with role-based controls
+
+## [Phase 23-28] - 2026-01-XX
+
+### Added
+- Universal Compliance Platform with 10 data categories and composable markings (D109)
+- Dual-hub crosswalk model: NIST 800-53 (US) + ISO 27001 (international) with bidirectional bridge (D111)
+- 6 Wave 1 compliance frameworks: CJIS, HIPAA, HITRUST CSF v11, SOC 2 Type II, PCI DSS v4.0, ISO/IEC 27001:2022 (D116)
+- Compliance auto-detection from data types with ISSO confirmation gate (D110)
+- Multi-regime assessment with crosswalk deduplication (D113)
+- BaseAssessor ABC pattern reducing per-framework code to approximately 60 LOC (D116)
+- DevSecOps profile management with 10 stages and 5 maturity levels (D119)
+- Pipeline security generation with Kyverno and OPA policy-as-code (D121)
+- Image signing and attestation management
+- Zero Trust Architecture: 7-pillar maturity scoring aligned to DoD ZTA Strategy (D120)
+- NIST SP 800-207 compliance assessment and gate (D118)
+- Service mesh generation for Istio and Linkerd (D121)
+- Network segmentation with namespace isolation and microsegmentation
+- PDP/PEP configuration for DISA ICAM, Zscaler, Palo Alto (D124)
+- ZTA posture score as cATO evidence dimension (D123)
+- DoD MOSA compliance framework (10 U.S.C. section 4401) via BaseAssessor pattern (D127)
+- Modularity analysis: coupling, cohesion, circular dependency detection (D129)
+- ICD and TSP document generation with CUI markings (D128)
+- MOSA code enforcement via static analysis (D129)
+- MOSA auto-trigger for DoD/IC customers during intake (D125)
+- CLI capabilities with 4 independent optional toggles and tenant ceiling (D132)
+- Remote Command Gateway with 5 channel adapters: Telegram, Slack, Teams, Mattermost, internal chat (D133)
+- 8-gate security chain for remote commands (D136)
+- IL-aware response filtering (D135)
+- User binding ceremony for remote command authorization (D136)
+- Air-gapped mode auto-disabling internet-dependent channels (D139)
+- Command allowlist with per-channel overrides (D137)
+- Auto-scaling: HPA manifests for all 15 agents + dashboard + API gateway (D141)
+- Pod Disruption Budgets with tier-based policies (D143)
+- Cross-AZ topology spread constraints (D144)
+- Cloud-agnostic node autoscaler reference (D142)
+
+## [Phase 19-22] - 2026-01-XX
+
+### Added
+- Agentic application generation producing mini-ICDEV™ clone child applications (D44-D53)
+- 6-dimension fitness scoring for agentic suitability assessment (D46)
+- Blueprint-driven generation with 12-step pipeline (D47)
+- Grandchild prevention mechanism (D52)
+- CSP MCP integration registry for AWS, GCP, Azure, Oracle
+- FIPS 199 security categorization with SP 800-60 information types and high watermark (D54)
+- FIPS 200 validation across all 17 minimum security areas (D55)
+- CNSSI 1253 overlay auto-application for IL6/SECRET (D57)
+- Dynamic SSP baseline selection from categorization (D56)
+- SaaS multi-tenancy platform with API gateway (D58-D65)
+- Per-tenant database isolation with strongest isolation model (D60)
+- 3 authentication methods: API key, OAuth 2.0/OIDC, CAC/PIV
+- 3 subscription tiers: Starter, Professional, Enterprise
+- REST API and MCP Streamable HTTP transport (D62)
+- Per-tenant K8s namespace provisioning (D63)
+- Offline license keys with RSA-SHA256 signatures for on-prem (D64)
+- Helm chart for on-prem deployment (D65)
+- Federated FORGE marketplace with 3-tier catalog (D74-D81)
+- 7-gate automated security scanning for marketplace assets (D76)
+- IL-aware compatibility checking with high-watermark consumption rule (D77)
+- Community ratings and reviews for marketplace assets
+- Marketplace SBOM generation for executable assets (D81)
+- LLM provider abstraction with vendor-agnostic routing (D66-D73)
+- Function-level LLM routing for best-of-breed model selection (D68)
+- Ollama support for air-gapped environments (D69)
+- Vision LLM support for diagram extraction and UI analysis (D82-D87)
+
+## [Phase 13-18] - 2025-XX-XX
+
+### Added
+- ATO acceleration: FedRAMP Moderate/High, CMMC Level 2/3, OSCAL generation (Phase 17)
+- eMASS bidirectional sync with hybrid mode
+- cATO continuous monitoring with evidence freshness tracking
+- PI compliance velocity tracking
+- Control crosswalk engine with dual-hub model
+- Classification manager for IL2 through IL6
+- MBSE integration: SysML XMI import, DOORS NG ReqIF import (Phase 18)
+- Digital thread with auto-linking and coverage reporting
+- Model-code generation from SysML block definitions
+- Model-code drift detection and sync engine
+- DoDI 5000.87 Digital Engineering Strategy compliance assessment
+- Diagram extraction from SysML screenshots via vision LLM
+- Application modernization: 7Rs assessment framework
+- Version migration (Python 2.7 to 3.11, Java 8 to 17, etc.)
+- Framework migration (Struts to Spring Boot, etc.)
+- Monolith decomposition with microservice extraction
+- Database migration DDL planning
+- Strangler fig pattern management
+- ATO compliance bridge for migration tracking
+
+## [Phase 7-12] - 2025-XX-XX
+
+### Added
+- RICOAS Requirements Intake: conversational AI-driven intake with 5-stage pipeline
+- Gap detection across 5 dimensions (completeness, clarity, feasibility, compliance, testability)
+- SAFe decomposition: Epic, Capability, Feature, Story, Enabler with WSJF scoring
+- Document extraction from SOW/CDD/CONOPS (shall/must/should statements)
+- ATO boundary impact assessment with 4-tier classification (GREEN/YELLOW/ORANGE/RED)
+- Supply chain intelligence: dependency graph, ISA lifecycle, SCRM assessment, CVE triage
+- Digital Program Twin simulation: 6-dimension what-if analysis
+- Monte Carlo estimation for schedule and cost
+- COA generation (Speed/Balanced/Comprehensive) with comparison and selection
+- External integration: bidirectional Jira, ServiceNow, GitLab sync
+- DOORS NG ReqIF export
+- Approval workflow management
+- RTM traceability builder
+- CI/CD integration: GitHub webhooks, GitLab webhooks, issue polling
+- Observability: hook-based agent monitoring, HMAC-signed events, SIEM forwarding
+- NLQ compliance queries via Bedrock with read-only SQL enforcement
+- Parallel CI/CD via git worktree task isolation
+
+## [Phase 1-6] - 2025-XX-XX
+
+### Added
+- Initial ICDEV™ platform with FORGE 6-layer agentic framework
+- ANVIL and M-ANVIL build workflows (Architect, Navigate, Verify, Integrate, Launch)
+- 15 multi-agent architecture across 3 tiers (Core, Domain, Support)
+- A2A protocol (JSON-RPC 2.0 over mutual TLS) for inter-agent communication
+- 14 MCP servers for Claude Code integration (stdio transport)
+- Memory system: dual storage (markdown + SQLite), hybrid search (BM25 + semantic)
+- Project management: create, list, status tracking
+- TDD workflow: RED, GREEN, REFACTOR cycle with 6 language support
+- Builder tools: scaffolding, code generation, linting, formatting
+- NIST 800-53 Rev 5 compliance: SSP, POAM, STIG checklist, SBOM generation
+- CUI marking system for IL4/IL5/IL6 artifacts
+- DoD CSSP (DI 8530.01) compliance assessment
+- CISA Secure by Design assessment
+- IEEE 1012 IV&V assessment
+- Security scanning: SAST (Bandit), dependency audit, secret detection, container scanning
+- Infrastructure generation: Terraform, Ansible, K8s manifests, CI/CD pipelines
+- Knowledge base with self-healing pattern detection
+- Monitoring: log analysis, metrics, alerts, health checks
+- Web dashboard with Flask (project status, compliance, security, agent management)
+- STIG-hardened Docker containers for all agents
+- Kubernetes manifests with network policies (default deny)
+- Audit trail: append-only, immutable, NIST AU compliant
+
+# [TEMPLATE: CUI // SP-CTI]

icdev-1.2.20/CLAUDE.md

@@ -0,0 +1,342 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+---
+
+## Quick Reference
+
+### Essential Commands
+```bash
+# Initialize framework (first run)
+/initialize
+
+# Session start
+python tools/memory/memory_read.py --format markdown
+python tools/project/session_context_builder.py --format markdown
+
+# Memory
+python tools/memory/memory_write.py --content "text" --type event
+python tools/memory/hybrid_search.py --query "query"
+
+# LLM Provider
+python -c "from tools.llm.router import LLMRouter; r = LLMRouter(); print(r.get_provider_for_function('code_generation'))"
+# Config: args/llm_config.yaml — providers, models, routing, embeddings
+
+# Database
+python tools/db/init_icdev_db.py
+python tools/db/storage.py --health --json
+
+# Testing
+python tools/testing/health_check.py --json
+python tools/testing/test_orchestrator.py --project-dir /path/to/project
+python tools/testing/e2e_runner.py --run-all
+
+# Companion sync (ALWAYS after code changes)
+python tools/dx/companion.py --sync --write --json
+
+# Coherence check
+python tools/workflow/coherence_checker.py --all --fix --gate
+
+# Internal Awareness Engine (Phase 1-6, D-AWARE)
+python tools/awareness/component_indexer.py --scan --json        # Refresh kg-icdev-self-awareness nodes
+python tools/awareness/health_prober.py --run-all --json         # Probe routes, imports, coherence
+python tools/awareness/drift_detector.py --detect --json         # Detect regressions vs baseline
+python tools/awareness/gap_detector.py --detect --json           # Surface structural gaps
+python tools/awareness/suggested_card_writer.py --write --json   # Promote predictions to kanban
+python -c "from tools.genesis.reflexes.awareness import run; run({}, None)"  # Full 5-phase cycle
+# UI: http://localhost:5050/components-map (visual map) + /ask-icdev (Q&A chat)
+# Config: args/awareness_config.yaml — 3h cadence, 7 gap rules, 0.7 threshold
+```
+
+### Python Dependencies
+See `requirements.txt`. Key: sqlite3, pathlib, json (stdlib); openai, anthropic, python-dotenv (optional); pyyaml, jinja2, flask, pytest (ICDEV™).
+
+> **Full command reference:** See [docs/reference/commands.md](docs/reference/commands.md) for all CLI commands across every ICDEV™ module.
+
+---
+
+## Architecture: FORGE Framework
+
+6-layer agentic system. AI orchestrates; tools execute deterministically.
+
+| Layer | Directory | Role |
+|-------|-----------|------|
+| **Goals** | `goals/` | Process definitions — what to achieve, which tools, expected outputs |
+| **Orchestration** | *(you)* | Read goal → decide tool order → apply args → handle errors |
+| **Tools** | `tools/` | Python scripts, one job each. Deterministic. Don't think, just execute. |
+| **Args** | `args/` | YAML/JSON behavior settings. Change behavior without editing goals/tools |
+| **Context** | `context/` | Static reference material (tone rules, writing samples, case studies) |
+| **Hard Prompts** | `hardprompts/` | Reusable LLM instruction templates |
+
+**Why:** LLMs are probabilistic. Business logic must be deterministic. 90% accuracy/step = ~59% over 5 steps.
+
+### Key Files
+- `goals/manifest.md` — Index of all goal workflows. Check before starting any task.
+- `tools/manifest.md` — Thin index of all tool shards. Detail lives in `tools/manifest/<topic>.md`. Grep the shard directory (not the index) when searching for an existing tool.
+- `memory/MEMORY.md` — Curated long-term facts/preferences.
+- `.env` — API keys, LLM model names. **Admins configure LLM here, not in code.**
+- `.tmp/` — Disposable scratch work. Never store important data here.
+
+---
+
+## How to Operate
+
+1. **Check goals first** — Read `goals/manifest.md` before starting a task. If a goal exists, follow it.
+2. **Check tools first** — Before writing new code, grep `tools/manifest/` shards for existing tools. If you create a new tool, add its entry to the appropriate topic shard (e.g. `tools/manifest/memory-system.md`), not the thin index.
+3. **When tools fail** — Read the error, fix the tool, update the goal with what you learned.
+4. **Goals are living docs** — Update when better approaches emerge. Never modify/create without permission.
+5. **When stuck** — Explain what's missing. Don't guess or invent capabilities.
+
+### Session Start Protocol
+1. Read `memory/MEMORY.md` for long-term context
+2. Read today's daily log (`memory/logs/YYYY-MM-DD.md`)
+3. Read yesterday's log for continuity
+4. Or run: `python tools/memory/memory_read.py --format markdown`
+5. Load project context: `python tools/project/session_context_builder.py --format markdown`
+
+### First Run
+If `memory/MEMORY.md` doesn't exist, this is a fresh environment. Run `/initialize`.
+
+---
+
+## Running ICDEV Outside Claude Code
+
+ICDEV™ is fully operable without the Claude Code CLI. Use `tools/airgap/` as the runtime shim — it replicates hooks, session management, and safety gates as plain Python.
+
+### Quick Start
+
+```bash
+# Detect environment (cloud vs air-gap)
+python -m tools.airgap --detect --json
+
+# Activate local-only LLM routing (air-gap mode)
+python -m tools.airgap --activate
+
+# Health check before any risky operation
+python tools/testing/health_check.py --json
+```
+
+### Cron Job Setup
+
+```bash
+# /etc/cron.d/icdev-audit — nightly compliance scan
+0 2 * * * icdev-user cd /opt/icdev && \
+  python -c "
+from tools.airgap.hook_compat import get_session_id, run_auto_commit
+get_session_id()   # sets CLAUDE_SESSION_ID + ICDEV_SESSION_ID for audit trail
+# ... invoke tools here (health_check, bandit, etc.) ...
+run_auto_commit('chore: nightly audit auto-commit')
+" >> /var/log/icdev/cron.log 2>&1
+```
+
+### CI/CD Pipeline (GitLab Stage End)
+
+```yaml
+# .gitlab-ci.yml — security gate + auto-commit at stage end
+security-scan:
+  stage: validate
+  script:
+    - export ICDEV_AUTO_COMMIT=true
+    - python tools/testing/health_check.py --json
+    - python -m bandit -r tools/ --severity-level medium
+    - python -c "from tools.airgap.hook_compat import run_pre_tool_check; \
+        r = run_pre_tool_check('Bash', {'command': 'git push'}); \
+        exit(0 if r['allowed'] else 1)"
+    - python -c "from tools.airgap.hook_compat import run_auto_commit; \
+        run_auto_commit('ci: post-scan auto-commit')"
+```
+
+### Headless ANVIL Workflow
+
+All 10 core ANVIL commands are runnable headlessly via `tools/anvil/<name>.py`.
+Each wrapper parses its source (`.claude/commands/*.md` or an `icdev-*` skill),
+extracts documented `python tools/…` steps, substitutes `$ARGUMENTS`, and runs
+them with an allowlisted prefix.
+
+```bash
+python tools/anvil/status.py --json                       # skill-backed
+python tools/anvil/feature.py --dry-run -- "add foo bar"  # md-backed preview
+python tools/anvil/feature.py --json -- "add foo bar"     # full execution
+```
+
+Available wrappers (11 total): `feature`, `bug`, `chore`, `test`, `review`,
+`commit`, `status`, `monitor`, `maintain`, `secure`, `deploy`.
+
+### Skill Invocation (Headless)
+
+Every `.agents/skills/icdev-*` skill is invokable from a non-Claude shell.
+
+```bash
+python tools/skills/invoke.py --list --json              # list all skills
+python tools/skills/invoke.py --show icdev-status        # print skill card
+python tools/skills/invoke.py --dry-run icdev-secure     # preview commands
+python tools/skills/invoke.py --exec icdev-status --json # execute + capture output
+python tools/skills/invoke.py --exec icdev-secure -- --scan tools/ --json  # with args
+```
+
+Allowlisted command prefixes: `python tools/`, `python -m tools`, `python -c`. Shell builtins, curl, etc. are refused.
+
+### Air-Gap LLM Routing (Ollama-only)
+
+```bash
+# .env — forces all routing through local Ollama, no cloud fallback
+OLLAMA_BASE_URL=http://localhost:11434
+ICDEV_LLM_PROVIDER=ollama
+# Also set in args/llm_config.yaml: two_tier.enabled: false
+```
+
+```python
+# Programmatic activation
+from tools.airgap import is_airgap, activate_airgap
+if is_airgap():
+    activate_airgap()   # patches llm_config.yaml routing to local-only
+```
+
+### Validation in Air-Gap Mode
+
+```bash
+python tools/testing/health_check.py --json                            # env + DB + deps
+python tools/testing/e2e_runner.py --run-all --mode native --json      # UI lifecycle tests
+python -m bandit -r tools/ --severity-level medium                     # security scan
+python tools/workflow/coherence_checker.py --all --gate                # coherence gate
+```
+
+> **Long-form reference:** [docs/ops/airgap-runbook.md](docs/ops/airgap-runbook.md)
+
+---
+
+## Guardrails
+
+- Always grep `tools/manifest/` shards before writing a new script
+- Verify tool output format before chaining into another tool
+- Don't assume APIs support batch operations — check first
+- When a workflow fails mid-execution, preserve intermediate outputs before retrying
+- Read the full goal before starting a task — don't skim
+- **NEVER DELETE YOUTUBE VIDEOS** — Irreversible.
+- When adding an append-only/immutable DB table, ALWAYS add it to `APPEND_ONLY_TABLES` in `.claude/hooks/pre_tool_use.py`
+- When adding a new dashboard page route, ALWAYS add it to the `Pages:` line in `.claude/commands/start.md`
+- **Project roadmaps** — when starting a multi-epic initiative (anything that decomposes into ≥2 epics with chained tasks), register it in `args/projects.yaml`: define `key`, `name`, `task_prefix`, `briefs[]`, and `epics[]`. Its progress card appears on Home (`/`) below the Task Board automatically via the reusable partial `tools/dashboard/templates/_projects_in_flight.html`. Task IDs MUST use the form `<task_prefix><epic_key>-<N>` (e.g. `dt-iqe-01`). Rules enforced at render time: no two projects may have `task_prefix` values where one is a prefix of the other; within a project, no epic `key` may be a prefix of another under the `-` separator. Cards auto-hide at 100% done or 0 tasks.
+- Screenshots: ALWAYS use `playwright/screenshots/<name>.png` as the filename
+- In Jinja2 templates, NEVER use `'%%.0f'|format(value)` — use `value|round(0)|int`
+- In Behave step definitions, match step text to tool return signatures
+- SQL CHECK constraints: derive from Python constants, never hardcode
+- Entity types: add to BOTH the Python constant AND the SQL CHECK constraint
+- Child apps: ALWAYS use `child_app_generator.py` + `forge_validator.py --gate`
+- Before writing tests: ALWAYS run `api_surface_extractor.py --file <module> --json`
+- **Cross-platform:** pathlib.Path, `encoding='utf-8'`, `tempfile.gettempdir()`, `datetime.now(timezone.utc)`, `hashlib.sha256` not md5
+- **LLM config via `.env`**, never hardcode model IDs in Python
+- **New tool/module registration checklist (8 points):**
+  1. `tools/manifest/<topic>.md` — add tool entry to the appropriate shard (index at `tools/manifest.md`)
+  2. `CLAUDE.md` — add CLI commands to [docs/reference/commands.md](docs/reference/commands.md)
+  3. `args/security_gates.yaml` — add gate if blocking/warning conditions
+  4. `tools/mcp/tool_registry.py` + `gap_handlers.py` — register in MCP gateway
+  5. `.claude/hooks/pre_tool_use.py` — add append-only tables
+  6. `tests/conftest.py` — add new table schemas to MINIMAL_ICDEV_SCHEMA
+  7. `python tools/dx/companion.py --sync --write --json` — sync to all AI platforms
+  8. `python tools/workflow/coherence_checker.py --all --fix --gate` — coherence validation
+
+---
+
+## ICDEV™ System — Intelligent Certified Development
+
+Meta-builder that autonomously builds Gov/DoD applications using FORGE + ANVIL workflow. Full SDLC with TDD/BDD, NIST 800-53 RMF compliance, and self-healing.
+
+### Environment
+- **Classification:** CUI // SP-CTI (IL4/IL5), SECRET (IL6)
+- **Impact Levels:** IL2 (Public), IL4 (CUI/GovCloud), IL5 (CUI/Dedicated), IL6 (SECRET/SIPR)
+- **Cloud:** Multi-cloud — AWS GovCloud, Azure Government, GCP, OCI, IBM, Local
+- **LLM:** Multi-cloud — Bedrock, Azure OpenAI, Vertex AI, OCI GenAI, watsonx.ai, Ollama
+- **Languages:** Python, Java, JavaScript/TS, Go, Rust, C# (6 first-class)
+- **CI/CD:** GitLab | **Orchestration:** K8s/OpenShift | **IaC:** Terraform + Ansible
+
+### Multi-Agent Architecture
+15 agents across 3 tiers (Core, Domain, Support) on ports 8443-8458. See [docs/reference/architecture.md](docs/reference/architecture.md).
+
+### Memory System
+Dual storage: markdown (human-readable) + DB (searchable, SQLite or PostgreSQL).
+- Tables in main `data/icdev.db` (or PostgreSQL): `memory_entries`, `daily_logs`, `memory_access_log`, `memory_consolidation_log`, `memory_buffer`
+- Activity tracking: `tasks`, `activity_tasks` tables (also in main DB)
+- Types: fact, preference, event, insight, task, relationship
+- Search: hybrid_search.py (0.7 BM25 + 0.3 semantic)
+- All tools use `get_connection()` — supports both SQLite and PostgreSQL backends
+
+### Self-Healing
+- **≥ 0.7** confidence → auto-remediate (max 5/hour)
+- **0.3–0.7** → suggest fix, require approval
+- **< 0.3** → escalate with full context
+
+### Databases
+| Database | Purpose |
+|----------|---------|
+| `data/icdev.db` | Main operational DB (391 tables, incl. memory + activity) |
+| `data/platform.db` | SaaS platform DB |
+| `data/tenants/{slug}.db` | Per-tenant isolated DB |
+
+Audit trail is **append-only/immutable** (NIST AU). Full schema: [docs/reference/databases.md](docs/reference/databases.md).
+
+---
+
+## ICDEV™ Guardrails
+
+- All artifacts MUST include classification markings (CUI for IL4/IL5, SECRET for IL6)
+- Use `classification_manager.py` for markings — don't hard-code CUI banners
+- Audit trail is append-only — NEVER UPDATE/DELETE audit tables
+- Security gates block on: CAT1 STIG, critical/high vulns, failed tests, missing markings
+- When implementing NIST 800-53 control, call crosswalk engine for FedRAMP/CMMC auto-populate
+- Self-healing limited to confidence ≥ 0.7 and max 5/hour
+- All A2A uses mutual TLS; never store secrets in code
+- SBOM regenerated on every build; containers non-root, read-only rootfs
+- IL6/SECRET: SIPR-only, NSA Type 1 encryption, air-gapped CI/CD
+- **V&V before handoff** — if change affects UI, verify with Playwright MCP before reporting
+- **Playwright E2E after dashboard changes** — mandatory post-implementation verification
+- **Feature docs** — create `docs/features/phase-{N}-{slug}.md` after each phase
+- **Sandbox coverage (OPT-58)** — any new `tools/` module that ingests user-provided content MUST land a decision in [docs/security/sandbox-coverage.md](docs/security/sandbox-coverage.md) (sandboxed / trusted-first-party / sandboxed-on-demand / bypass-documented). Canvas templates are first-party; canvas design JSON is data only. `.tmp/*.py` scripts are dev-scratch only — productize under `tools/` before merge. Enforced by `coherence_checker.py:check_sandbox_coverage`.
+
+---
+
+## Security Gates (Summary)
+
+Gates block on critical conditions. Full definitions: [docs/reference/compliance-security.md](docs/reference/compliance-security.md).
+
+Key gates: Code Review, Merge, Deploy, FedRAMP, CMMC, cATO, DES, Migration, RICOAS, Supply Chain, FIPS 199/200, Marketplace, Multi-Regime, DevSecOps, ZTA, MOSA, AI Security, RAG, Fine-Tuning, Coherence, Acceptance Validation.
+
+---
+
+## Karpathy Principles — Pre-Design Engineering Gate
+
+Before writing code, apply these 5 heuristics from `hardprompts/karpathy_principles.md`:
+
+1. **State assumptions** — Name the constraints, inputs, invariants you're relying on. Unstated assumptions are where bugs hide.
+2. **Enumerate interpretations** — For any ambiguous requirement, list the 2–4 ways it could be read before picking one. Surface them to the user if the choice is load-bearing.
+3. **Prefer simpler** — Three similar lines beats one clever abstraction. Don't design for hypothetical future requirements. YAGNI.
+4. **Bound your edit scope** — Only touch what the task requires. No drive-by refactors, no surrounding cleanup, no speculative error handling.
+5. **Success criteria** — State how you'll know the change is done before writing it. If you can't write the test / acceptance check, the spec is incomplete.
+
+Applies to: build, bug fix, refactor, TDD, and code review workflows. Enforced across all 10 AI platform configs by `tools/workflow/coherence_checker.py::check_karpathy_sync`.
+
+---
+
+## Reference Documentation
+
+Detailed reference material (read on-demand, not loaded automatically):
+
+| File | Contents |
+|------|----------|
+| [commands.md](docs/reference/commands.md) | All CLI commands for every ICDEV™ module |
+| [architecture.md](docs/reference/architecture.md) | Agents, MCP servers, languages, skills, deployment, scaling, installation |
+| [adrs.md](docs/reference/adrs.md) | All architecture decision records (D1–D360+) |
+| [compliance-security.md](docs/reference/compliance-security.md) | Compliance frameworks, crosswalk, security gates, args config |
+| [subsystems.md](docs/reference/subsystems.md) | Innovation, Creative, Research engines; RICOAS; SaaS; Marketplace; CI/CD |
+| [goals.md](docs/reference/goals.md) | All existing goal workflows with descriptions |
+| [testing.md](docs/reference/testing.md) | Testing framework, test commands, E2E specs |
+| [databases.md](docs/reference/databases.md) | Database tables, schemas, migration commands |
+| [ops/airgap-runbook.md](docs/ops/airgap-runbook.md) | Running ICDEV™ outside Claude Code — cron, CI/CD, air-gap LLM, headless ANVIL |
+
+---
+
+## Continuous Improvement
+
+Every failure strengthens the system: identify what broke → fix the tool → test it → update the goal → next run succeeds automatically.
+
+Be direct. Be reliable. Get shit done.