serenecode 0.4.0__tar.gz → 0.5.0__tar.gz

{serenecode-0.4.0 → serenecode-0.5.0}/CLAUDE.md

@@ -1,6 +1,6 @@
 ## Serenecode
 
-All code in this project MUST follow the standards defined in SERENECODE.md. Read SERENECODE.md before writing or modifying any code. Every public function must have icontract preconditions and postconditions. Every class with state must have invariants. Follow the architectural patterns specified in SERENECODE.md.
+All code in this project MUST follow the same standards SereneCode ships to users: the embedded templates in `src/serenecode/templates/content.py` (default / strict / minimal) define the conventions the structural checker enforces. Read the relevant template before writing or modifying any code. Every public function must have icontract preconditions and postconditions. Every class with state must have invariants. Follow the architectural patterns specified there.
 
 Pre-existing `*_SPEC.md` or PRD files are narrative inputs; only project-root `SPEC.md` with REQ/INT identifiers satisfies SereneCode traceability (`serenecode check --spec`).
 

{serenecode-0.4.0 → serenecode-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: serenecode
-Version: 0.4.0
+Version: 0.5.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
@@ -51,7 +51,7 @@ SereneCode turns the question from "did the model ship code?" to "does it match
 
 **MCP:** register the server once (Claude Code, Cursor, Cline, Continue, or any MCP client) and the agent can pull structured JSON—findings, suggestions, counterexamples—while the cursor is still on the line, instead of discovering issues only after merge.
 
-> **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 — including the MCP server, which the same AI agents now use to verify their own work mid-edit. The current tree passes its own `serenecode check src --level 6 --allow-code-execution` end-to-end via the bare CLI (counts vary with the tree; expect hundreds of functions with a mix of passed, exempt, and advisory dead-code notes; wall time on the order of minutes for a full L1–L6 run), an internal strict-config Level 6 self-check in the test suite (`pytest tests/integration/test_example_projects.py::test_serenecode_repo_passes_strict_level_6`, which exercises L4–L6 against `strict_config` over the full source tree), `mypy src examples/dosage-serenecode/src`, the shipped dosage example's own `serenecode check src --level 6 --allow-code-execution`, and the full `pytest` suite (on the order of 1,400+ passing tests; a small number are skipped by design). The verification output is transparent about scope: exempt modules (adapters, CLI, ports, MCP server, `__init__.py`) and functions excluded from deep verification (non-primitive parameter types) are reported as "exempt" rather than silently omitted; dead-code findings are **advisories** and appear in the summary unless you use `--fail-on-advisory` to fail CI when any remain.
+> **This framework was bootstrapped with AI under its own rules.** Convention templates in `src/serenecode/templates/content.py` were defined before the first line of code, and the codebase has been developed under those conventions from the start — including the MCP server, which the same AI agents now use to verify their own work mid-edit. The current tree passes its own `serenecode check src --level 6 --allow-code-execution` end-to-end via the bare CLI (counts vary with the tree; expect hundreds of functions with a mix of passed, exempt, and advisory notes; wall time on the order of minutes for a full L1–L6 run), an internal strict-config Level 6 self-check in the test suite (`pytest tests/integration/test_example_projects.py::test_serenecode_repo_passes_strict_level_6`, which exercises L4–L6 against `strict_config` over the full source tree), `mypy src examples/dosage-serenecode/src`, the shipped dosage example's own `serenecode check src --level 6 --allow-code-execution`, and the full `pytest` suite (on the order of 1,450+ passing tests; a small number are skipped by design). The verification output is transparent about scope: exempt modules (adapters, CLI, ports, MCP server, `__init__.py`) and functions excluded from deep verification (non-primitive parameter types) are reported as "exempt" rather than silently omitted; dead-code and module health findings are **advisories** and appear in the summary unless you use `--fail-on-advisory` to fail CI when any remain.
 
 ---
 
@@ -85,6 +85,8 @@ After enough hours pair-programming with coding agents, the same handful of mist
 
 - **Tests that pass but verify nothing.** A `def test_foo(): foo()` with no `assert` runs successfully and counts as "covered" — but it only checks that the function doesn't raise. L1's no-assertions-in-tests check fires on any `test_*` function with no `assert`, `pytest.raises`, `pytest.fail`, or `self.assertX` call.
 
+- **Module bloat and god classes.** Agents accumulate code in a single module without splitting. A 2000-line file with 30 methods on one class compiles and tests pass, but it's unmaintainable. Module health checks flag files, functions, and classes that exceed configurable thresholds — advisory warnings when they're getting large, hard errors when they exceed the maximum. The agent gets concrete split suggestions derived from AST analysis: which classes could be standalone modules, which function groups share a prefix, and where banner comments suggest logical boundaries.
+
 - **Architectural drift.** Asked to "add a feature," the agent puts I/O in core, business logic in adapters, and circular imports between them. The system still works in tests because everything is loaded together — but the layering rule that made the code testable in the first place is gone. L6 compositional checks enforce dependency direction, interface compliance, and contract presence at module boundaries.
 
 None of these failures are unique to AI; humans make them too. What's unique is the *rate* at which an agent produces them and the *confidence* with which the agent reports the work as done. The structural checker, the contracts, the property tester, and the symbolic search exist to make each pattern impossible to ship without an explicit, reviewed override.
@@ -162,7 +164,7 @@ This creates SERENECODE.md (project conventions including spec traceability) and
 
 A lightweight AST-based checker that validates code follows SERENECODE.md conventions in seconds. Missing a postcondition? No class invariant? No test file for a module? Caught before you waste time on heavy verification.
 
-L1 also catches AI-failure-mode patterns that compile and look correct but represent real bugs: stub residue (`pass`/`...`/`raise NotImplementedError` left as a function body), mutable default arguments, bare `assert` in non-test source, `print()` in core, dangerous calls (`eval`, `exec`, `pickle.loads`, `os.system`, `subprocess` with `shell=True`), `TODO`/`FIXME`/`XXX`/`HACK` markers in tracked files, tests with no assertions, silent exception handlers, tautological postconditions, and likely dead code. Dead-code findings are advisory review items: the agent should ask the user whether to remove or allowlist the code before changing it. Each rule has a per-rule opt-out comment for legitimate exceptions; see SERENECODE.md "Code Quality Standards" for the full list.
+L1 also catches AI-failure-mode patterns that compile and look correct but represent real bugs: stub residue (`pass`/`...`/`raise NotImplementedError` left as a function body), mutable default arguments, bare `assert` in non-test source, `print()` in core, dangerous calls (`eval`, `exec`, `pickle.loads`, `os.system`, `subprocess` with `shell=True`), `TODO`/`FIXME`/`XXX`/`HACK` markers in tracked files, tests with no assertions, silent exception handlers, tautological postconditions, and likely dead code. L1 additionally runs **module health checks**: files exceeding a configurable line threshold, functions that are too long, functions with too many parameters, and classes with too many methods generate warnings (advisory) or errors depending on severity. These target the common AI agent drift pattern of accumulating code in a single module without splitting. Dead-code and module health findings are advisory review items; each rule has a per-rule opt-out comment for legitimate exceptions. See SERENECODE.md "Code Quality Standards" and "Module Health" for the full list. Skip all module health checks with `--skip-module-health`.
 
 ```bash
 serenecode check src/ --structural          # structural conventions + dead-code review
@@ -228,8 +230,9 @@ The same `serenecode mcp` stdio server works in Claude Code, Cursor, Cline, Cont
 | `serenecode_integration_status` | Implementation/verification status of one INT |
 | `serenecode_orphans` | REQs with no implementation or no test |
 | `serenecode_dead_code` | Likely dead-code findings that require user review |
+| `serenecode_module_health` | Module health metrics (file size, function lengths, parameter counts, class sizes) for a single file — no verification needed |
 
-Tool results mirror the CLI pipeline: structured payloads include **`passed`**, levels, **`verdict`**, and a **summary** with counts (including **`advisory_count`** for dead-code-style exempt rows). Paths and `project_root` are resolved on the host — they are not sandboxed to one workspace; see [docs/SECURITY.md](docs/SECURITY.md).
+Tool results mirror the CLI pipeline: structured payloads include **`passed`**, levels, **`verdict`**, and a **summary** with counts (including **`advisory_count`** for advisory findings like dead code and module health warnings). Paths and `project_root` are resolved on the host — they are not sandboxed to one workspace; see [docs/SECURITY.md](docs/SECURITY.md).
 
 **Read-only resources** the agent can fetch without "calling" anything: `serenecode://config` (active SerenecodeConfig as JSON), `serenecode://findings/last-run` (most recent CheckResponse from this server session), `serenecode://exempt-modules` (the exempt path patterns for the active config), `serenecode://reqs` (parsed REQ-xxx list from the project's SPEC.md), and `serenecode://integrations` (parsed INT-xxx metadata from the project's SPEC.md).
 
@@ -310,13 +313,13 @@ The library API (`serenecode.check`) and the MCP server (`serenecode_check`, `se
 
 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:
+Those convention templates were the first artifacts — 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 (on the order of 1,400+ passing tests; a small number skipped by design)
+- `pytest` across the full suite (on the order of 1,450+ passing tests; a small number skipped by design)
 - `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 the full L1–L6 pipeline against the framework's own source; exact counts of passed / exempt / advisory rows change as the tree grows (wall time often several minutes for a deep run). A separate integration test, `test_serenecode_repo_passes_strict_level_6`, runs the same `src/` tree through `run_pipeline` with `strict_config()` and `start_level=4`, which strips path-based exemptions and forces adapters, CLI, MCP, and similar code through L4–L6. The exempt items in a **default-config** run still include adapter modules, port `Protocol`s, CLI/MCP composition roots, and functions whose parameter types are poor fits for Hypothesis/CrossHair. Exempt and advisory rows stay visible in the output — they are not silently omitted.
+On the current tree, `serenecode check src --level 6 --allow-code-execution` runs the full L1–L6 pipeline against the framework's own source; exact counts of passed / exempt / advisory rows change as the tree grows (wall time often several minutes for a deep run). A separate integration test, `test_serenecode_repo_passes_strict_level_6`, runs the same `src/` tree through `run_pipeline` with `strict_config()` and `start_level=4`, which strips path-based exemptions and forces adapters, CLI, MCP, and similar code through L4–L6. The exempt items in a **default-config** run still include adapter modules, port `Protocol`s, CLI/MCP composition roots, and functions whose parameter types are poor fits for Hypothesis/CrossHair. Advisory items include dead-code findings and module health warnings (file length, function length, parameter count, class method count). Exempt and advisory rows stay 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.
 
@@ -365,7 +368,8 @@ serenecode check [<path>] [--level 1-6] [--allow-code-execution]        # run ve
                           [--project-root DIR]                          #   repo root for imports + config
                           [--format human|json]                         #   output format
                           [--structural] [--verify]                     #   L1 only / L3-6 only
-                          [--fail-on-advisory]                         #   exit 11 if dead-code advisories remain
+                          [--skip-module-health]                        #   skip file/function/param/class size checks
+                          [--fail-on-advisory]                         #   exit 11 if advisories remain
                           [--per-condition-timeout N]                   #   L5 CrossHair budgets
                           [--per-path-timeout N] [--module-timeout N]   #   (defaults: 30/10/300s)
                           [--coverage-timeout N]                        #   L3 pytest/coverage subprocess (default 600s)
@@ -379,7 +383,7 @@ serenecode mcp [--allow-code-execution]                                 # boot t
 
 **Environment (optional):** `SERENECODE_MAX_WORKERS` overrides `--workers`; `SERENECODE_COVERAGE_TIMEOUT` overrides `--coverage-timeout`. **`SERENECODE_DEBUG=1`** logs subprocess environment **key names** (not values) when tools spawn mypy, pytest, CrossHair, etc. Details: [docs/SECURITY.md](docs/SECURITY.md).
 
-**Exit codes:** 0 = passed (and no `--fail-on-advisory` violation), 1–6 = first failing verification level (structural … compositional), 10 = internal error or deep verification refused without `--allow-code-execution`, **11 = dead-code advisories remain with `--fail-on-advisory`** (checks otherwise passed).
+**Exit codes:** 0 = passed (and no `--fail-on-advisory` violation), 1–6 = first failing verification level (structural … compositional), 10 = internal error or deep verification refused without `--allow-code-execution`, **11 = advisories remain with `--fail-on-advisory`** (dead code, module health warnings; checks otherwise passed).
 
 ---
 
@@ -391,7 +395,7 @@ SereneCode is honest about what it can and can't do:
 
 **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, MCP server, `__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.
+**Exempt items are visible, not hidden.** Modules exempt from structural checking (adapters, CLI, ports, MCP server, `__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. Advisory items (dead code, module health warnings) are also visible and counted separately. This makes the verification scope transparent: the tool reports passed, failed, skipped, exempt, and advisory counts separately so you can see exactly what was and wasn't deeply verified.
 
 **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.
 
@@ -419,6 +423,7 @@ CLI / Library API / MCP     ← composition roots (interactive init, spec valida
     │       ├──▸ Structural Checker    (ast)
     │       ├──▸ Spec Traceability     (REQ-xxx / INT-xxx → Implements/Verifies)
     │       ├──▸ Dead-Code Review      (likely unused code → ask before removal)
+    │       ├──▸ Module Health         (file/function/class size → advisory or error)
     │       ├──▸ Test Existence        (test_<module>.py discovery)
     │       ├──▸ Type Checker          (mypy)
     │       ├──▸ Coverage Analyzer     (coverage.py)
@@ -433,6 +438,16 @@ CLI / Library API / MCP     ← composition roots (interactive init, spec valida
 
 Core logic is pure. All I/O goes through Protocol-defined ports. The verification engine itself is verifiable.
 
+## Comparison: AWS Kiro and Spec Kit / Speckit
+
+SereneCode overlaps with these tools on **spec-first, AI-assisted development**—all three push against unstructured “vibe coding.” The difference is **what each product optimizes for**.
+
+**AWS Kiro** is an agentic AI IDE from AWS (Bedrock-powered), with spec-driven flows, autonomous agents, “powers,” and multi-repo work inside that environment. SereneCode is **not an IDE**: it is a **Python verification toolkit** (CLI + MCP) that plugs into editors you already use. Kiro optimizes **how you build in their stack**; SereneCode optimizes **repeatable assurance on Python code**—traceability from root `SPEC.md` IDs to implementation and tests, `icontract` contracts, mypy, coverage, Hypothesis, bounded CrossHair search, and compositional checks. The two are **complementary** if you use Kiro to author code but still want repo-local, machine-checkable verification on a Python tree.
+
+**Spec Kit** (GitHub’s methodology) and ecosystem tools such as **Speckit** focus on **structured specification and phased delivery**—for example constitution, specify, plan, tasks, and implementation—with agents and templates driving the workflow. “Executable” there often means **process and artifact structure** that steers implementation. SereneCode adds a different meaning of executable: **contracts and checkers that run against your Python**, plus optional solvers and property tests, with explicit **REQ-xxx / INT-xxx** traceability to `Implements:` / `Verifies:` in code and tests. Spec Kit is typically **stack-agnostic**; SereneCode is **Python-specific** by design.
+
+If you already use Spec Kit–style phases, SereneCode fits **after** the spec is stable enough to land as root `SPEC.md`—as the **verification layer** that answers whether the code and tests actually match what you declared.
+
 ## Security and trust
 
 Serenecode runs on **your machine** and, with `--allow-code-execution` (CLI or MCP), **imports and executes** project code—similar trust to running `pytest` or `python -m` on that tree. It is **not** a sandbox. Subprocesses receive a filtered environment to limit credential leakage; see [docs/SECURITY.md](docs/SECURITY.md) for the threat model, MCP behavior, `SERENECODE_DEBUG`, and CI exit code **11** with `--fail-on-advisory`.

{serenecode-0.4.0 → serenecode-0.5.0}/README.md

@@ -15,7 +15,7 @@ SereneCode turns the question from "did the model ship code?" to "does it match
 
 **MCP:** register the server once (Claude Code, Cursor, Cline, Continue, or any MCP client) and the agent can pull structured JSON—findings, suggestions, counterexamples—while the cursor is still on the line, instead of discovering issues only after merge.
 
-> **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 — including the MCP server, which the same AI agents now use to verify their own work mid-edit. The current tree passes its own `serenecode check src --level 6 --allow-code-execution` end-to-end via the bare CLI (counts vary with the tree; expect hundreds of functions with a mix of passed, exempt, and advisory dead-code notes; wall time on the order of minutes for a full L1–L6 run), an internal strict-config Level 6 self-check in the test suite (`pytest tests/integration/test_example_projects.py::test_serenecode_repo_passes_strict_level_6`, which exercises L4–L6 against `strict_config` over the full source tree), `mypy src examples/dosage-serenecode/src`, the shipped dosage example's own `serenecode check src --level 6 --allow-code-execution`, and the full `pytest` suite (on the order of 1,400+ passing tests; a small number are skipped by design). The verification output is transparent about scope: exempt modules (adapters, CLI, ports, MCP server, `__init__.py`) and functions excluded from deep verification (non-primitive parameter types) are reported as "exempt" rather than silently omitted; dead-code findings are **advisories** and appear in the summary unless you use `--fail-on-advisory` to fail CI when any remain.
+> **This framework was bootstrapped with AI under its own rules.** Convention templates in `src/serenecode/templates/content.py` were defined before the first line of code, and the codebase has been developed under those conventions from the start — including the MCP server, which the same AI agents now use to verify their own work mid-edit. The current tree passes its own `serenecode check src --level 6 --allow-code-execution` end-to-end via the bare CLI (counts vary with the tree; expect hundreds of functions with a mix of passed, exempt, and advisory notes; wall time on the order of minutes for a full L1–L6 run), an internal strict-config Level 6 self-check in the test suite (`pytest tests/integration/test_example_projects.py::test_serenecode_repo_passes_strict_level_6`, which exercises L4–L6 against `strict_config` over the full source tree), `mypy src examples/dosage-serenecode/src`, the shipped dosage example's own `serenecode check src --level 6 --allow-code-execution`, and the full `pytest` suite (on the order of 1,450+ passing tests; a small number are skipped by design). The verification output is transparent about scope: exempt modules (adapters, CLI, ports, MCP server, `__init__.py`) and functions excluded from deep verification (non-primitive parameter types) are reported as "exempt" rather than silently omitted; dead-code and module health findings are **advisories** and appear in the summary unless you use `--fail-on-advisory` to fail CI when any remain.
 
 ---
 
@@ -49,6 +49,8 @@ After enough hours pair-programming with coding agents, the same handful of mist
 
 - **Tests that pass but verify nothing.** A `def test_foo(): foo()` with no `assert` runs successfully and counts as "covered" — but it only checks that the function doesn't raise. L1's no-assertions-in-tests check fires on any `test_*` function with no `assert`, `pytest.raises`, `pytest.fail`, or `self.assertX` call.
 
+- **Module bloat and god classes.** Agents accumulate code in a single module without splitting. A 2000-line file with 30 methods on one class compiles and tests pass, but it's unmaintainable. Module health checks flag files, functions, and classes that exceed configurable thresholds — advisory warnings when they're getting large, hard errors when they exceed the maximum. The agent gets concrete split suggestions derived from AST analysis: which classes could be standalone modules, which function groups share a prefix, and where banner comments suggest logical boundaries.
+
 - **Architectural drift.** Asked to "add a feature," the agent puts I/O in core, business logic in adapters, and circular imports between them. The system still works in tests because everything is loaded together — but the layering rule that made the code testable in the first place is gone. L6 compositional checks enforce dependency direction, interface compliance, and contract presence at module boundaries.
 
 None of these failures are unique to AI; humans make them too. What's unique is the *rate* at which an agent produces them and the *confidence* with which the agent reports the work as done. The structural checker, the contracts, the property tester, and the symbolic search exist to make each pattern impossible to ship without an explicit, reviewed override.
@@ -126,7 +128,7 @@ This creates SERENECODE.md (project conventions including spec traceability) and
 
 A lightweight AST-based checker that validates code follows SERENECODE.md conventions in seconds. Missing a postcondition? No class invariant? No test file for a module? Caught before you waste time on heavy verification.
 
-L1 also catches AI-failure-mode patterns that compile and look correct but represent real bugs: stub residue (`pass`/`...`/`raise NotImplementedError` left as a function body), mutable default arguments, bare `assert` in non-test source, `print()` in core, dangerous calls (`eval`, `exec`, `pickle.loads`, `os.system`, `subprocess` with `shell=True`), `TODO`/`FIXME`/`XXX`/`HACK` markers in tracked files, tests with no assertions, silent exception handlers, tautological postconditions, and likely dead code. Dead-code findings are advisory review items: the agent should ask the user whether to remove or allowlist the code before changing it. Each rule has a per-rule opt-out comment for legitimate exceptions; see SERENECODE.md "Code Quality Standards" for the full list.
+L1 also catches AI-failure-mode patterns that compile and look correct but represent real bugs: stub residue (`pass`/`...`/`raise NotImplementedError` left as a function body), mutable default arguments, bare `assert` in non-test source, `print()` in core, dangerous calls (`eval`, `exec`, `pickle.loads`, `os.system`, `subprocess` with `shell=True`), `TODO`/`FIXME`/`XXX`/`HACK` markers in tracked files, tests with no assertions, silent exception handlers, tautological postconditions, and likely dead code. L1 additionally runs **module health checks**: files exceeding a configurable line threshold, functions that are too long, functions with too many parameters, and classes with too many methods generate warnings (advisory) or errors depending on severity. These target the common AI agent drift pattern of accumulating code in a single module without splitting. Dead-code and module health findings are advisory review items; each rule has a per-rule opt-out comment for legitimate exceptions. See SERENECODE.md "Code Quality Standards" and "Module Health" for the full list. Skip all module health checks with `--skip-module-health`.
 
 ```bash
 serenecode check src/ --structural          # structural conventions + dead-code review
@@ -192,8 +194,9 @@ The same `serenecode mcp` stdio server works in Claude Code, Cursor, Cline, Cont
 | `serenecode_integration_status` | Implementation/verification status of one INT |
 | `serenecode_orphans` | REQs with no implementation or no test |
 | `serenecode_dead_code` | Likely dead-code findings that require user review |
+| `serenecode_module_health` | Module health metrics (file size, function lengths, parameter counts, class sizes) for a single file — no verification needed |
 
-Tool results mirror the CLI pipeline: structured payloads include **`passed`**, levels, **`verdict`**, and a **summary** with counts (including **`advisory_count`** for dead-code-style exempt rows). Paths and `project_root` are resolved on the host — they are not sandboxed to one workspace; see [docs/SECURITY.md](docs/SECURITY.md).
+Tool results mirror the CLI pipeline: structured payloads include **`passed`**, levels, **`verdict`**, and a **summary** with counts (including **`advisory_count`** for advisory findings like dead code and module health warnings). Paths and `project_root` are resolved on the host — they are not sandboxed to one workspace; see [docs/SECURITY.md](docs/SECURITY.md).
 
 **Read-only resources** the agent can fetch without "calling" anything: `serenecode://config` (active SerenecodeConfig as JSON), `serenecode://findings/last-run` (most recent CheckResponse from this server session), `serenecode://exempt-modules` (the exempt path patterns for the active config), `serenecode://reqs` (parsed REQ-xxx list from the project's SPEC.md), and `serenecode://integrations` (parsed INT-xxx metadata from the project's SPEC.md).
 
@@ -274,13 +277,13 @@ The library API (`serenecode.check`) and the MCP server (`serenecode_check`, `se
 
 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:
+Those convention templates were the first artifacts — 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 (on the order of 1,400+ passing tests; a small number skipped by design)
+- `pytest` across the full suite (on the order of 1,450+ passing tests; a small number skipped by design)
 - `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 the full L1–L6 pipeline against the framework's own source; exact counts of passed / exempt / advisory rows change as the tree grows (wall time often several minutes for a deep run). A separate integration test, `test_serenecode_repo_passes_strict_level_6`, runs the same `src/` tree through `run_pipeline` with `strict_config()` and `start_level=4`, which strips path-based exemptions and forces adapters, CLI, MCP, and similar code through L4–L6. The exempt items in a **default-config** run still include adapter modules, port `Protocol`s, CLI/MCP composition roots, and functions whose parameter types are poor fits for Hypothesis/CrossHair. Exempt and advisory rows stay visible in the output — they are not silently omitted.
+On the current tree, `serenecode check src --level 6 --allow-code-execution` runs the full L1–L6 pipeline against the framework's own source; exact counts of passed / exempt / advisory rows change as the tree grows (wall time often several minutes for a deep run). A separate integration test, `test_serenecode_repo_passes_strict_level_6`, runs the same `src/` tree through `run_pipeline` with `strict_config()` and `start_level=4`, which strips path-based exemptions and forces adapters, CLI, MCP, and similar code through L4–L6. The exempt items in a **default-config** run still include adapter modules, port `Protocol`s, CLI/MCP composition roots, and functions whose parameter types are poor fits for Hypothesis/CrossHair. Advisory items include dead-code findings and module health warnings (file length, function length, parameter count, class method count). Exempt and advisory rows stay 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.
 
@@ -329,7 +332,8 @@ serenecode check [<path>] [--level 1-6] [--allow-code-execution]        # run ve
                           [--project-root DIR]                          #   repo root for imports + config
                           [--format human|json]                         #   output format
                           [--structural] [--verify]                     #   L1 only / L3-6 only
-                          [--fail-on-advisory]                         #   exit 11 if dead-code advisories remain
+                          [--skip-module-health]                        #   skip file/function/param/class size checks
+                          [--fail-on-advisory]                         #   exit 11 if advisories remain
                           [--per-condition-timeout N]                   #   L5 CrossHair budgets
                           [--per-path-timeout N] [--module-timeout N]   #   (defaults: 30/10/300s)
                           [--coverage-timeout N]                        #   L3 pytest/coverage subprocess (default 600s)
@@ -343,7 +347,7 @@ serenecode mcp [--allow-code-execution]                                 # boot t
 
 **Environment (optional):** `SERENECODE_MAX_WORKERS` overrides `--workers`; `SERENECODE_COVERAGE_TIMEOUT` overrides `--coverage-timeout`. **`SERENECODE_DEBUG=1`** logs subprocess environment **key names** (not values) when tools spawn mypy, pytest, CrossHair, etc. Details: [docs/SECURITY.md](docs/SECURITY.md).
 
-**Exit codes:** 0 = passed (and no `--fail-on-advisory` violation), 1–6 = first failing verification level (structural … compositional), 10 = internal error or deep verification refused without `--allow-code-execution`, **11 = dead-code advisories remain with `--fail-on-advisory`** (checks otherwise passed).
+**Exit codes:** 0 = passed (and no `--fail-on-advisory` violation), 1–6 = first failing verification level (structural … compositional), 10 = internal error or deep verification refused without `--allow-code-execution`, **11 = advisories remain with `--fail-on-advisory`** (dead code, module health warnings; checks otherwise passed).
 
 ---
 
@@ -355,7 +359,7 @@ SereneCode is honest about what it can and can't do:
 
 **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, MCP server, `__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.
+**Exempt items are visible, not hidden.** Modules exempt from structural checking (adapters, CLI, ports, MCP server, `__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. Advisory items (dead code, module health warnings) are also visible and counted separately. This makes the verification scope transparent: the tool reports passed, failed, skipped, exempt, and advisory counts separately so you can see exactly what was and wasn't deeply verified.
 
 **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.
 
@@ -383,6 +387,7 @@ CLI / Library API / MCP     ← composition roots (interactive init, spec valida
     │       ├──▸ Structural Checker    (ast)
     │       ├──▸ Spec Traceability     (REQ-xxx / INT-xxx → Implements/Verifies)
     │       ├──▸ Dead-Code Review      (likely unused code → ask before removal)
+    │       ├──▸ Module Health         (file/function/class size → advisory or error)
     │       ├──▸ Test Existence        (test_<module>.py discovery)
     │       ├──▸ Type Checker          (mypy)
     │       ├──▸ Coverage Analyzer     (coverage.py)
@@ -397,6 +402,16 @@ CLI / Library API / MCP     ← composition roots (interactive init, spec valida
 
 Core logic is pure. All I/O goes through Protocol-defined ports. The verification engine itself is verifiable.
 
+## Comparison: AWS Kiro and Spec Kit / Speckit
+
+SereneCode overlaps with these tools on **spec-first, AI-assisted development**—all three push against unstructured “vibe coding.” The difference is **what each product optimizes for**.
+
+**AWS Kiro** is an agentic AI IDE from AWS (Bedrock-powered), with spec-driven flows, autonomous agents, “powers,” and multi-repo work inside that environment. SereneCode is **not an IDE**: it is a **Python verification toolkit** (CLI + MCP) that plugs into editors you already use. Kiro optimizes **how you build in their stack**; SereneCode optimizes **repeatable assurance on Python code**—traceability from root `SPEC.md` IDs to implementation and tests, `icontract` contracts, mypy, coverage, Hypothesis, bounded CrossHair search, and compositional checks. The two are **complementary** if you use Kiro to author code but still want repo-local, machine-checkable verification on a Python tree.
+
+**Spec Kit** (GitHub’s methodology) and ecosystem tools such as **Speckit** focus on **structured specification and phased delivery**—for example constitution, specify, plan, tasks, and implementation—with agents and templates driving the workflow. “Executable” there often means **process and artifact structure** that steers implementation. SereneCode adds a different meaning of executable: **contracts and checkers that run against your Python**, plus optional solvers and property tests, with explicit **REQ-xxx / INT-xxx** traceability to `Implements:` / `Verifies:` in code and tests. Spec Kit is typically **stack-agnostic**; SereneCode is **Python-specific** by design.
+
+If you already use Spec Kit–style phases, SereneCode fits **after** the spec is stable enough to land as root `SPEC.md`—as the **verification layer** that answers whether the code and tests actually match what you declared.
+
 ## Security and trust
 
 Serenecode runs on **your machine** and, with `--allow-code-execution` (CLI or MCP), **imports and executes** project code—similar trust to running `pytest` or `python -m` on that tree. It is **not** a sandbox. Subprocesses receive a filtered environment to limit credential leakage; see [docs/SECURITY.md](docs/SECURITY.md) for the threat model, MCP behavior, `SERENECODE_DEBUG`, and CI exit code **11** with `--fail-on-advisory`.

serenecode-0.5.0/SPEC.md

@@ -0,0 +1,290 @@
+# Module Health Checks — Specification
+
+**Purpose:** Extend SereneCode with structural checks that detect overgrown files, functions, classes, and parameter lists — common AI coding agent failure modes — and provide actionable refactoring guidance.
+
+**Source:** Implementation plan derived from codebase exploration (2026-04-13).
+
+---
+
+## Configuration
+
+### REQ-001: ModuleHealthConfig dataclass
+
+A `ModuleHealthConfig` frozen dataclass with the following fields, all enforced by class invariants:
+
+- `enabled`: bool. When False, all module health checks are skipped.
+- `file_length_warn`: int, lines above which a file-length advisory is emitted. Must be > 0.
+- `file_length_error`: int, lines above which a file-length error is emitted. Must be > `file_length_warn`.
+- `function_length_warn`: int, body lines above which a function-length advisory is emitted. Must be > 0.
+- `function_length_error`: int, body lines above which a function-length error is emitted. Must be > `function_length_warn`.
+- `parameter_count_warn`: int, non-receiver parameters above which an advisory is emitted. Must be > 0.
+- `parameter_count_error`: int, non-receiver parameters above which an error is emitted. Must be > `parameter_count_warn`.
+- `class_method_count_warn`: int, methods above which a class-size advisory is emitted. Must be > 0.
+- `class_method_count_error`: int, methods above which a class-size error is emitted. Must be > `class_method_count_warn`.
+
+### REQ-002: ModuleHealthConfig added to SerenecodeConfig
+
+`SerenecodeConfig` gains a `module_health: ModuleHealthConfig` field. All existing composition roots (`default_config`, `strict_config`, `minimal_config`, `_apply_content_overrides`) must propagate this field.
+
+### REQ-003: Template-specific default thresholds
+
+Each template preset provides different thresholds:
+
+| Metric                | Default (warn / error) | Strict (warn / error) | Minimal (warn / error) |
+|-----------------------|------------------------|-----------------------|------------------------|
+| File length (lines)   | 500 / 1000             | 400 / 700             | 750 / 1500             |
+| Function length (lines) | 50 / 100             | 30 / 60               | 75 / 150               |
+| Parameter count       | 5 / 8                  | 4 / 6                 | 7 / 10                 |
+| Class method count    | 15 / 25                | 10 / 18               | 20 / 35                |
+
+---
+
+## Advisory Generalization
+
+### REQ-004: ADVISORY_FINDING_TYPES constant
+
+A module-level `frozenset[str]` in `models.py` enumerating all finding types that use the advisory pattern (EXEMPT status, visible in output, do not block verification unless `--fail-on-advisory`). Initial members: `"dead_code"`, `"file_length"`, `"function_length"`, `"parameter_count"`, `"class_method_count"`.
+
+### REQ-005: Generalized advisory counting in make_check_result
+
+`make_check_result()` must count advisory results by checking `detail.finding_type in ADVISORY_FINDING_TYPES` instead of hardcoding `"dead_code"`. The `advisory_count` field in `CheckSummary` must reflect all advisory types.
+
+### REQ-006: Generalized advisory display in reporter
+
+The human and HTML reporters must classify advisory results using `ADVISORY_FINDING_TYPES` membership instead of hardcoding `"dead_code"`. The summary label must read `"advisory"` (not `"advisory (dead code)"`).
+
+### REQ-007: Generalized advisory inclusion in MCP wire format
+
+The `to_check_response` projection in `schemas.py` must include EXEMPT results with any `finding_type in ADVISORY_FINDING_TYPES` in the wire findings, not only `"dead_code"`.
+
+---
+
+## File Length Check
+
+### REQ-008: File length check counts total lines
+
+`_check_file_length` counts lines as `len(source.splitlines())` for each source file. Test files (identified by `_is_test_file_path`) are excluded.
+
+### REQ-009: File length error when exceeding error threshold
+
+When line count exceeds `config.module_health.file_length_error`, a `FunctionResult` with `status=FAILED`, `function="<module>"`, `line=1`, `finding_type="file_length"` is emitted. The message must include the actual line count and the threshold.
+
+### REQ-010: File length advisory when exceeding warn threshold
+
+When line count exceeds `config.module_health.file_length_warn` but not the error threshold, a `FunctionResult` with `status=EXEMPT`, `finding_type="file_length"` is emitted (advisory pattern). The message must include the actual line count and both thresholds.
+
+### REQ-011: File length check runs on exempt modules
+
+Unlike structural policy checks, file length runs on all source files including modules exempt from contract/type checks. This is because exempt modules (adapters, CLI, MCP tools) are often the largest files.
+
+### REQ-012: File length suggestions are agent-actionable
+
+The `suggestion` field for file-length findings must include concrete refactoring strategies: extracting classes into standalone modules, grouping related functions by shared prefix or domain concept, and identifying comment-banner section boundaries.
+
+---
+
+## Function Length Check
+
+### REQ-013: Function length measured by line span
+
+`_check_function_length` measures each function's length as `node.end_lineno - node.lineno + 1` using AST `end_lineno`. Both `FunctionDef` and `AsyncFunctionDef` at module level and as class methods are checked.
+
+### REQ-014: Function length error when exceeding error threshold
+
+When function length exceeds `config.module_health.function_length_error`, a `FunctionResult` with `status=FAILED`, `function=node.name`, `finding_type="function_length"` is emitted.
+
+### REQ-015: Function length advisory when exceeding warn threshold
+
+When function length exceeds `config.module_health.function_length_warn` but not the error threshold, an advisory `FunctionResult` with `status=EXEMPT`, `finding_type="function_length"` is emitted.
+
+### REQ-016: Function length suggestions reference extraction patterns
+
+The suggestion must mention: extracting comment-delimited sections, pulling nested loops/conditionals into helpers, and converting setup/teardown into context managers.
+
+---
+
+## Parameter Count Check
+
+### REQ-017: Parameter count excludes self and cls
+
+`_check_parameter_count` counts non-receiver parameters (excluding `self`/`cls`) for each function. Both positional, keyword-only, `*args`, and `**kwargs` are counted.
+
+### REQ-018: Parameter count error when exceeding error threshold
+
+When parameter count exceeds `config.module_health.parameter_count_error`, a `FunctionResult` with `status=FAILED`, `finding_type="parameter_count"` is emitted.
+
+### REQ-019: Parameter count advisory when exceeding warn threshold
+
+When parameter count exceeds `config.module_health.parameter_count_warn` but not the error threshold, an advisory `FunctionResult` is emitted.
+
+### REQ-020: Parameter count suggestions reference Parameter Object pattern
+
+The suggestion must mention grouping related parameters into a dataclass, TypedDict, or config object using the Parameter Object pattern.
+
+---
+
+## Class Method Count Check
+
+### REQ-021: Class method count includes all def nodes in class body
+
+`_check_class_method_count` counts direct `FunctionDef` and `AsyncFunctionDef` children of each top-level `ClassDef` (not nested classes).
+
+### REQ-022: Class method count error when exceeding error threshold
+
+When method count exceeds `config.module_health.class_method_count_error`, a `FunctionResult` with `status=FAILED`, `function=class_name`, `finding_type="class_method_count"` is emitted.
+
+### REQ-023: Class method count advisory when exceeding warn threshold
+
+When method count exceeds `config.module_health.class_method_count_warn` but not the error threshold, an advisory `FunctionResult` is emitted.
+
+### REQ-024: Class method count suggestions reference SRP extraction
+
+The suggestion must mention: extracting cohesive groups of methods sharing a prefix, methods accessing a subset of attributes, and methods that could be standalone functions.
+
+---
+
+## Split Suggestions
+
+### REQ-025: AST-based split point identification
+
+A helper `_suggest_split_points` analyzes a file's AST and source to identify natural module boundaries:
+
+- Top-level classes with their line span and method count.
+- Groups of top-level functions sharing a common prefix (e.g., `parse_header`, `parse_body` -> `parse_*`).
+- Banner comments (lines matching patterns like `# --- Section ---` or `# ====`) that suggest logical boundaries.
+
+### REQ-026: Split suggestions included in file-length findings
+
+When file-length advisory or error findings are emitted, the suggestion field must include the output of `_suggest_split_points` formatted as a bullet list of concrete split candidates with line ranges.
+
+### REQ-027: Graceful fallback when no split points found
+
+If `_suggest_split_points` identifies no clear boundaries, the file-length finding falls back to the generic refactoring suggestion without split points.
+
+---
+
+## Pipeline Integration
+
+### REQ-028: Module health checks run in Level 1 pipeline block
+
+All four checks (`_check_file_length`, `_check_function_length`, `_check_parameter_count`, `_check_class_method_count`) are called within the Level 1 block of `run_pipeline`, after dead-code analysis. They are guarded by `config.module_health.enabled`.
+
+### REQ-029: Module health checks apply at all verification levels
+
+Since the checks are part of Level 1 and Level 1 runs for all levels 1-6 (unless `--verify` skips it), module health checks run by default at every verification level.
+
+### REQ-030: Module health check results participate in early termination
+
+If any module health check produces a FAILED result and `early_termination=True`, the pipeline stops at Level 1 (consistent with other Level 1 failures).
+
+---
+
+## CLI
+
+### REQ-031: --skip-module-health flag
+
+The `serenecode check` command accepts a `--skip-module-health` boolean flag. When set, `config.module_health.enabled` is overridden to `False` via `dataclasses.replace` before the pipeline runs.
+
+### REQ-032: --fail-on-advisory applies to module health advisories
+
+The existing `--fail-on-advisory` flag must trigger exit code 11 for any advisory, including module health warnings. The help text and exit message must not hardcode "dead-code."
+
+---
+
+## MCP Tool
+
+### REQ-033: serenecode_module_health tool returns file metrics
+
+A new MCP tool `tool_module_health(path: str)` reads a single Python file and returns a dict containing:
+
+- `file`: the file path.
+- `metrics`: `line_count`, `function_count`, `class_count`, `largest_function` (name, lines, line), `max_parameters` (name, count, line), `largest_class` (name, method_count, line).
+- `status`: per-metric status (`"ok"`, `"warning"`, `"error"`) derived from `ModuleHealthConfig` thresholds.
+- `split_suggestions`: output of `_suggest_split_points`.
+
+### REQ-034: serenecode_module_health does not run the verification pipeline
+
+The tool parses the AST and computes metrics directly, without calling `run_pipeline`. It does not require `--allow-code-execution`. It loads config via `_load_config` for threshold comparison.
+
+### REQ-035: serenecode_module_health registered in MCP server
+
+The tool is registered in `build_server()` with a description emphasizing proactive use during editing to monitor module structure.
+
+---
+
+## Templates
+
+### REQ-036: Module health documented in all templates
+
+Each template in `content.py` (default, strict, minimal) includes a "Module Health" subsection under Code Quality Standards documenting the four metrics, their warn/error thresholds, the advisory/error behavior, and the `--skip-module-health` flag.
+
+---
+
+## INT-001: Pipeline integration flow
+
+Kind: call
+Source: run_pipeline
+Target: check_file_length
+
+**Components:** `run_pipeline` (pipeline.py), `_check_file_length`, `_check_function_length`, `_check_parameter_count`, `_check_class_method_count`, `ModuleHealthConfig` (config.py)
+
+**Flow:**
+1. `run_pipeline` enters Level 1 block.
+2. After structural checks + dead-code analysis, checks `config.module_health.enabled`.
+3. If enabled, calls all four `_check_*` functions, passing `source_files` and `config`.
+4. Each function iterates source files, skips test files, parses AST as needed, applies thresholds.
+5. Results (FAILED or EXEMPT advisory) are appended to `level_1_results`.
+6. Early termination triggers if any FAILED result exists.
+
+**Contracts at boundary:** Each check function has icontract preconditions on inputs and postconditions ensuring returned list contains only valid `FunctionResult` objects.
+
+## INT-002: Advisory result propagation
+
+Kind: call
+Source: make_check_result
+Target: ADVISORY_FINDING_TYPES
+
+**Components:** `make_check_result` (models.py), `format_human` / `format_html` (reporter.py), `to_check_response` (schemas.py), `ADVISORY_FINDING_TYPES` (models.py)
+
+**Flow:**
+1. Module health checks emit `FunctionResult` with `status=EXEMPT` and `finding_type in ADVISORY_FINDING_TYPES`.
+2. `make_check_result` counts these as `advisory_count` via set membership check.
+3. Reporter classifies them as advisory (visible, distinct from plain exempt) via same set.
+4. MCP schemas include them in wire findings via same set.
+5. CLI `--fail-on-advisory` triggers exit 11 when `advisory_count > 0`.
+
+**Invariant:** `advisory_count` is always consistent across all three consumers because they share the single `ADVISORY_FINDING_TYPES` constant.
+
+## INT-003: CLI config override for --skip-module-health
+
+Kind: call
+Source: check
+Target: run_pipeline
+
+**Components:** `check` (cli.py), `SerenecodeConfig` (config.py), `ModuleHealthConfig` (config.py), `run_pipeline` (pipeline.py)
+
+**Flow:**
+1. CLI parses `--skip-module-health` flag.
+2. If set, uses `dataclasses.replace` to create a new `SerenecodeConfig` with `module_health.enabled=False`.
+3. Modified config is passed to `run_pipeline`.
+4. Pipeline checks `config.module_health.enabled` and skips all four check functions.
+
+**Postcondition:** When `--skip-module-health` is set, no `FunctionResult` with `finding_type in {"file_length", "function_length", "parameter_count", "class_method_count"}` appears in the output.
+
+## INT-004: MCP module_health tool standalone analysis
+
+Kind: call
+Source: tool_module_health
+Target: _load_config
+
+**Components:** `tool_module_health` (tools.py), `_load_config` (tools.py), `_suggest_split_points` (pipeline.py), `ModuleHealthConfig` (config.py)
+
+**Flow:**
+1. Tool receives file path, reads source via `LocalFileReader`.
+2. Loads config via `_load_config` (cached, mtime-aware).
+3. Parses AST, computes metrics (line count, function sizes, parameter counts, class sizes).
+4. Compares each metric against `ModuleHealthConfig` thresholds to derive status.
+5. Calls `_suggest_split_points` on source + AST for split candidates.
+6. Returns structured dict with metrics, status, and suggestions.
+
+**Postcondition:** Response always contains all metric fields even when file is empty or has no functions/classes (values are 0 / empty).

{serenecode-0.4.0 → serenecode-0.5.0}/docs/VERIFICATION_LEVELS.md

@@ -19,11 +19,11 @@ SereneCode checks stack from fast structural rules (Level 1) through types, cove
 
 ## Spec ergonomics
 
-- **Narrative vs traceability:** PRDs, `README` sections, and `*_SPEC.md` files are inputs. REQ/INT traceability and `serenecode check --spec` apply only to project-root **SPEC.md**, which must include a `**Source:** …` line (see SERENECODE.md). Run `serenecode doctor` to see whether SPEC.md and narrative-looking files were detected at the project root.
+- **Narrative vs traceability:** PRDs, `README` sections, and `*_SPEC.md` files are inputs. REQ/INT traceability and `serenecode check --spec` apply only to project-root **SPEC.md**, which must include a `**Source:** …` line (see the Spec Traceability section in your project's `SERENECODE.md` from `serenecode init`, or the embedded templates in `src/serenecode/templates/content.py`). Run `serenecode doctor` to see whether SPEC.md and narrative-looking files were detected at the project root.
 - Use **one primary target per comma segment**; avoid stuffing unrelated names into a single `Target` line unless you intend AND semantics.
 - Align **dotted names** with how types appear in code (`from pkg import X as Y` is easier to reason about when `Target` uses the same simple name the implementation calls).
 
 ## Related reading
 
 - [SECURITY.md](SECURITY.md) — trust model for `--allow-code-execution` (required for Levels 3–6 as implemented today).
-- Project `SERENECODE.md` — conventions the structural checker enforces.
+- Your project's `SERENECODE.md` (from `serenecode init`) — conventions the structural checker enforces; source templates live in `src/serenecode/templates/content.py`.

{serenecode-0.4.0 → serenecode-0.5.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "serenecode"
-version = "0.4.0"
+version = "0.5.0"
 description = "Verification framework for AI-generated Python — test coverage, property testing, and symbolic execution"
 requires-python = ">=3.10"
 license = "MIT"