Overview

licit is a standalone CLI tool that analyzes AI-assisted development projects to evaluate their regulatory compliance. It operates locally (filesystem-first), without requiring external services or databases.

licit (CLI)
├── config/          Pydantic v2 schema + YAML loader
├── core/            Domain models + detection + evidence
├── logging/         structlog configuration
├── provenance/      Code traceability (Phase 2 — COMPLETED)
├── changelog/       Agent config change tracking (Phase 3 — COMPLETED)
├── frameworks/      Regulatory evaluators (Phases 4-5 COMPLETED)
│   ├── base.py          Protocol ComplianceFramework
│   ├── registry.py      Framework registry
│   ├── eu_ai_act/   EU AI Act (Phase 4 — COMPLETED)
│   └── owasp_agentic/  OWASP Agentic Top 10 (Phase 5 — COMPLETED)
├── connectors/      Optional integrations (Phase 7)
└── reports/         Report generation (Phase 6)

Technology Stack

ComponentTechnologyJustification
CLIClick 8.1+Command composition, types, automatic help
Config validationPydantic v2Strict validation, YAML/JSON serialization
Domain modelsdataclassesLightweight, no dependencies, native typing
EnumsStrEnum (Python 3.12)Direct string serialization, ruff UP042 compatible
LoggingstructlogStructured logging, composable processors
ConfigPyYAMLDe facto standard for YAML config
TemplatesJinja2Markdown/HTML report generation
CryptocryptographyHMAC-SHA256 for provenance signing

Design Principles

  1. Filesystem-first: All data is stored in .licit/ within the project. No databases, APIs, or remote services.

  2. Dataclasses for domain, Pydantic for config: Domain models (ProvenanceRecord, ControlResult, etc.) are pure dataclasses. Only configuration (LicitConfig) uses Pydantic v2.

  3. Protocol for interfaces: Abstractions between modules use typing.Protocol, not inheritance with abstract classes.

  4. Lazy imports: Commands for future phases use lazy imports with try/except ImportError so the CLI works without the modules that are not yet implemented.

  5. Automatic detection: ProjectDetector infers languages, frameworks, CI/CD, security tools, and AI agent configurations without requiring manual configuration.

Data Flow

User's project
       │
       ├──────────────────────────────────────┬─────────────────────┐
       ▼                                      ▼                     ▼
┌─────────────────┐                  ┌──────────────────┐  ┌───────────────────┐
│ ProjectDetector  │                  │ProvenanceTracker  │  │  ConfigWatcher     │
│                  │                  │                    │  │                    │
│ Detects languages│                  │ ┌──────────────┐  │  │ git log --follow   │
│ frameworks, CI/CD│                  │ │ GitAnalyzer   │  │  │ → ConfigSnapshot[] │
│ agents           │                  │ │  + Heuristics │  │  └────────┬──────────┘
└────────┬────────┘                  │ └──────┬───────┘  │           │
         │ ProjectContext             │        │          │  ┌────────▼──────────┐
         ▼                           │ ┌──────────────┐  │  │  Semantic Differ   │
┌─────────────────┐                  │ │SessionReaders │  │  │  (YAML/JSON/MD)    │
│EvidenceCollector │                  │ └──────┬───────┘  │  └────────┬──────────┘
│                  │                  │        │          │           │ FieldDiff[]
│ .licit/, configs │                  │ ┌──────────────┐  │  ┌────────▼──────────┐
│ SARIF, architect │                  │ │  Attestor    │  │  │ ChangeClassifier   │
└────────┬────────┘                  │ └──────┬───────┘  │  │ (MAJOR/MINOR/PATCH)│
         │ EvidenceBundle             │        │          │  └────────┬──────────┘
         ▼                           │ ┌──────────────┐  │           │ ConfigChange[]
┌─────────────────┐                  │ │    Store     │  │  ┌────────▼──────────┐
│   Evaluators    │ ← Phases 4-5    │ └──────────────┘  │  │ ChangelogRenderer  │
└────────┬────────┘                  └──────────┬───────┘  │ (Markdown / JSON)  │
         │ ControlResult[]                      │          └────────┬──────────┘
         ▼                                      ▼                   ▼
