kragg 0.3.0__tar.gz

kragg-0.3.0/.gitignore

@@ -0,0 +1,28 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+
+# tooling
+.pytest_cache/
+.coverage
+htmlcov/
+.mypy_cache/
+.ruff_cache/
+.hypothesis/
+
+# env
+.env
+.env.*
+!.env.example
+
+# OS
+.DS_Store
+
+# kragg local artifacts (journal, coverage, criticality, mutation sessions)
+.kragg/*
+# ...but the reviewed equivalent-mutant baseline is meant to be committed
+!.kragg/mutants.baseline

kragg-0.3.0/.kragg/mutants.baseline

@@ -0,0 +1,65 @@
+[
+ "src/kragg/changes.py::core/ExceptionReplacer::0",
+ "src/kragg/changes.py::core/ReplaceComparisonOperator_Eq_Gt::0",
+ "src/kragg/changes.py::core/ReplaceComparisonOperator_Eq_GtE::0",
+ "src/kragg/changes.py::core/ReplaceComparisonOperator_Eq_Is::0",
+ "src/kragg/critical.py::core/NumberReplacer::3",
+ "src/kragg/critical.py::core/NumberReplacer::4",
+ "src/kragg/critical.py::core/NumberReplacer::5",
+ "src/kragg/critical.py::core/ReplaceBinaryOperator_Sub_Add::0",
+ "src/kragg/critical.py::core/ReplaceBinaryOperator_Sub_BitOr::0",
+ "src/kragg/critical.py::core/ReplaceBinaryOperator_Sub_BitXor::0",
+ "src/kragg/critical.py::core/ReplaceBinaryOperator_Sub_FloorDiv::0",
+ "src/kragg/critical.py::core/ReplaceBinaryOperator_Sub_LShift::0",
+ "src/kragg/critical.py::core/ReplaceBinaryOperator_Sub_Mul::0",
+ "src/kragg/critical.py::core/ReplaceBinaryOperator_Sub_Pow::0",
+ "src/kragg/critical.py::core/ReplaceTrueWithFalse::0",
+ "src/kragg/report.py::core/ExceptionReplacer::0",
+ "src/kragg/report.py::core/NumberReplacer::10",
+ "src/kragg/report.py::core/NumberReplacer::11",
+ "src/kragg/report.py::core/NumberReplacer::12",
+ "src/kragg/report.py::core/NumberReplacer::13",
+ "src/kragg/report.py::core/NumberReplacer::14",
+ "src/kragg/report.py::core/NumberReplacer::15",
+ "src/kragg/report.py::core/NumberReplacer::17",
+ "src/kragg/report.py::core/NumberReplacer::30",
+ "src/kragg/report.py::core/NumberReplacer::31",
+ "src/kragg/report.py::core/NumberReplacer::32",
+ "src/kragg/report.py::core/NumberReplacer::33",
+ "src/kragg/report.py::core/ReplaceAndWithOr::0",
+ "src/kragg/report.py::core/ReplaceAndWithOr::1",
+ "src/kragg/report.py::core/ReplaceAndWithOr::2",
+ "src/kragg/report.py::core/ReplaceAndWithOr::5",
+ "src/kragg/report.py::core/ReplaceBinaryOperator_Div_Add::0",
+ "src/kragg/report.py::core/ReplaceBinaryOperator_Div_BitAnd::0",
+ "src/kragg/report.py::core/ReplaceBinaryOperator_Div_BitOr::0",
+ "src/kragg/report.py::core/ReplaceBinaryOperator_Div_BitXor::0",
+ "src/kragg/report.py::core/ReplaceBinaryOperator_Div_FloorDiv::0",
+ "src/kragg/report.py::core/ReplaceBinaryOperator_Div_LShift::0",
+ "src/kragg/report.py::core/ReplaceBinaryOperator_Div_Mod::0",
+ "src/kragg/report.py::core/ReplaceBinaryOperator_Div_Mul::0",
+ "src/kragg/report.py::core/ReplaceBinaryOperator_Div_Pow::0",
+ "src/kragg/report.py::core/ReplaceBinaryOperator_Div_RShift::0",
+ "src/kragg/report.py::core/ReplaceBinaryOperator_Div_Sub::0",
+ "src/kragg/report.py::core/ReplaceBinaryOperator_Sub_RShift::2",
+ "src/kragg/report.py::core/ReplaceComparisonOperator_Eq_LtE::0",
+ "src/kragg/report.py::core/ReplaceComparisonOperator_Gt_Eq::1",
+ "src/kragg/report.py::core/ReplaceComparisonOperator_Gt_GtE::0",
+ "src/kragg/report.py::core/ReplaceComparisonOperator_Gt_GtE::1",
+ "src/kragg/report.py::core/ReplaceComparisonOperator_Gt_Is::1",
+ "src/kragg/report.py::core/ReplaceComparisonOperator_Gt_IsNot::0",
+ "src/kragg/report.py::core/ReplaceComparisonOperator_Gt_NotEq::0",
+ "src/kragg/report.py::core/ReplaceComparisonOperator_Lt_IsNot::0",
+ "src/kragg/report.py::core/ReplaceComparisonOperator_Lt_LtE::0",
+ "src/kragg/report.py::core/ReplaceComparisonOperator_Lt_NotEq::0",
+ "src/kragg/report.py::core/ReplaceTrueWithFalse::0",
+ "src/kragg/report.py::core/ReplaceTrueWithFalse::1",
+ "src/kragg/report.py::core/ReplaceUnaryOperator_Delete_USub::0",
+ "src/kragg/report.py::core/ReplaceUnaryOperator_Delete_USub::1",
+ "src/kragg/report.py::core/ReplaceUnaryOperator_USub_Invert::0",
+ "src/kragg/report.py::core/ReplaceUnaryOperator_USub_Invert::1",
+ "src/kragg/report.py::core/ReplaceUnaryOperator_USub_Not::0",
+ "src/kragg/report.py::core/ReplaceUnaryOperator_USub_Not::1",
+ "src/kragg/report.py::core/ReplaceUnaryOperator_USub_UAdd::0",
+ "src/kragg/report.py::core/ReplaceUnaryOperator_USub_UAdd::1"
+]

kragg-0.3.0/.python-version

@@ -0,0 +1 @@
+3.12

kragg-0.3.0/AGENTS.md

@@ -0,0 +1,134 @@
+# AGENTS.md
+
+## Mission
+
+This repository builds `kragg`, an opinionated Python guardrails framework and CLI for AI-assisted Python projects. Optimize changes for correctness, safety, and minimal disruption to the public CLI/package behavior.
+
+## Priority Order
+
+When tradeoffs conflict, use this order:
+
+1. Correctness.
+2. Data safety.
+3. Minimal diff.
+4. Existing project conventions.
+5. Performance.
+6. Elegance.
+
+Do not optimize for elegance by expanding scope. Do not optimize for performance unless the task is performance-related or a measured bottleneck exists.
+
+## Operating Rules
+
+- Do exactly what the user asked.
+- Prefer small, local changes.
+- Prefer modifying existing functions over adding helper layers when the change is local.
+- Preserve existing architecture unless explicitly asked to change it.
+- Read nearby code before editing.
+- Match existing naming, structure, typing, and error-handling patterns.
+- Do not refactor unrelated code.
+- Do not rewrite unrelated files.
+- Do not reformat untouched files.
+- Preserve public APIs and CLI behavior unless the task explicitly requires changing them.
+- Do not introduce new abstractions unless they remove duplicated behavior in the changed files.
+- Do not introduce new dependencies without explicit user approval.
+- When blocked, report the blocker and propose the smallest next step.
+
+## Project Map
+
+- `src/kragg/cli.py`: CLI argument parsing and dispatch.
+- `src/kragg/commands.py`: command handlers behind each subcommand.
+- `src/kragg/scaffold.py`: generated project files and initialization logic.
+- `src/kragg/gates/`: built-in guardrail checks for complexity, type/architecture constraints, secrets, criticality, and test quality/coverage.
+- `src/kragg/policy.py`: `kragg.toml` / `[tool.kragg]` policy loading and defaults.
+- `src/kragg/models.py`: shared result/context data types.
+- `src/kragg/runner.py`: external command execution wrapper.
+- `src/kragg/environment.py`: project-interpreter resolution for environment-dependent tools (pytest, mypy, pip-audit, deptry).
+- `src/kragg/check.py`: gate pipeline engine (GateSpec, run_gates, fast/slow tiers).
+- `src/kragg/catalog.py`: assembles the concrete check/security pipelines from the gates.
+- `src/kragg/parsers.py`: tool output parsers producing structured violations.
+- `src/kragg/report.py`: consolidated reports, JSON schema, text rendering, exit codes.
+- `src/kragg/critical.py`: resolves public critical functions to source file + coverage key; shared by coverage and mutation surfaces.
+- `src/kragg/coverage.py`: reads coverage.py JSON, surfaces criticality-ranked coverage gaps (`kragg coverage`).
+- `src/kragg/mutation.py`: targeted mutation testing via cosmic-ray over changed critical files (`kragg mutation`).
+- `src/kragg/spec.py`: extracts the test suite's name/docstring tree and flags critical functions lacking property-based tests (`kragg spec`).
+- `src/kragg/changes.py`: git-based changed-file detection plus HEAD sha and dirty-tree metadata.
+- `src/kragg/flaky.py`: flaky detection — passive journal mining and active suite reruns (`kragg flaky [--rerun N]`).
+- `src/kragg/journal.py`: `.kragg/history.jsonl` run journal backing `kragg status`.
+- `src/kragg/hooks.py`: harness hook adapters (`kragg hook claude`).
+- `src/kragg/mapping.py`: public-symbol inventory backing `kragg map`.
+- `src/kragg/brief.py`: reviewable change digest backing `kragg brief`.
+- `src/kragg/templates.py`: generated source for project kinds and `kragg gen module`.
+- `tests/`: focused unit and CLI tests.
+- `pyproject.toml`: package metadata, CLI entry point, dependencies, and tool configuration.
+
+Update this section when the repo structure changes.
+
+## Commands
+
+- Install: `uv sync`
+- Run CLI: `uv run kragg --help`
+- Test: `uv run pytest`
+- Typecheck: `uv run mypy src tests`
+- Lint: `uv run ruff check src tests`
+- Format check: `uv run ruff format --check src tests`
+- Format: `uv run ruff format src tests`
+- Focused guardrail check: `uv run kragg check --file <path>`
+- Coverage gaps / spec / flaky: `uv run kragg coverage`, `uv run kragg spec`, `uv run kragg flaky`
+- Mutation test (on-demand, slow; needs cosmic-ray): `uv run kragg mutation --all`
+
+Use the narrowest relevant command first. Run broader validation before claiming completion when practical.
+
+## Code Standards
+
+- Python target is 3.12.
+- Keep strict typing clean; do not weaken types to silence errors.
+- Prefer explicit return types at module boundaries and public functions.
+- Prefer existing utilities over new abstractions.
+- Keep functions small, but do not split code just for aesthetics.
+- Handle errors explicitly. Do not hide failures.
+- Keep generated scaffold content readable and minimal.
+- Use Mermaid only for execution flow, ownership boundaries, or data flow, and keep diagrams small.
+
+## Testing Rules
+
+- Add or update tests for changed behavior.
+- Prefer focused tests near the changed code.
+- Run the narrowest relevant test first.
+- Run `uv run pytest`, `uv run ruff check src tests`, and `uv run mypy src tests` before claiming completion when practical.
+- Do not delete failing tests unless they are obsolete and the reason is explained.
+- If tests cannot be run, state exactly why.
+
+## Stop Conditions
+
+Stop and ask before:
+
+- adding a production dependency,
+- changing public CLI commands or importable public APIs,
+- changing generated CI, deployment, or secrets handling,
+- changing authentication or authorization behavior,
+- changing billing or payment behavior,
+- changing database schema or migrations,
+- deleting data,
+- making broad architectural changes,
+- replacing working code with a new pattern just because it is cleaner.
+
+Before changing database schema in any future project that has one, inspect existing migrations and update tests. After changing API behavior in any future API layer, update or add request/response tests.
+
+## Do Not
+
+- Do not rewrite unrelated files.
+- Do not rename symbols for style only.
+- Do not reformat untouched files.
+- Do not weaken types to silence errors.
+- Do not add caching, retries, queues, or concurrency unless requested.
+- Do not replace working code with a new pattern just because it is cleaner.
+- Do not claim success without validation.
+
+## Definition of Done
+
+A task is complete when:
+
+- the requested behavior is implemented,
+- relevant tests are added or updated,
+- validation commands have been run when practical,
+- the final response lists changed files, validation results, and any remaining risks.

kragg-0.3.0/CRITICALITY.md

@@ -0,0 +1,37 @@
+# Critical Functions
+
+> Auto-generated by `kragg criticality --write`. Do not edit by hand.
+
+Functions marked critical have high fan-in or betweenness centrality.
+When editing them, full types, docstrings, and tests are mandatory.
+
+## Critical
+
+| Function | Fan-in | Fan-out | Centrality | Risk |
+| --- | ---: | ---: | ---: | --- |
+| `kragg.critical.critical_functions` | 3 | 4 | 0.0011 | MED |
+| `kragg.policy.load_policy` | 17 | 5 | 0.0010 | HIGH |
+| `kragg.report.to_payload` | 3 | 5 | 0.0006 | MED |
+| `kragg.changes.changed_python_files` | 4 | 4 | 0.0006 | MED |
+
+## Non-critical
+
+| Function | Fan-in | Fan-out | Centrality | Risk |
+| --- | ---: | ---: | ---: | --- |
+| `kragg.catalog.build_check_gates` | 2 | 15 | 0.0053 | low |
+| `kragg.hooks._run_check` | 2 | 9 | 0.0050 | low |
+| `kragg.hooks._dispatch` | 1 | 4 | 0.0027 | low |
+| `kragg.hooks._post_edit` | 1 | 4 | 0.0018 | low |
+| `kragg.hooks._stop` | 1 | 4 | 0.0018 | low |
+| `kragg.coverage.critical_gaps` | 2 | 4 | 0.0015 | low |
+| `kragg.hooks.run_claude_hook` | 1 | 1 | 0.0014 | low |
+| `kragg.gates.critical_coverage.check_critical_coverage` | 1 | 2 | 0.0014 | low |
+| `kragg.catalog._critical_coverage_gate` | 1 | 2 | 0.0013 | low |
+| `kragg.gates.critical_tests.check_critical_tests` | 1 | 4 | 0.0007 | low |
+| `kragg.catalog._project_tool_gate` | 2 | 8 | 0.0007 | low |
+| `kragg.gates.test_quality.check_tests` | 1 | 3 | 0.0006 | low |
+| `kragg.catalog._test_quality_gate` | 1 | 2 | 0.0006 | low |
+| `kragg.catalog._critical_tests_gate` | 1 | 2 | 0.0006 | low |
+| `kragg.gates.criticality.build_call_graph` | 1 | 4 | 0.0006 | low |
+| `kragg.commands._run_pipeline` | 2 | 8 | 0.0006 | low |
+

kragg-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Torta Studios, LLC (tortastudios.com)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

kragg-0.3.0/PKG-INFO

@@ -0,0 +1,189 @@
+Metadata-Version: 2.4
+Name: kragg
+Version: 0.3.0
+Summary: Agent-first guardrails framework for AI-assisted Python projects
+Project-URL: Homepage, https://tortastudios.com
+Project-URL: Repository, https://github.com/tortastudios/kragg
+Project-URL: Issues, https://github.com/tortastudios/kragg/issues
+Author-email: "Torta Studios, LLC" <tech@tortastudios.com>
+Maintainer-email: "Torta Studios, LLC" <tech@tortastudios.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,ai,claude-code,code-quality,guardrails,linting,scaffolding
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Code Generators
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: bandit>=1.8.3
+Requires-Dist: deptry>=0.24.0
+Requires-Dist: detect-secrets>=1.5.0
+Requires-Dist: mypy>=1.19.1
+Requires-Dist: networkx>=3.4.2
+Requires-Dist: pip-audit>=2.9.0
+Requires-Dist: pytest-cov>=7.0.0
+Requires-Dist: pytest>=9.0.2
+Requires-Dist: radon>=6.0.1
+Requires-Dist: ruff>=0.15.5
+Requires-Dist: vulture>=2.15
+Description-Content-Type: text/markdown
+
+# kragg
+
+`kragg` is an opinionated guardrails framework for AI-assisted Python projects.
+It is agent-first: coding agents (Claude Code, Codex, Cursor, Gemini CLI, …)
+are the primary users, running check → fix loops. kragg gives them one command,
+structured results, meaningful exit codes, and copy-pasteable fixes.
+
+## Install modes
+
+**Dev dependency (recommended).** kragg runs inside the project environment, so
+every tool sees the project's packages:
+
+```bash
+uv add --dev kragg
+uv run kragg check
+```
+
+**Global tool (pipx / uv tool).** kragg runs from its own environment, but
+environment-dependent gates (pytest, mypy, pip-audit, deptry) are always
+executed on the *project's* interpreter, resolved in this order:
+
+1. `KRAGG_PROJECT_PYTHON` environment variable (explicit override)
+2. `<project>/.venv`
+3. an active `VIRTUAL_ENV` (ignored when it is kragg's own environment)
+4. `uv run --project <project>` as a fallback
+
+If no project environment exists, those gates fail loudly with the exact fix
+(`uv sync`, `uv add --dev mypy`, …) instead of silently running in the wrong
+environment. `kragg doctor` shows which interpreter was resolved and which
+tools are missing.
+
+## Commands
+
+```bash
+kragg new my-app --kind cli   # layered skeleton (cli | api | worker) + uv sync
+kragg gen module payments     # service/domain/test slots in the layout
+kragg init .                  # add guardrails to an existing project
+kragg check                   # all gates, consolidated report
+kragg check --changed         # only files changed in git (cheap inner loop)
+kragg check --since main      # changed vs merge-base with a ref
+kragg check --file src/foo.py --file src/bar.py
+kragg check --format json     # stable machine-readable schema
+kragg fix                     # auto-fix formatting and safe lint
+kragg map                     # public symbol inventory (what already exists)
+kragg spec                    # test suite rendered as a readable spec tree
+kragg coverage                # uncovered lines in critical functions (ranked)
+kragg mutation                # mutation-test changed critical files (cosmic-ray)
+kragg mutation --all          # mutation-test every critical file
+kragg mutation --update-baseline  # accept current survivors (equivalent mutants)
+kragg brief                   # reviewable digest of the change set
+kragg security
+kragg audit
+kragg criticality --write     # call-graph risk -> CRITICALITY.md + .kragg/
+kragg status                  # what failed last run, without re-running
+kragg flaky                   # gates that flipped pass/fail on an unchanged commit
+kragg flaky --rerun 20        # re-run the suite N times, rank tests by failure ratio
+kragg hook claude             # harness hook adapter (reads hook JSON on stdin)
+kragg doctor                  # environment diagnostics with exact fixes
+kragg policy show
+```
+
+## Gates
+
+Fast (always all run): ruff, mypy, radon-cc, radon-mi, halstead,
+type-complexity, **boundaries** (layered import contract from
+`[tool.kragg] layers`), **structure** (file/symbol budgets),
+**critical-tests** (critical functions cannot change without test changes),
+**test-quality** (no assertion-free tests; critical functions must be
+referenced by tests), bandit, detect-secrets.
+Slow (skipped while fast gates fail): pytest+coverage, **critical-coverage**
+(public critical functions must have no uncovered lines), pip-audit.
+
+## Test depth
+
+Green checkmarks are easy to fake, so kragg looks past them with layered,
+mostly-deterministic signals — each a harder-to-game answer to "do the tests
+actually defend behavior":
+
+- **what's run** — `kragg coverage` surfaces uncovered lines in critical
+  functions, ranked by fan-in, instead of a gameable global percentage; the
+  `critical-coverage` gate fails on any uncovered line in a critical function.
+- **what's defended** — `kragg mutation` runs cosmic-ray over the changed
+  critical files (the criticality graph and git diff keep it cheap) and reports
+  surviving mutants as `file:line` fixes. Accept equivalent mutants with
+  `kragg mutation --update-baseline`.
+- **what's claimed** — `kragg spec` renders test names and docstrings as a
+  documentation tree and flags critical functions that have only example-based
+  tests (property-based tests, via Hypothesis, kill more mutants).
+- **what's trustworthy** — `kragg flaky` mines the run journal for gates that
+  flipped on an unchanged commit; `--rerun N` re-runs the suite and ranks tests
+  by failure ratio (for cron/CI, never the inner loop).
+
+Mutation and active flaky runs are deliberately outside `kragg check`: they are
+on-demand or CI surfaces, not inner-loop gates.
+
+`kragg mutation` runs cosmic-ray on the project interpreter, so add it to the
+project being checked (`uv add --dev cosmic-ray`); kragg prints the exact
+command if it is missing. Property-based tests use Hypothesis
+(`uv add --dev hypothesis`). Mutation needs an editable/source install so it
+mutates the code the tests import.
+
+## Agent-native design
+
+Agents drift where they have freedom, so the scaffold removes the freedom:
+every kind ships one layered layout (`entrypoints/` → `services/` →
+`domain/`) with the `boundaries` gate enforcing dependency direction from
+the first commit, and `kragg gen module` creates new code in the one place
+it belongs. The tool holds the memory the agent lacks: `kragg map` is the
+inventory of what exists (injected at session start so nothing gets
+reinvented), `.kragg/history.jsonl` remembers runs, `CRITICALITY.md`
+remembers risk, and `kragg brief` renders the change set legible to the
+human reviewer.
+
+## Agent loop design
+
+- `kragg check` runs **all static gates** and reports every failure in one run
+  (one loop iteration instead of one per gate). Slow gates (pytest, pip-audit)
+  are skipped while static gates fail; `--fail-fast` and `--all` override.
+- Output is token-efficient: violations are deduplicated, capped per gate
+  (`--max-violations`, policy `max_violations_per_gate`), and reported as
+  `file:line` pointers with fix hints instead of raw tool dumps.
+- Exit codes are branchable without parsing: `0` pass, `1` gate failures,
+  `2` usage error, `3` environment broken.
+- Every run appends a slim line to `.kragg/history.jsonl`; `kragg status` answers
+  "what failed last run" for a few tokens.
+- Scaffolding emits `AGENTS.md` as the canonical agent contract (read by
+  Codex, Cursor, Gemini CLI, and Claude Code via a `CLAUDE.md` pointer), plus
+  hooks that run `kragg check --changed` after edits.
+
+## Configuration
+
+Configure kragg in `pyproject.toml` under `[tool.kragg]`, or in a standalone
+`kragg.toml` (top-level keys, takes precedence when present):
+
+```toml
+[tool.kragg]
+profile = "strict-ai-python"
+source_paths = ["src"]
+test_paths = ["tests"]
+coverage_fail_under = 80
+type_max_nesting_depth = 2
+type_max_length = 40
+max_violations_per_gate = 25
+```
+
+## V1 scope
+
+`kragg` models agentic workflow support as policy packs, not as an LLM runtime.
+A policy pack defines the gates, thresholds, generated agent instructions, and
+project wrappers that keep AI-authored Python code inside known constraints.
+
+The default policy pack is `strict-ai-python`.

kragg-0.3.0/README.md

@@ -0,0 +1,152 @@
+# kragg
+
+`kragg` is an opinionated guardrails framework for AI-assisted Python projects.
+It is agent-first: coding agents (Claude Code, Codex, Cursor, Gemini CLI, …)
+are the primary users, running check → fix loops. kragg gives them one command,
+structured results, meaningful exit codes, and copy-pasteable fixes.
+
+## Install modes
+
+**Dev dependency (recommended).** kragg runs inside the project environment, so
+every tool sees the project's packages:
+
+```bash
+uv add --dev kragg
+uv run kragg check
+```
+
+**Global tool (pipx / uv tool).** kragg runs from its own environment, but
+environment-dependent gates (pytest, mypy, pip-audit, deptry) are always
+executed on the *project's* interpreter, resolved in this order:
+
+1. `KRAGG_PROJECT_PYTHON` environment variable (explicit override)
+2. `<project>/.venv`
+3. an active `VIRTUAL_ENV` (ignored when it is kragg's own environment)
+4. `uv run --project <project>` as a fallback
+
+If no project environment exists, those gates fail loudly with the exact fix
+(`uv sync`, `uv add --dev mypy`, …) instead of silently running in the wrong
+environment. `kragg doctor` shows which interpreter was resolved and which
+tools are missing.
+
+## Commands
+
+```bash
+kragg new my-app --kind cli   # layered skeleton (cli | api | worker) + uv sync
+kragg gen module payments     # service/domain/test slots in the layout
+kragg init .                  # add guardrails to an existing project
+kragg check                   # all gates, consolidated report
+kragg check --changed         # only files changed in git (cheap inner loop)
+kragg check --since main      # changed vs merge-base with a ref
+kragg check --file src/foo.py --file src/bar.py
+kragg check --format json     # stable machine-readable schema
+kragg fix                     # auto-fix formatting and safe lint
+kragg map                     # public symbol inventory (what already exists)
+kragg spec                    # test suite rendered as a readable spec tree
+kragg coverage                # uncovered lines in critical functions (ranked)
+kragg mutation                # mutation-test changed critical files (cosmic-ray)
+kragg mutation --all          # mutation-test every critical file
+kragg mutation --update-baseline  # accept current survivors (equivalent mutants)
+kragg brief                   # reviewable digest of the change set
+kragg security
+kragg audit
+kragg criticality --write     # call-graph risk -> CRITICALITY.md + .kragg/
+kragg status                  # what failed last run, without re-running
+kragg flaky                   # gates that flipped pass/fail on an unchanged commit
+kragg flaky --rerun 20        # re-run the suite N times, rank tests by failure ratio
+kragg hook claude             # harness hook adapter (reads hook JSON on stdin)
+kragg doctor                  # environment diagnostics with exact fixes
+kragg policy show
+```
+
+## Gates
+
+Fast (always all run): ruff, mypy, radon-cc, radon-mi, halstead,
+type-complexity, **boundaries** (layered import contract from
+`[tool.kragg] layers`), **structure** (file/symbol budgets),
+**critical-tests** (critical functions cannot change without test changes),
+**test-quality** (no assertion-free tests; critical functions must be
+referenced by tests), bandit, detect-secrets.
+Slow (skipped while fast gates fail): pytest+coverage, **critical-coverage**
+(public critical functions must have no uncovered lines), pip-audit.
+
+## Test depth
+
+Green checkmarks are easy to fake, so kragg looks past them with layered,
+mostly-deterministic signals — each a harder-to-game answer to "do the tests
+actually defend behavior":
+
+- **what's run** — `kragg coverage` surfaces uncovered lines in critical
+  functions, ranked by fan-in, instead of a gameable global percentage; the
+  `critical-coverage` gate fails on any uncovered line in a critical function.
+- **what's defended** — `kragg mutation` runs cosmic-ray over the changed
+  critical files (the criticality graph and git diff keep it cheap) and reports
+  surviving mutants as `file:line` fixes. Accept equivalent mutants with
+  `kragg mutation --update-baseline`.
+- **what's claimed** — `kragg spec` renders test names and docstrings as a
+  documentation tree and flags critical functions that have only example-based
+  tests (property-based tests, via Hypothesis, kill more mutants).
+- **what's trustworthy** — `kragg flaky` mines the run journal for gates that
+  flipped on an unchanged commit; `--rerun N` re-runs the suite and ranks tests
+  by failure ratio (for cron/CI, never the inner loop).
+
+Mutation and active flaky runs are deliberately outside `kragg check`: they are
+on-demand or CI surfaces, not inner-loop gates.
+
+`kragg mutation` runs cosmic-ray on the project interpreter, so add it to the
+project being checked (`uv add --dev cosmic-ray`); kragg prints the exact
+command if it is missing. Property-based tests use Hypothesis
+(`uv add --dev hypothesis`). Mutation needs an editable/source install so it
+mutates the code the tests import.
+
+## Agent-native design
+
+Agents drift where they have freedom, so the scaffold removes the freedom:
+every kind ships one layered layout (`entrypoints/` → `services/` →
+`domain/`) with the `boundaries` gate enforcing dependency direction from
+the first commit, and `kragg gen module` creates new code in the one place
+it belongs. The tool holds the memory the agent lacks: `kragg map` is the
+inventory of what exists (injected at session start so nothing gets
+reinvented), `.kragg/history.jsonl` remembers runs, `CRITICALITY.md`
+remembers risk, and `kragg brief` renders the change set legible to the
+human reviewer.
+
+## Agent loop design
+
+- `kragg check` runs **all static gates** and reports every failure in one run
+  (one loop iteration instead of one per gate). Slow gates (pytest, pip-audit)
+  are skipped while static gates fail; `--fail-fast` and `--all` override.
+- Output is token-efficient: violations are deduplicated, capped per gate
+  (`--max-violations`, policy `max_violations_per_gate`), and reported as
+  `file:line` pointers with fix hints instead of raw tool dumps.
+- Exit codes are branchable without parsing: `0` pass, `1` gate failures,
+  `2` usage error, `3` environment broken.
+- Every run appends a slim line to `.kragg/history.jsonl`; `kragg status` answers
+  "what failed last run" for a few tokens.
+- Scaffolding emits `AGENTS.md` as the canonical agent contract (read by
+  Codex, Cursor, Gemini CLI, and Claude Code via a `CLAUDE.md` pointer), plus
+  hooks that run `kragg check --changed` after edits.
+
+## Configuration
+
+Configure kragg in `pyproject.toml` under `[tool.kragg]`, or in a standalone
+`kragg.toml` (top-level keys, takes precedence when present):
+
+```toml
+[tool.kragg]
+profile = "strict-ai-python"
+source_paths = ["src"]
+test_paths = ["tests"]
+coverage_fail_under = 80
+type_max_nesting_depth = 2
+type_max_length = 40
+max_violations_per_gate = 25
+```
+
+## V1 scope
+
+`kragg` models agentic workflow support as policy packs, not as an LLM runtime.
+A policy pack defines the gates, thresholds, generated agent instructions, and
+project wrappers that keep AI-authored Python code inside known constraints.
+
+The default policy pack is `strict-ai-python`.