serenecode 0.1.0__py3-none-any.whl

serenecode/templates/content.py

@@ -0,0 +1,337 @@
+"""Embedded template content for SERENECODE.md files.
+
+This module stores template content as string constants so that
+the init module can generate SERENECODE.md without file I/O.
+"""
+
+from __future__ import annotations
+
+import icontract
+
+from serenecode.contracts.predicates import is_valid_template_name
+
+_DEFAULT_TEMPLATE = """\
+# SERENECODE.md — Project Conventions
+
+This file governs how all code in this project must be written. Any AI coding \
+agent MUST read this file in its entirety before writing or modifying any code.
+
+Verified with: `serenecode check src/ --level 4 --allow-code-execution`
+
+Levels 3-6 import and execute project modules. Only use \
+`--allow-code-execution` for trusted code.
+
+---
+
+## Complete Example
+
+This shows every pattern the checker enforces. Follow this exactly:
+
+```python
+\"\"\"Module docstring describing purpose and architecture role.\"\"\"
+
+import icontract
+from dataclasses import dataclass
+
+
+@icontract.invariant(lambda self: self.balance >= 0, "balance must be non-negative")
+@dataclass(frozen=True)
+class Account:
+    \"\"\"An immutable account record.\"\"\"
+
+    name: str
+    balance: float
+
+
+@icontract.require(lambda items: len(items) > 0, "items must not be empty")
+@icontract.ensure(lambda items, result: min(items) <= result <= max(items), "result within range")
+def compute_mean(items: list[float]) -> float:
+    \"\"\"Compute the arithmetic mean.\"\"\"
+    return sum(items) / len(items)
+```
+
+---
+
+## Contract Standards
+
+### Public Functions
+
+Every public function MUST have `@icontract.require` (preconditions) and \
+`@icontract.ensure` (postconditions) using icontract decorators.
+
+- Every contract decorator MUST include a human-readable description string \
+as the second argument: `@icontract.require(lambda x: x > 0, "x must be positive")`
+- Functions with no meaningful parameters may omit `@icontract.require`.
+- Contracts must be pure boolean expressions — no side effects.
+
+### Private/Helper Functions
+
+Private functions (prefixed with `_`) SHOULD have contracts when the function \
+contains non-trivial logic.
+
+### Class Invariants
+
+Every class MUST have at least one `@icontract.invariant` defining its \
+representation invariant. Invariants must constrain actual state — \
+tautological invariants like `lambda self: True` provide no verification \
+value and should not be used. If a class is truly stateless (e.g. a \
+Protocol or a stateless adapter), omit the invariant and document why.
+
+---
+
+## Type Annotation Standards
+
+- All function signatures MUST have complete type annotations on every \
+parameter kind (including positional-only, keyword-only, variadic, and private \
+helper parameters) and the return type.
+- No use of `Any` in core modules. Use `Protocol`, `Union`, or generics.
+- Generic types must be fully parameterized (`list[str]` not `list`).
+- Use modern type syntax (Python 3.10+): `X | None` not `Optional[X]`.
+
+---
+
+## Documentation Standards
+
+- Every module MUST have a module-level docstring.
+- Every public function and class MUST have a docstring.
+
+---
+
+## Architecture Standards
+
+### Hexagonal Architecture
+
+```
+src/yourproject/
+├── core/        # Pure logic. No I/O. No os/pathlib/subprocess imports.
+├── ports/       # Protocol interfaces only.
+├── adapters/    # I/O implementations.
+└── cli.py       # Thin entry point.
+```
+
+Core modules (`core/`, models, contracts) MUST NOT import I/O libraries \
+(`os`, `pathlib`, `subprocess`, `requests`, `socket`, `shutil`, `tempfile`, `glob`). \
+Inject dependencies through function parameters.
+
+---
+
+## Naming Conventions
+
+- Modules: `snake_case.py`. Classes: `PascalCase`. Functions: `snake_case`.
+
+---
+
+## Exemptions
+
+The following are exempt from full contract requirements:
+- `cli.py`, `__init__.py` — Composition roots.
+- `adapters/` — I/O boundary code.
+- `ports/` — Protocol definitions.
+- `templates/`, `tests/fixtures/`, `exceptions.py`
+
+These MUST still have type annotations.
+"""
+
+_STRICT_TEMPLATE = """\
+# SERENECODE.md — Strict Project Conventions
+
+This file governs how all code in this project must be written. Any AI coding \
+agent MUST read this file in its entirety before writing or modifying any code. \
+**No exemptions.** Every function — public and private — must have contracts.
+
+Verified with: `serenecode check src/ --level 6 --allow-code-execution`
+
+Levels 3-6 import and execute project modules. Only use \
+`--allow-code-execution` for trusted code.
+
+---
+
+## Complete Example
+
+This shows every pattern the checker enforces. Follow this exactly:
+
+```python
+\"\"\"Module docstring describing purpose and architecture role.
+
+This is a core module — no I/O operations are permitted.
+\"\"\"
+
+import icontract
+from dataclasses import dataclass
+
+
+@icontract.invariant(lambda self: self.balance >= 0, "balance must be non-negative")
+@dataclass(frozen=True)
+class Account:
+    \"\"\"An immutable account record.\"\"\"
+
+    name: str
+    balance: float
+
+
+@icontract.require(lambda items: len(items) > 0, "items must not be empty")
+@icontract.ensure(lambda items, result: min(items) <= result <= max(items), "result within range")
+def compute_mean(items: list[float]) -> float:
+    \"\"\"Compute the arithmetic mean.\"\"\"
+    total = 0.0
+    # Loop invariant: total is the sum of items[0..i]
+    for item in items:
+        total += item
+    return total / len(items)
+
+
+def _validate_positive(value: float) -> bool:
+    \"\"\"Check that a value is positive.\"\"\"
+    return value > 0
+```
+
+---
+
+## Contract Standards
+
+### Public Functions
+
+Every public function MUST have `@icontract.require` and `@icontract.ensure` \
+with description strings: `@icontract.require(lambda x: x > 0, "x must be positive")`
+
+Functions with no meaningful parameters may omit `@icontract.require`.
+
+### Private Functions
+
+Private functions (prefixed with `_`) MUST have contracts for all non-trivial \
+logic. Simple one-liner helpers may omit contracts but MUST have type annotations.
+
+### Class Invariants
+
+Every class MUST have `@icontract.invariant`. Invariants must constrain \
+actual state — tautological invariants like `lambda self: True` provide no \
+verification value. If a class is truly stateless (Protocol, stateless adapter), \
+omit the invariant and document why.
+
+---
+
+## Type Annotation Standards
+
+- All function signatures MUST have complete type annotations on every \
+parameter kind (including positional-only, keyword-only, variadic, and private \
+helper parameters) and the return type.
+- No use of `Any` anywhere — use `Protocol`, `Union`, or generics.
+- Generic types must be fully parameterized (`list[str]` not `list`).
+- Use modern type syntax (Python 3.10+): `X | None` not `Optional[X]`.
+
+---
+
+## Documentation Standards
+
+- Every module MUST have a module-level docstring.
+- Every public function and class MUST have a docstring.
+
+---
+
+## Architecture Standards
+
+```
+src/yourproject/
+├── core/        # Pure logic. No I/O. No os/pathlib/subprocess imports.
+├── ports/       # Protocol interfaces only.
+├── adapters/    # I/O implementations.
+└── cli.py       # Thin entry point.
+```
+
+Core modules (`core/`, models, contracts, checkers) MUST NOT import I/O \
+libraries (`os`, `pathlib`, `subprocess`, `requests`, `socket`, `shutil`, \
+`tempfile`, `glob`). Inject dependencies through function parameters.
+
+---
+
+## Error Handling Standards
+
+Only domain-specific exceptions permitted in core modules. Never raise bare \
+`Exception`, `ValueError`, `TypeError`, `RuntimeError`, `KeyError`, \
+`IndexError`, or `AttributeError` in core.
+
+---
+
+## Loop and Recursion Standards
+
+- Every loop MUST include a comment describing the loop invariant.
+- Recursive functions MUST document the variant (decreasing measure).
+- Prefer bounded iteration over unbounded `while`.
+
+---
+
+## Naming Conventions
+
+- Modules: `snake_case.py`. Classes: `PascalCase`. Functions: `snake_case`.
+
+---
+
+## No Exemptions
+
+Strict mode has NO exempt modules. Every module, including CLI and adapters, \
+must follow all conventions above.
+"""
+
+_MINIMAL_TEMPLATE = """\
+# SERENECODE.md — Minimal Project Conventions
+
+This file defines minimal code conventions for this project. AI coding agents \
+MUST read this before writing any code.
+
+Verified with: `serenecode check src/`
+
+---
+
+## Contract Standards
+
+Every public function MUST have `@icontract.require` (preconditions) and \
+`@icontract.ensure` (postconditions). Type annotations on all parameters \
+and return values.
+
+```python
+import icontract
+
+@icontract.require(lambda items: len(items) > 0)
+@icontract.ensure(lambda items, result: min(items) <= result <= max(items))
+def compute_mean(items: list[float]) -> float:
+    return sum(items) / len(items)
+```
+
+Functions with no meaningful parameters may omit `@icontract.require` but \
+MUST still have `@icontract.ensure`.
+
+---
+
+## Exemptions
+
+- `cli.py` — Thin CLI layer.
+- `adapters/` — I/O boundary code.
+- `templates/` — Static files.
+- `tests/fixtures/` — Test fixtures.
+"""
+
+_TEMPLATES = {
+    "default": _DEFAULT_TEMPLATE,
+    "strict": _STRICT_TEMPLATE,
+    "minimal": _MINIMAL_TEMPLATE,
+}
+
+
+@icontract.require(
+    lambda template_name: is_valid_template_name(template_name),
+    "template_name must be a valid template name",
+)
+@icontract.ensure(
+    lambda result: isinstance(result, str) and len(result) > 0,
+    "result must be a non-empty string",
+)
+def get_template(template_name: str) -> str:
+    """Return the template content for a named template.
+
+    Args:
+        template_name: One of 'default', 'strict', or 'minimal'.
+
+    Returns:
+        The full SERENECODE.md template content.
+    """
+    return _TEMPLATES[template_name]

