# .goosehints — ICDEV™ Project
# CUI // SP-CTI

## Project Overview

ICDEV™ Project is an ICDEV™-managed webapp (python).
Classification: CUI // SP-CTI (IL4)

## FORGE Framework (6 Layers)

1. **Goals** (`goals/`) — Workflow definitions (check `goals/manifest.md` first)
2. **Orchestration** (you) — Read goal, decide tool order, apply args, handle errors
3. **Tools** (`tools/`) — Deterministic Python scripts, one job each (all support `--json`)
4. **Args** (`args/`) — YAML/JSON behavior config (change behavior without editing code)
5. **Context** (`context/`) — Static reference material
6. **Hard Prompts** (`hardprompts/`) — Reusable LLM instruction templates

## How to Operate

- Check `goals/manifest.md` before starting any task
- Check `tools/manifest.md` before writing new code
- All tools support `--json` and `--gate` flags
- When tools fail: read error, fix tool, update goal
- Run `python tools/dx/companion.py --sync --write --json` after code changes

## LLM Router

Use the `llm_invoke` MCP tool (ICDEV™ LLM Router extension) for all LLM calls.
Three tiers: Planner (Claude), Worker (qwen3.5 draft + Claude review), Scanner (Ollama only).
Use `llm_resolve` to check which model handles a function before invoking.

## Classification Markings

Every generated file must include `# CUI // SP-CTI` as the first comment line. This is a compliance requirement for IL4 projects.


## Testing

- **Syntax:** `python -m py_compile <file>`
- **Lint:** `ruff check <file>`
- **Unit tests:** pytest (`pytest tests/ -q`)
- **BDD tests:** behave (`behave features/`)
- **Security:** `python -m bandit -r <file> --severity-level medium`
- **Tool verify:** Run each tool with `--json` and `--gate`

## Key Directories

| Dir | Purpose |
|-----|---------|
| `tools/` | 251+ Python tools (deterministic, one job each) |
| `goals/` | Workflow definitions |
| `args/` | YAML config (llm_config.yaml, security_gates.yaml) |
| `data/` | SQLite databases (icdev.db, memory.db, activity.db) |
| `hardprompts/` | Reusable LLM instruction templates |
| `context/` | Static reference material |

## Guardrails

- Never delete audit tables (append-only, NIST AU)
- Always include CUI classification markings
- Use `pathlib.Path`, `encoding='utf-8'`, `datetime.now(timezone.utc)`
- LLM config via `.env`, never hardcode model IDs
- Cross-platform: forward slashes, `tempfile.gettempdir()`, `hashlib.sha256`
- Security gates block on: CAT1 STIG, critical vulns, failed tests, missing markings

## Available CLI Tools

```bash
python tools/project/session_context_builder.py --format markdown  # Load context
python tools/testing/health_check.py --json                        # Health check
python tools/testing/test_orchestrator.py --project-dir . --json   # Run tests
python tools/compliance/ssp_generator.py --project-id "" --json
python tools/security/sast_runner.py --project-dir . --json        # SAST scan
python tools/dx/companion.py --sync --write --json                 # Companion sync
python tools/workflow/coherence_checker.py --all --fix --gate      # Coherence
```

---

*Generated by ICDEV™ Companion*

## 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.