┌─────────────────┐                  ┌──────────────────┐  ┌───────────────────┐
│   Reports       │ ← Phase 6       │ Provenance Report │  │ changelog.md/json  │
└─────────────────┘                  └──────────────────┘  └───────────────────┘

Implemented Modules (Phases 1-5)

config/ — Configuration

core/ — Core

logging/ — Logging

provenance/ — Code Traceability

changelog/ — Agent Config Changelog

frameworks/ — Compliance Evaluators

cli.py — Command Line Interface

10 commands registered with Click. Eight functional: init, status, connect, trace, changelog, fria, annex-iv, verify. The remaining (report, gaps) have full signatures and help text but depend on modules from future phases. verify evaluates both EU AI Act and OWASP Agentic Top 10.

Implementation Phases

PhaseModuleStatusDescription
1FoundationCOMPLETEDConfig, models, detection, evidence, CLI, logging
2ProvenanceCOMPLETEDgit_analyzer, heuristics, JSONL store, HMAC, attestation, session readers, report
3ChangelogCOMPLETEDwatcher, semantic differ, classifier (MAJOR/MINOR/PATCH), renderer (MD/JSON)
4EU AI ActCOMPLETEDProtocol, registry, evaluator (11 articles), interactive FRIA, Annex IV, Jinja2 templates
5OWASPCOMPLETEDOWASP Agentic Top 10 evaluator (10 controls), risk-based scoring, Jinja2 template
6ReportsPendingUnified report, gap analyzer, Markdown/JSON/HTML
7ConnectorsPendingIntegration with architect and vigil

Dependency Graph