serenecode-0.1.0.dist-info/METADATA

@@ -0,0 +1,298 @@
+Metadata-Version: 2.4
+Name: serenecode
+Version: 0.1.0
+Summary: Verification framework for AI-generated Python — test coverage, property testing, and symbolic execution
+Project-URL: Homepage, https://github.com/helgster77/serenecode
+Project-URL: Repository, https://github.com/helgster77/serenecode
+Project-URL: Issues, https://github.com/helgster77/serenecode/issues
+Author: helgster77
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Testing
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: click>=8.0
+Requires-Dist: icontract>=2.7.0
+Provides-Extra: dev
+Requires-Dist: crosshair-tool>=0.0.60; extra == 'dev'
+Requires-Dist: hypothesis>=6.0; extra == 'dev'
+Requires-Dist: mypy>=1.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Provides-Extra: verify
+Requires-Dist: coverage>=7.0; extra == 'verify'
+Requires-Dist: crosshair-tool>=0.0.60; extra == 'verify'
+Requires-Dist: hypothesis>=6.0; extra == 'verify'
+Requires-Dist: mypy>=1.0; extra == 'verify'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="serenecode.jpg" alt="SereneCode" width="500">
+</p>
+
+<h3 align="center">A Framework for AI-Driven Development of Verifiable Systems</h3>
+
+SereneCode is a verification framework for AI-generated Python. It tells the AI *how* to write verifiable code, checks that the AI followed instructions, and then verifies the code at multiple levels — from test coverage analysis that catches gaps in AI-written tests, through property-based testing that checks contracts against hundreds of random inputs, to symbolic execution that uses an SMT solver to search for *any* input that breaks a contract. You choose the verification depth that matches your project: lightweight for internal tools, balanced for production systems, strict for safety-critical code. AI agents write code fast but can be suboptimal at testing their own work; SereneCode closes that gap by surfacing untested paths, generating test suggestions, and verifying behavior beyond what hand-written tests cover.
+
+> **This framework was bootstrapped with AI under its own rules.** SereneCode's SERENECODE.md was written before the first line of code, and the codebase has been developed under those conventions from the start. The current tree passes its own `serenecode check src --level 6 --allow-code-execution`, an internal strict-config Level 6 self-check in the test suite, `mypy src examples/dosage-serenecode/src`, the shipped example's strict Level 6 check, and the full `pytest` suite. The verification output is transparent about scope: exempt modules (adapters, CLI, ports) and functions excluded from deep verification (non-primitive parameter types) are reported as "exempt" rather than silently omitted.
+
+---
+
+## Why This Exists
+
+AI writes code fast. But *fast* and *correct* aren't the same thing. When you're building a medical dosage calculator, a financial ledger, or an avionics controller, "it passed my tests" isn't enough. Tests check the inputs you thought of. Formal verification uses an SMT solver to search for *any* input that breaks your contracts.
+
+The problem is that formal verification has always been expensive — too slow, too manual, too specialized. SereneCode makes it tractable by controlling the process from the start: a convention file tells the AI to write verification-ready code, a structural linter checks it followed the rules, and CrossHair + Z3 search for contract violations via symbolic execution.
+
+SereneCode is designed for **building new verifiable systems from scratch with AI**, not for retrofitting verification onto large existing codebases. The conventions go in before the first line of code, and every module is written with verification in mind from day one. That's what makes it work. SereneCode is a best-effort tool, not a guarantee — see the [Disclaimer](#disclaimer) for important limitations on what it can and cannot assure.
+
+### Choosing the Right Level
+
+The cost of verification should be proportional to the cost of a bug. Each level generates a different SERENECODE.md with different requirements for the AI, so the choice shapes how code is *written*, not just how it's checked.
+
+| | `--minimal` | **Default** | `--strict` |
+|---|---|---|---|
+| **Verifies through** | L2 (structure + types) | L4 (+ test coverage + properties) | L6 (+ symbolic + compositional) |
+| **What the AI must write** | Contracts on public functions, type annotations | + description strings, class invariants, hexagonal architecture | + contracts on *all* functions, loop invariants, domain exceptions, no exemptions |
+| **What catches bugs** | Runtime contract checks, mypy | + L3 surfaces untested code paths and generates test suggestions; L4 tests contracts against hundreds of random inputs | + SMT solver searches for *any* counterexample within analysis bounds |
+| **Good for** | Internal tools, scripts, prototypes, incremental adoption | Production APIs, business logic, data pipelines | Medical, financial, infrastructure, regulated systems |
+| **The tradeoff** | Low ceremony, but contracts are only checked at the boundaries you wrote them | Moderate overhead; architecture rules keep core logic pure and testable | Significant overhead — every loop gets an invariant comment, every helper gets a contract. Justified when the cost of an undiscovered bug is measured in patient harm, financial loss, or regulatory failure |
+
+Pick the level that matches the stakes, and pick it early. Moving up later means retrofitting contracts, invariants, and architecture onto existing code — it's not just flipping a flag. Safety-critical code should be written for `--strict` from the first line.
+
+---
+
+## See It In Action: The Medical Dosage Calculator
+
+We built the same medical dosage calculator twice from the same spec — once with plain AI, once with SereneCode — to show the difference.
+
+Both versions implement four functions: dose calculation with weight-based dosing and max caps, renal function adjustment with tiered CrCl thresholds, daily safety checks with explicit total-versus-threshold calculations, and contraindication detection across current medications.
+
+Both versions implement the same requirements, and the plain version passes its 59-test suite. Here's what SereneCode adds on top:
+
+| What can you claim? | Plain AI | SereneCode |
+|---|---|---|
+| **Dose never exceeds maximum** | Covered by unit tests | Encoded as a postcondition; bounded symbolic search found no counterexample within analysis bounds |
+| **Renal adjustment never increases a dose** | Covered by unit tests | `result <= dose_mg` is an executable contract, not just a test expectation |
+| **Safety result is internally consistent** | No validation — you can construct `SafetyResult(total=9999, max=100, is_safe=True)` | Representation invariants make inconsistent `SafetyResult` states unconstructable |
+| **Objects are truly immutable** | `frozen=True` with mutable `set` on Drug | `_Frozen` mixin + immutable `tuple`/`frozenset` fields — fully locked down |
+| **Boundary behavior (CrCl exactly 30.0)** | Covered by explicit tests | Boundary behavior is specified in contracts; bounded symbolic search found no counterexample |
+| **What if someone changes the code later?** | You rely on the tests you remembered to keep | Contracts stay attached to the code and keep checking every contracted call |
+| **Can a solver verify it?** | No executable specification for a solver to target | 120 executable contracts and a clean `serenecode check ... --level 6 --allow-code-execution` run |
+| **Confidence in a safety-critical setting** | Better than ad hoc code, but still test-shaped confidence | Higher: behavior is formally specified, runtime-checked, and solver-checked within analysis bounds — but bounded search is not proof |
+
+The plain version relies on 59 tests that check specific scenarios. The SereneCode version adds 120 executable contracts across its domain models and core dosage logic. Those contracts define *what correct means* in code, get checked at runtime, and give CrossHair/Z3 something precise to search against when looking for counterexamples within analysis bounds.
+
+> Both examples live in [`examples/dosage-regular/`](examples/dosage-regular/) and [`examples/dosage-serenecode/`](examples/dosage-serenecode/). Read them side by side.
+
+The Serenecode dosage example currently passes `serenecode check examples/dosage-serenecode/src --level 6 --allow-code-execution`. Its local `pytest` suite is also green with 74 passing tests.
+
+---
+
+## How It Works
+
+### 1. SERENECODE.md — Your AI Writes Code That's Built for Verification
+
+A markdown file in your project root that tells AI coding agents exactly how to write code: what contracts to include, what architecture to follow, what patterns to use. When Claude Code (or another agent) reads this before generating code, it has a concrete target for producing verification-friendly output from the first keystroke.
+
+```bash
+serenecode init              # balanced defaults — contracts on public APIs, test coverage, hexagonal architecture
+serenecode init --strict     # maximum rigor — contracts on ALL functions (public and private), no exemptions
+serenecode init --minimal    # lightweight — public-function contracts only, relaxed architecture rules
+```
+
+This creates a SERENECODE.md tailored to your project and integrates with CLAUDE.md so Claude Code follows the conventions automatically. You write the rules once, and the agent has a stable spec to follow on every iteration.
+
+### 2. The Checker — Instant Feedback
+
+A lightweight AST-based linter that validates code follows SERENECODE.md conventions in seconds. Missing a postcondition? No class invariant? I/O imports in a core module? Caught before you waste time on heavy verification.
+
+```bash
+serenecode check src/ --structural    # seconds
+```
+
+### 3. The Verifier — Symbolic Verification
+
+A six-level verification pipeline that escalates from fast checks to full symbolic verification:
+
+| Level | What | Speed | Backend |
+|-------|------|-------|---------|
+| **L1** | Structural conventions | Seconds | AST analysis |
+| **L2** | Type correctness | Seconds | mypy --strict |
+| **L3** | Test coverage analysis | Seconds–minutes | coverage.py |
+| **L4** | Property-based testing | Seconds–minutes | Hypothesis |
+| **L5** | Symbolic search (bounded) | Minutes | CrossHair / Z3 |
+| **L6** | Cross-module verification | Seconds | Compositional analysis |
+
+```bash
+serenecode check src/ --level 6 --allow-code-execution  # verify it
+```
+
+**L3 Test Coverage** is where SereneCode checks that the AI's tests actually exercise the code it wrote. AI agents can be suboptimal at writing tests — they tend to cover the happy path, skip edge cases, and miss error branches. L3 runs your existing tests under coverage.py tracing, measures per-function line and branch coverage, and reports exactly which lines and branches are untested. For each coverage gap, it generates concrete test suggestions including mock necessity assessments: each dependency is classified as REQUIRED (external I/O — must mock) or OPTIONAL (internal code — consider using the real implementation). This gives the AI agent actionable feedback to improve its own tests rather than leaving coverage gaps undetected. When no tests exist for a module, L3 reports this as informational rather than failing, so the coverage level serves as a baseline measurement before L4 property testing generates new test inputs.
+
+The full pipeline is thorough but not instant. Larger systems will take longer, and the deepest runs may surface skipped items when Hypothesis cannot synthesize valid values for complex domain types or when CrossHair hits its time budget. By default, L5 focuses on contracted top-level functions defined in each module and skips modules or signatures that are currently poor fits for direct symbolic execution, such as adapter/composition-root code, helper predicate modules, and object-heavy APIs. Not everything needs L5/L6. Critical paths get full symbolic and compositional verification. Utility functions get property testing. A Level 4 run only counts as achieved when at least one contracted property target was actually exercised.
+
+Levels 3-6 import and execute project modules so coverage.py, Hypothesis, and CrossHair can exercise real code. Deep runs therefore require explicit `--allow-code-execution` and should only be used on trusted code.
+
+Scoped targets keep their package/import context across verification levels. In practice that means commands like `serenecode check src/core/ --level 4 --allow-code-execution` and `serenecode check src/core/models.py --level 3 --allow-code-execution` use the same local import roots and architectural module paths as a project-wide run instead of breaking relative imports or scoped core-module rules. Those scoped core/exemption rules are matched on path segments, not raw substrings, so names like `notcli.py`, `viewmodels.py`, and `transports/` do not accidentally change policy classification. Standalone files with non-importable names are also targeted correctly for CrossHair via `file.py:line` references.
+
+---
+
+## The AI Agent Loop
+
+SereneCode is designed for AI agents that write code and fix their own mistakes:
+
+```
+AI reads SERENECODE.md           → knows how to write verification-ready code
+AI generates code with contracts → postconditions, input preconditions, invariants
+serenecode check --structural                        → instant: did the AI follow the rules?
+serenecode check --level 5 --allow-code-execution   → deep: can the solver find any counterexample?
+AI reads counterexamples         → "input x=[-1] violates postcondition"
+AI fixes the code                → adjusts implementation or contract
+Repeat until verified            → no counterexample found, not just tested
+```
+
+AI-generated code won't always pass verification on the first try — and that's the point. SereneCode gives the coding agent structured feedback on exactly what failed and why: counterexamples, violated contracts, and suggested fixes. The agent uses that feedback to iterate until the code passes. The value isn't in one-shotting perfection — it's in the loop that converges on verified correctness.
+
+Works in Claude Code, works in the terminal, works in CI:
+
+```python
+import serenecode
+
+result = serenecode.check(path="src/", level=5, allow_code_execution=True)
+for failure in result.failures:
+    print(f"{failure.function} @ {failure.file}:{failure.line}")
+    for detail in failure.details:
+        if detail.counterexample is not None:
+            print(detail.counterexample)  # exact input that breaks the code
+        if detail.suggestion is not None:
+            print(detail.suggestion)      # proposed fix direction
+```
+
+---
+
+## Built With Its Own Medicine
+
+SereneCode isn't just a tool that *tells* you to write verified code. It *is* verified code.
+
+The SERENECODE.md convention file was the first artifact created — before any Python was written. The framework has been developed under those conventions with AI as a first-class contributor, and the repository continuously checks itself with:
+
+- `pytest` across the full suite (currently 651 passing tests, 16 skipped)
+- `mypy --strict` across `src/` and `examples/dosage-serenecode/src/`
+- SereneCode's own structural, type, property, symbolic, and compositional passes
+
+On the current tree, `serenecode check src --level 6 --allow-code-execution` runs all six verification levels. The exempt items include adapter modules (which handle I/O and are integration-tested), port interfaces (Protocols that define abstract contracts), CLI entry points, and functions whose parameter types are too complex for automated strategy generation or symbolic execution. Exempt items are visible in the output — they are not silently omitted.
+
+At Level 5, CrossHair and Z3 search for counterexamples across the codebase's symbolic-friendly contracted top-level functions. Functions with non-primitive parameters (custom dataclasses, Protocol implementations, Callable types) are reported as exempt because the solver cannot generate inputs for them. Level 6 adds structural compositional analysis: dependency direction, circular dependency detection, interface compliance, contract presence at module boundaries, aliased cross-module call resolution, and architectural invariants. Interface compliance follows explicit `Protocol` inheritance and checks substitutability, including extra required parameters and incompatible return annotations. Together, they provide both deep per-function verification and system-level structural guarantees — but the structural checks at L6 verify contract *presence*, not logical *sufficiency* across call chains.
+
+---
+
+## Quick Start
+
+```bash
+# Clone and install from source
+git clone https://github.com/helgster77/serenecode.git
+cd serenecode
+uv sync --extra verify
+
+# Or with pip:
+# pip install -e ".[verify]"
+
+# Initialize a project with conventions
+serenecode init
+
+# Let your AI agent write code following SERENECODE.md...
+# Then verify:
+serenecode check src/ --structural
+
+# Or go deep:
+serenecode check src/core/ --level 5 --allow-code-execution --format json
+```
+
+JSON output includes top-level `passed`, `level_requested`, and `level_achieved` fields alongside the summary and per-function results.
+
+When you verify a nested package or a single module, Serenecode now preserves the package root and module-path context used by mypy, Hypothesis, CrossHair, and the architectural checks. That lets package-local absolute imports, relative imports, and scoped core-module rules behave the same way they do in project-wide runs.
+
+## CLI Reference
+
+```bash
+serenecode init [<path>] [--strict | --minimal]                         # set up conventions
+serenecode check [<path>] [--level 1-6] [--allow-code-execution]        # run verification
+                          [--format human|json]                         #   output format
+                          [--structural] [--verify]                     #   L1 only / L3-6 only
+                          [--per-condition-timeout N]                   #   L5 CrossHair budgets
+                          [--per-path-timeout N] [--module-timeout N]   #   (defaults: 30/10/300s)
+                          [--workers N]                                 #   L5 parallel workers
+serenecode status [<path>] [--format human|json]                        # verification status
+serenecode report [<path>] [--format human|json|html]                   # generate reports
+                           [--output FILE] [--allow-code-execution]     #   write to file
+```
+
+**Exit codes:** 0 = passed, 1 = structural, 2 = types, 3 = coverage, 4 = properties, 5 = symbolic, 6 = compositional, 10 = internal error or deep verification refused without explicit trust.
+
+---
+
+## Honest Limitations
+
+SereneCode is honest about what it can and can't do:
+
+**"No counterexample found" is not "proven correct."** CrossHair uses bounded symbolic execution backed by Z3 — it explores execution paths within time limits (default: 30 seconds per condition, 10 seconds per path, 300 seconds per module) and searches for counterexamples. When it reports "no counterexample found within analysis bounds," that's strong evidence of correctness for the explored paths, but it's not an unbounded proof in the Coq/Lean sense. For pure functions with simple control flow, the coverage is often effectively exhaustive. For complex code, it's bounded. The tool's output now uses this honest language rather than saying "verified."
+
+**Contracts are only as good as you write them.** A function with weak postconditions will pass verification even if the implementation is subtly wrong. SereneCode checks that contracts exist and hold, but can't check that they fully capture your intent. Tautological contracts like `lambda self: True` are now flagged by the conventions and should not be used — they provide no verification value.
+
+**Exempt items are visible, not hidden.** Modules exempt from structural checking (adapters, CLI, ports, `__init__.py`) and functions excluded from deep verification (non-primitive parameter types, adapter code) are reported as "exempt" in the output rather than being silently omitted. This makes the verification scope transparent: the tool reports passed, failed, skipped, and exempt counts separately so you can see exactly what was and wasn't deeply verified. Previous versions silently omitted these, inflating the apparent scope.
+
+**Runtime checks can be disabled.** icontract decorators are checked on every call by default, but can be disabled via environment variables for performance in production. This is a feature, not a bug — but it means runtime guarantees depend on configuration.
+
+**Not everything can be deeply verified.** Functions with complex domain-type parameters (custom dataclasses, Callable, Protocol implementations) are automatically excluded from L4/L5 because the tools cannot generate valid inputs for them — they show up as "exempt" in the output. See "Choosing the Right Level" above for guidance on which verification depth fits your system.
+
+**Levels 3-6 execute your code.** Coverage analysis, property-based testing, and symbolic verification import project modules and run their top-level code as part of analysis. Module loading uses `compile()` + `exec()` on target source files and their transitive dependencies. There is no sandboxing or syscall filtering — a malicious `.py` file in the target directory gets full access to the host. Use `--allow-code-execution` or `allow_code_execution=True` only for code you trust. Subprocess-based backends (CrossHair, pytest/coverage) receive module paths and search paths from the source discovery layer; symlink-based directory traversal is blocked (`followlinks=False`), but the trust boundary ultimately relies on the `--allow-code-execution` gate.
+
+**Deep runs can be incomplete by default.** A result can include skipped items even when there are no correctness failures: Hypothesis may not be able to derive strategies for some highly structured project-local types, and CrossHair can time out on solver-heavy modules once the module budget is exhausted. When a run exercises no property-testing targets at all, Serenecode does not claim L4 was achieved. When a scoped run produces no symbolic findings at all, Serenecode does not claim L5 was achieved. A verification level is only marked as achieved when results are non-empty with no failures and no skips — empty results from L3/L4/L5 backends mean "nothing was exercised," not "everything passed." Increase `--per-condition-timeout`, `--per-path-timeout`, or `--module-timeout` when you want to push harder on L5.
+
+**Level 6 is structural, not semantic.** Compositional verification (L6) checks that contracts *exist* at module boundaries, that dependency direction is correct, and that interfaces structurally match, including explicit `Protocol` inheritance and signature-shape compatibility. It does not verify that postconditions *logically satisfy* preconditions across call chains — that would require symbolic reasoning across module boundaries, which is a planned future enhancement. L6 catches architectural violations and contract gaps, not logical insufficiency. Source files with syntax errors are now reported as skipped with an actionable message instead of silently producing an empty analysis.
+
+
+
+---
+
+## Architecture
+
+SereneCode follows hexagonal architecture — the same pattern it enforces on your code:
+
+```
+CLI / Library API           ← composition roots
+    │
+    ├──▸ Pipeline           ← orchestrates L1 → L2 → L3 → L4 → L5 → L6
+    │       ├──▸ Structural Checker    (ast)
+    │       ├──▸ Type Checker          (mypy)
+    │       ├──▸ Coverage Analyzer     (coverage.py)
+    │       ├──▸ Property Tester       (Hypothesis)
+    │       ├──▸ Symbolic Checker      (CrossHair/Z3)
+    │       └──▸ Compositional Checker (ast)
+    │
+    ├──▸ Reporter           ← human / JSON / HTML
+    │
+    └──▸ Adapters → Ports   ← Protocol interfaces for all I/O
+```
+
+Core logic is pure. All I/O goes through Protocol-defined ports. The verification engine itself is verifiable.
+
+## Disclaimer
+
+SereneCode is provided as-is, without warranty of any kind. It is a best-effort tool that helps surface defects through contracts, property-based testing, and bounded symbolic execution — but it cannot guarantee the absence of bugs. "No counterexample found" means the solver did not find one within its analysis bounds, not that none exists. Verification results depend on the quality of the contracts you write, the time budgets you configure, and the inherent limitations of the underlying tools.
+
+Users are responsible for the correctness, safety, and regulatory compliance of their own systems. SereneCode is not a substitute for independent code review, domain-expert validation, or any certification process required by your industry. If you are building safety-critical software, use this framework as one layer of assurance among many — not as the only one.
+
+## License
+
+MIT