Phase 1: config ← core/models
         core/project (independent)
         core/evidence ← config + core/models + (provenance.store optional)
         cli ← config + core/* + logging

Phase 2: provenance ← core/models + config (COMPLETED)
         provenance/heuristics (independent)
         provenance/git_analyzer ← heuristics + core/models
         provenance/store ← core/models
         provenance/attestation (independent)
         provenance/session_readers ← core/models
         provenance/tracker ← git_analyzer + session_readers + attestation + store + config
         provenance/report ← core/models
Phase 3: changelog ← core/models + config (COMPLETED)
         changelog/watcher ← subprocess (git)
         changelog/differ ← yaml + json (independent)
         changelog/classifier ← differ + core/models
         changelog/renderer ← core/models
Phase 4: frameworks/eu_ai_act ← core/* + evidence (COMPLETED)
         frameworks/base.py (independent — Protocol)
         frameworks/registry.py ← base.py
         eu_ai_act/requirements.py ← core/models
         eu_ai_act/evaluator.py ← requirements + core/* + evidence
         eu_ai_act/fria.py ← core/project + core/evidence + jinja2
         eu_ai_act/annex_iv.py ← core/project + core/evidence + jinja2
Phase 5: frameworks/owasp ← core/* + evidence + frameworks/base (COMPLETED)
         owasp_agentic/requirements.py ← core/models
         owasp_agentic/evaluator.py ← requirements + core/* + evidence
Phase 6: reports ← frameworks/* + evidence + core/models
Phase 7: connectors ← config (independent)

Project Directory Structure

licit-cli/
├── pyproject.toml              # Metadata, deps, tools
├── LICENSE                     # MIT
├── README.md                   # README in English
├── CHANGELOG.md                # Changelog in English
├── SECURITY.md                 # Security policy
├── SEGUIMIENTO-V0.md           # Implementation tracking (Spanish)
├── docs/                       # This documentation
├── src/
│   └── licit/
│       ├── __init__.py         # __version__
│       ├── __main__.py         # python -m licit
│       ├── py.typed            # PEP 561
│       ├── cli.py              # Click CLI
│       ├── config/
│       │   ├── schema.py       # Pydantic models
│       │   ├── loader.py       # YAML load/save
│       │   └── defaults.py     # Constants
│       ├── core/
│       │   ├── models.py       # Dataclasses + enums
│       │   ├── project.py      # ProjectDetector
│       │   └── evidence.py     # EvidenceCollector
│       ├── logging/
│       │   └── setup.py        # structlog config
│       ├── provenance/         # Phase 2 (COMPLETED)
│       │   ├── heuristics.py   # 6 AI detection heuristics
│       │   ├── git_analyzer.py # Git history analysis
│       │   ├── store.py        # Append-only JSONL store
│       │   ├── attestation.py  # HMAC-SHA256 + Merkle tree
│       │   ├── tracker.py      # Orchestrator
│       │   ├── report.py       # Markdown report generator
│       │   └── session_readers/
│       │       ├── base.py     # Protocol SessionReader
│       │       └── claude_code.py  # Claude Code JSONL reader
│       ├── changelog/          # Phase 3 (COMPLETED)
│       │   ├── watcher.py      # Git monitoring of agent configs
│       │   ├── differ.py       # Semantic diffing (YAML/JSON/MD/text)
│       │   ├── classifier.py   # MAJOR/MINOR/PATCH classification
│       │   └── renderer.py     # Markdown + JSON rendering
│       ├── frameworks/         # Phases 4-5 (COMPLETED)
│       │   ├── base.py        # Protocol ComplianceFramework
│       │   ├── registry.py    # FrameworkRegistry
│       │   ├── eu_ai_act/     # EU AI Act (Phase 4)
│       │   │   ├── requirements.py  # 11 evaluable requirements
│       │   │   ├── evaluator.py     # Per-article evaluator
│       │   │   ├── fria.py          # Interactive FRIA generator
│       │   │   ├── annex_iv.py      # Annex IV generator
│       │   │   └── templates/       # Jinja2 (FRIA, Annex IV, report section)
│       │   └── owasp_agentic/ # OWASP Agentic Top 10 (Phase 5)
│       │       ├── requirements.py  # 10 risks as ControlRequirements
│       │       ├── evaluator.py     # Per-security-risk evaluator
│       │       └── templates/       # Jinja2 (report section)
│       ├── connectors/         # (Phase 7)
│       └── reports/            # (Phase 6)
└── tests/
    ├── conftest.py             # Shared fixtures
    ├── test_cli.py             # CLI tests (13)
    ├── test_qa_edge_cases.py   # QA Phase 1 tests (61)
    ├── test_config/
    │   ├── test_schema.py      # Schema tests (7)
    │   └── test_loader.py      # Loader tests (9)
    ├── test_core/
    │   ├── test_project.py     # Detection tests (12)
    │   └── test_evidence.py    # Evidence tests (11)
    ├── test_provenance/
    │   ├── test_heuristics.py      # Heuristics tests (23)
    │   ├── test_git_analyzer.py    # Git analyzer tests (15)
    │   ├── test_store.py           # JSONL store tests (15)
    │   ├── test_attestation.py     # Attestation tests (13)
    │   ├── test_tracker.py         # Tracker tests (7)
    │   ├── test_session_reader.py  # Session reader tests (13)
    │   ├── test_qa_edge_cases.py   # QA Phase 2 tests (81)
    │   └── fixtures/               # Test data
    ├── test_changelog/
    │   ├── test_watcher.py         # Watcher tests (12)
    │   ├── test_differ.py          # Differ tests (19)
    │   ├── test_classifier.py      # Classifier tests (22)
    │   ├── test_renderer.py        # Renderer tests (10)
    │   ├── test_integration.py     # Integration tests (3)
    │   ├── test_qa_edge_cases.py   # QA Phase 3 tests (27)
    │   └── fixtures/               # Test data
    └── test_frameworks/
        ├── test_eu_ai_act/
        │   ├── test_evaluator.py       # Evaluator tests (32)
        │   ├── test_fria.py            # FRIA tests (23)
        │   ├── test_annex_iv.py        # Annex IV tests (17)
        │   ├── test_requirements.py    # Requirements tests (9)
        │   └── test_qa_edge_cases.py   # QA Phase 4 tests (43)
        └── test_owasp/
            ├── test_evaluator.py       # OWASP evaluator tests (40)
            ├── test_requirements.py    # OWASP requirements tests (15)
            └── test_qa_edge_cases.py   # QA Phase 5 tests (48)