constraintloop 0.1.0__tar.gz → 0.3.0__tar.gz

{constraintloop-0.1.0 → constraintloop-0.3.0}/.gitignore

@@ -14,3 +14,5 @@ build/
 dist/
 *.egg-info/
 .constraintloop/
+constraintloop.local.yml
+constraintloop.local.yaml

constraintloop-0.3.0/CHANGELOG.md

@@ -0,0 +1,59 @@
+# Changelog
+
+All notable changes are documented here. The project follows Semantic
+Versioning, with the usual initial-development flexibility for `0.y.z`.
+
+## [Unreleased]
+
+## [0.3.0] - 2026-08-18
+
+- Add native monotonic ratchet constraints with committed JSON baselines,
+  strengthening-only baseline updates by default, and explicit intentional
+  regression overrides.
+- Preserve selected fields from JSON report artifacts as structured evidence
+  and show metric values, baselines, and changes in run and status output.
+- Add `constraintloop explain` for phase eligibility, matched and changed watch
+  paths, cache state, and complete dependency chains.
+- Diagnose missing worktree environment files, virtual environments, container
+  runtimes, Docker daemons, and ratchet baselines in `doctor --deep`.
+- Publish a generated JSON Schema for YAML editor validation and autocomplete.
+- Classify genuine constraint failures separately from environmental and
+  startup failures in human-readable summaries and JSON evidence.
+
+## [0.2.0] - 2026-08-07
+
+- Preserve selected monorepo project paths in generated hooks, support explicit
+  persistent hook executables, and pin ephemeral `uvx` hook invocations.
+- Add gitignored, strengthening-only local contract overlays while keeping CI
+  authoritative, and automatically protect local state from Git tracking.
+- Stream constraint start, heartbeat, retry, cache reuse, and completion status
+  during long human-readable runs.
+- Add bounded per-command transient retry policies for exit codes, startup
+  failures, and timeouts with explicit total budgets.
+- Add read-only `doctor --deep` diagnostics for executables, Python invocation,
+  environment variables/files, empty watch globs, and state hygiene.
+- Recommend isolated `uv tool` or `pipx` installation to avoid project dependency
+  conflicts.
+
+## [0.1.0] - 2026-07-29
+
+- Added the initial evidence engine, strict contract schema, provider adapters,
+  native agent hooks, contributor quality configuration, and CI baseline.
+- Added deterministic OpenAI request-contract tests, refusal and incomplete
+  response handling, safe call metadata, SDK compatibility checks, and a
+  versioned opt-in semantic evaluation corpus.
+- Added isolated native Codex and Claude Code command evaluators with
+  hook-aware same-agent preference and strict structured output.
+- Added bounded convergence loops with pending evidence, strict budgets, atomic
+  journals, recoverable supervisor leases, stable cycle exit codes, native
+  prompts, and shared Stop-hook attempt accounting.
+- Declared the v0.1 compatibility boundary around CLI and versioned protocols;
+  Python submodules remain internal during initial development.
+- Added snapshot-bound advisory acknowledgments so Stop feedback must be
+  addressed or explicitly explained before completion can continue.
+- Added canonical package metadata, a build-once PyPI Trusted Publishing
+  workflow, release invariants, CODEOWNERS, and dependency automation.
+- Hardened project-bound and reversible hook setup, malformed hook/settings
+  handling, exact-result deterministic waivers, complete-bundle rubric caching,
+  rename disclosure, and evaluator-scoped secret loading and redaction.
+- Added Contributor Covenant 2.1 with private conduct reporting instructions.

{constraintloop-0.1.0 → constraintloop-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: constraintloop
-Version: 0.1.0
+Version: 0.3.0
 Summary: Evidence-based completion gates for AI coding agents
 Project-URL: Homepage, https://github.com/mauhpr/constraintloop
 Project-URL: Documentation, https://github.com/mauhpr/constraintloop/tree/main/docs
@@ -45,6 +45,8 @@ Description-Content-Type: text/markdown
 
 [![CI](https://github.com/mauhpr/constraintloop/actions/workflows/ci.yml/badge.svg)](https://github.com/mauhpr/constraintloop/actions/workflows/ci.yml)
 [![codecov](https://codecov.io/gh/mauhpr/constraintloop/branch/main/graph/badge.svg)](https://codecov.io/gh/mauhpr/constraintloop)
+[![PyPI](https://img.shields.io/pypi/v/constraintloop)](https://pypi.org/project/constraintloop/)
+[![Python](https://img.shields.io/pypi/pyversions/constraintloop)](https://pypi.org/project/constraintloop/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
 ConstraintLoop is an evidence-based completion gate for AI coding agents. Instead
@@ -116,9 +118,8 @@ flowchart LR
 ## Quick start
 
 ```bash
-python -m venv .venv
-. .venv/bin/activate
-pip install constraintloop
+uv tool install constraintloop
+# Or: pipx install constraintloop
 
 constraintloop init
 constraintloop setup --adapter all
@@ -130,6 +131,12 @@ constraintloop ci
 plain `constraintloop.yml`. It does not install tools or silently invent gates.
 Review and commit the contract.
 
+Install ConstraintLoop as an isolated tool instead of adding it to the target
+project's environment. This avoids dependency conflicts with the application.
+If you intentionally run setup through `uvx`, generated hooks pin the current
+ConstraintLoop version. You can choose another persistent invocation with, for
+example, `constraintloop setup --hook-executable "pipx run constraintloop"`.
+
 The five commands above establish this flow:
 
 ```mermaid
@@ -160,6 +167,10 @@ constraints:
     command: [python, -m, pytest, -q]
     phases: [stop, ci]
     watch: ["src/**/*.py", "tests/**/*.py", pyproject.toml]
+    retry:
+      max_attempts: 3
+      exit_codes: [1]
+      delay_seconds: 2
 
   coverage:
     kind: metric
@@ -173,6 +184,14 @@ constraints:
     needs: [tests]
     phases: [stop, ci]
 
+  database_consumers:
+    kind: ratchet
+    description: Do not add legacy database consumers during migration
+    command: [python, scripts/inventory_consumers.py, --json]
+    parser: {type: json, path: counts.database_consumers}
+    mode: must_not_increase
+    phases: [stop, ci]
+
   design_review:
     kind: rubric
     enforcement: advisory
@@ -193,6 +212,15 @@ evaluators:
 See [examples/constraintloop.full.yml](examples/constraintloop.full.yml) for all
 constraint types.
 
+Ratchets store their numeric baseline and evidence SHA-256 in the committed
+`constraintloop-baselines.json`; baseline changes are therefore explicit code
+review events. JSON artifact constraints can map selected dotted paths through
+`evidence` so human-readable runs and `constraintloop status` report useful
+counts and changes while the complete machine-readable run remains available
+through `--json`. The published
+[JSON Schema](schema/constraintloop.schema.json) provides editor validation and
+autocomplete for every contract field.
+
 The pre-release engineering and open-source checklist is tracked in
 [docs/release-readiness.md](docs/release-readiness.md).
 Participation is governed by the [Code of Conduct](CODE_OF_CONDUCT.md).
@@ -263,6 +291,13 @@ stale without a mutable invalidation list. Local state lives under the
 gitignored `.constraintloop/state` directory; set `CONSTRAINTLOOP_CACHE_DIR` to
 override it.
 
+For stronger machine-local gates, create a gitignored
+`constraintloop.local.yml`. ConstraintLoop recursively merges mappings over the
+repository contract and rejects changes that could weaken committed gates.
+The authoritative `constraintloop ci` command ignores this overlay.
+`init` and `setup` add the overlay names and `.constraintloop/state/` to the
+selected project's `.gitignore`, and warn if state is already tracked.
+
 ### Verdicts and what they mean
 
 | Verdict | Meaning | Can complete? |
@@ -290,12 +325,21 @@ override it.
 - `constraintloop loop-prompt NAME --adapter claude|codex` — print the bounded
   native-agent repair protocol without launching an agent.
 - `constraintloop status` — inspect evidence without executing commands.
+- `constraintloop explain --phase change|stop|ci` — show why each constraint
+  runs or is skipped, including matched and changed watch paths, cache state,
+  and dependency chains.
+- `constraintloop baseline update ID|--all` — initialize or strengthen native
+  ratchet baselines; weakening requires the explicit `--allow-regression` flag.
 - `constraintloop debug ID` — explain evidence freshness, evaluator
   configuration, executable resolution, and native CLI availability without
   running an evaluator or consuming model quota.
 - `constraintloop acknowledge ID --reason "..."` — record an explicit
   snapshot-bound advisory disposition without changing its verdict.
-- `constraintloop doctor` — validate and fingerprint the contract.
+- `constraintloop doctor` — validate and fingerprint the contract;
+  `--deep` also checks executables, Python invocations, referenced environment
+  files and variables, worktree environment templates, virtual environments,
+  container runtimes and daemons, ratchet baselines, empty watch globs, and
+  local-state hygiene.
 - `constraintloop waive ID --reason "..."` — human-local, snapshot-bound waiver
   for fresh non-passing deterministic evidence. Rubrics cannot be waived.
 - `constraintloop enhance` — write a review-only proposal for stronger tooling.
@@ -337,7 +381,7 @@ responses become `uncertain`; a required rubric therefore fails closed.
 
 ## Compatibility boundary
 
-The supported v0.1 surfaces are the CLI and exit codes, configuration schema,
+The supported v0.3 surfaces are the CLI and exit codes, configuration schema,
 evaluator command protocol, native hook responses, and schema-versioned
 evidence and cycle JSON. Python submodules are internal during initial
 development and are not covered by semantic-versioning compatibility promises.

{constraintloop-0.1.0 → constraintloop-0.3.0}/README.md

@@ -2,6 +2,8 @@
 
 [![CI](https://github.com/mauhpr/constraintloop/actions/workflows/ci.yml/badge.svg)](https://github.com/mauhpr/constraintloop/actions/workflows/ci.yml)
 [![codecov](https://codecov.io/gh/mauhpr/constraintloop/branch/main/graph/badge.svg)](https://codecov.io/gh/mauhpr/constraintloop)
+[![PyPI](https://img.shields.io/pypi/v/constraintloop)](https://pypi.org/project/constraintloop/)
+[![Python](https://img.shields.io/pypi/pyversions/constraintloop)](https://pypi.org/project/constraintloop/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
 ConstraintLoop is an evidence-based completion gate for AI coding agents. Instead
@@ -73,9 +75,8 @@ flowchart LR
 ## Quick start
 
 ```bash
-python -m venv .venv
-. .venv/bin/activate
-pip install constraintloop
+uv tool install constraintloop
+# Or: pipx install constraintloop
 
 constraintloop init
 constraintloop setup --adapter all
@@ -87,6 +88,12 @@ constraintloop ci
 plain `constraintloop.yml`. It does not install tools or silently invent gates.
 Review and commit the contract.
 
+Install ConstraintLoop as an isolated tool instead of adding it to the target
+project's environment. This avoids dependency conflicts with the application.
+If you intentionally run setup through `uvx`, generated hooks pin the current
+ConstraintLoop version. You can choose another persistent invocation with, for
+example, `constraintloop setup --hook-executable "pipx run constraintloop"`.
+
 The five commands above establish this flow:
 
 ```mermaid
@@ -117,6 +124,10 @@ constraints:
     command: [python, -m, pytest, -q]
     phases: [stop, ci]
     watch: ["src/**/*.py", "tests/**/*.py", pyproject.toml]
+    retry:
+      max_attempts: 3
+      exit_codes: [1]
+      delay_seconds: 2
 
   coverage:
     kind: metric
@@ -130,6 +141,14 @@ constraints:
     needs: [tests]
     phases: [stop, ci]
 
+  database_consumers:
+    kind: ratchet
+    description: Do not add legacy database consumers during migration
+    command: [python, scripts/inventory_consumers.py, --json]
+    parser: {type: json, path: counts.database_consumers}
+    mode: must_not_increase
+    phases: [stop, ci]
+
   design_review:
     kind: rubric
     enforcement: advisory
@@ -150,6 +169,15 @@ evaluators:
 See [examples/constraintloop.full.yml](examples/constraintloop.full.yml) for all
 constraint types.
 
+Ratchets store their numeric baseline and evidence SHA-256 in the committed
+`constraintloop-baselines.json`; baseline changes are therefore explicit code
+review events. JSON artifact constraints can map selected dotted paths through
+`evidence` so human-readable runs and `constraintloop status` report useful
+counts and changes while the complete machine-readable run remains available
+through `--json`. The published
+[JSON Schema](schema/constraintloop.schema.json) provides editor validation and
+autocomplete for every contract field.
+
 The pre-release engineering and open-source checklist is tracked in
 [docs/release-readiness.md](docs/release-readiness.md).
 Participation is governed by the [Code of Conduct](CODE_OF_CONDUCT.md).
@@ -220,6 +248,13 @@ stale without a mutable invalidation list. Local state lives under the
 gitignored `.constraintloop/state` directory; set `CONSTRAINTLOOP_CACHE_DIR` to
 override it.
 
+For stronger machine-local gates, create a gitignored
+`constraintloop.local.yml`. ConstraintLoop recursively merges mappings over the
+repository contract and rejects changes that could weaken committed gates.
+The authoritative `constraintloop ci` command ignores this overlay.
+`init` and `setup` add the overlay names and `.constraintloop/state/` to the
+selected project's `.gitignore`, and warn if state is already tracked.
+
 ### Verdicts and what they mean
 
 | Verdict | Meaning | Can complete? |
@@ -247,12 +282,21 @@ override it.
 - `constraintloop loop-prompt NAME --adapter claude|codex` — print the bounded
   native-agent repair protocol without launching an agent.
 - `constraintloop status` — inspect evidence without executing commands.
+- `constraintloop explain --phase change|stop|ci` — show why each constraint
+  runs or is skipped, including matched and changed watch paths, cache state,
+  and dependency chains.
+- `constraintloop baseline update ID|--all` — initialize or strengthen native
+  ratchet baselines; weakening requires the explicit `--allow-regression` flag.
 - `constraintloop debug ID` — explain evidence freshness, evaluator
   configuration, executable resolution, and native CLI availability without
   running an evaluator or consuming model quota.
 - `constraintloop acknowledge ID --reason "..."` — record an explicit
   snapshot-bound advisory disposition without changing its verdict.
-- `constraintloop doctor` — validate and fingerprint the contract.
+- `constraintloop doctor` — validate and fingerprint the contract;
+  `--deep` also checks executables, Python invocations, referenced environment
+  files and variables, worktree environment templates, virtual environments,
+  container runtimes and daemons, ratchet baselines, empty watch globs, and
+  local-state hygiene.
 - `constraintloop waive ID --reason "..."` — human-local, snapshot-bound waiver
   for fresh non-passing deterministic evidence. Rubrics cannot be waived.
 - `constraintloop enhance` — write a review-only proposal for stronger tooling.
@@ -294,7 +338,7 @@ responses become `uncertain`; a required rubric therefore fails closed.
 
 ## Compatibility boundary
 
-The supported v0.1 surfaces are the CLI and exit codes, configuration schema,
+The supported v0.3 surfaces are the CLI and exit codes, configuration schema,
 evaluator command protocol, native hook responses, and schema-versioned
 evidence and cycle JSON. Python submodules are internal during initial
 development and are not covered by semantic-versioning compatibility promises.

constraintloop-0.3.0/docs/configuration.md

@@ -0,0 +1,136 @@
+# Configuration reference
+
+ConstraintLoop reads the nearest supported YAML contract filename. The schema
+is strict: unknown fields are errors.
+
+The root fields are `version` (currently `1`), `settings`, `constraints`,
+`evaluators`, and `loops`.
+
+The generated JSON Schema is published at
+[`schema/constraintloop.schema.json`](../schema/constraintloop.schema.json).
+Editors that support YAML language-server directives can enable validation and
+autocomplete with:
+
+```yaml
+# yaml-language-server: $schema=https://raw.githubusercontent.com/mauhpr/constraintloop/main/schema/constraintloop.schema.json
+```
+
+Settings default to:
+
+| Field | Default | Allowed |
+| --- | ---: | --- |
+| `max_auto_retries` | 2 | 0–20 |
+| `concurrency` | 4 | 1–32 |
+| `evidence_output_limit` | 65536 | 1024–1048576 bytes |
+| `evaluation_bundle_limit` | 102400 | 4096–2097152 bytes |
+| `progress_interval_seconds` | 15 | 0.1–300 seconds |
+
+If `constraintloop.local.yml` or `constraintloop.local.yaml` exists beside the
+repository contract, it is loaded as a local overlay. Mapping values merge
+recursively. Overlays may add constraints and tighten an existing constraint's
+enforcement, phase set, dependency set, or timeout. They cannot disable or
+replace committed gates, commands, evaluators, loops, watched inputs, or reduce
+evidence limits. Only one overlay filename may exist. The merged contract is
+validated normally and its digest invalidates evidence when local policy
+changes. `init` and `setup` add both overlay names to `.gitignore`. The
+authoritative `constraintloop ci` command ignores local overlays and always
+evaluates the committed repository contract.
+
+Every constraint supports `description`, `enforcement` (`required` or
+`advisory`), `phases` (`change`, `stop`, `ci`), `watch` globs, dependency IDs
+in `needs`, `timeout_seconds`, and `enabled`. Dependencies must exist and the
+graph must be acyclic.
+Identifiers may contain letters, numbers, dots, underscores, and hyphens.
+`watch` and `include` values must be nonempty project-relative POSIX globs.
+
+Command constraints use `kind: command`, `command`, `cwd`, `shell`,
+`success_codes`, and `pending_codes` (default `[75]`). Prefer an argv list. A
+string command is rejected unless `shell: true` explicitly accepts shell
+parsing. Success and pending codes may not overlap.
+
+Command, metric, and ratchet constraints may declare an optional transient
+retry policy:
+
+```yaml
+retry:
+  max_attempts: 3
+  exit_codes: [1, 125]
+  retry_timeouts: false
+  retry_start_errors: true
+  delay_seconds: 2
+  total_timeout_seconds: 90
+```
+
+No retries occur when `retry` is absent. A configured policy retries only the
+listed exit codes and, when enabled, timeouts or process startup failures.
+Every attempt is capped by the constraint's normal timeout. Retry and periodic
+running status lines are emitted during human-readable runs; `--json` remains a
+single machine-readable document. `timeout_seconds` bounds each attempt and,
+unless overridden, the complete retry sequence including delays. Timeout
+retries require an explicit `total_timeout_seconds` greater than the per-attempt
+timeout. This keeps the total bound visible while leaving enough budget for a
+second attempt.
+
+Metric constraints add `parser` and `threshold`. A parser has type `json` or
+`regex`, reads `stdout`, `stderr`, or a project-contained `file`, and selects a
+dotted JSON `path` or regex `pattern` and `group`. Threshold operators are
+`gt`, `gte`, `lt`, `lte`, and `eq`.
+
+Ratchet constraints use `kind: ratchet` with the same command and parser fields
+as a metric. Their default `mode: must_not_increase` compares the current value
+to the committed `constraintloop-baselines.json`; `must_not_decrease` supports
+monotonic growth metrics. Initialize or strengthen baselines explicitly:
+
+```bash
+constraintloop baseline update database_consumers
+constraintloop baseline update --all
+```
+
+Updates that would weaken an existing baseline are rejected. Use
+`--allow-regression` only for a reviewed, intentional reset, then commit the
+baseline artifact with the contract. `baseline_file` can select another
+project-relative JSON file. Each baseline entry records both the numeric value
+and the SHA-256 digest of the parsed evidence source, replacing the separate
+count-and-hash bookkeeping commonly used for migration inventories.
+
+Artifact constraints use `kind: artifact`, a project-contained `path`, format
+`any`, `json`, or `junit`, and `non_empty`. JSON artifacts can expose selected
+dotted paths as structured evidence so summaries and `status` show meaningful
+counts instead of the entire report:
+
+```yaml
+report:
+  kind: artifact
+  path: reports/consumer-inventory.json
+  format: json
+  evidence:
+    consumers: counts.consumers
+    change: counts.change
+```
+
+Rubric constraints use `kind: rubric`, an evaluator ID, a written `rubric`,
+`include` globs, `runs`, and `pass_quorum`. Required rubrics need at least two
+runs and an explicit majority quorum.
+
+Evaluators are:
+
+- `command`: `command`, `shell`, and `timeout_seconds`;
+- `openai`: `model`, `api_key_env`, `timeout_seconds`, `max_attempts`,
+  `max_output_tokens`, and `reasoning_effort`;
+- `anthropic`: `model`, `api_key_env`, `timeout_seconds`, `max_attempts`, and
+  `max_output_tokens`.
+
+See `examples/constraintloop.full.yml` for a parseable full example. CI ignores
+local waivers. Each loop declares a phase, positive polling interval, repair and
+unchanged-repair budgets, a duration budget, and fixed pass/failure/pending/
+exhaustion actions. Unknown fields and zero or unbounded budgets are rejected.
+At most one Stop-phase loop is allowed. Ready deterministic constraints execute
+concurrently up to `settings.concurrency`; rubric evaluators remain serialized
+and result ordering follows the contract.
+`constraintloop explain --phase stop` reports why every constraint is eligible
+or skipped, the files matched by its watch globs, changed watch paths, cache
+state, and dependency chains without executing any gate. Human-readable final
+summaries label concrete policy failures as `constraint` and startup,
+prerequisite, or evaluation errors as `environment`; the same
+`failure_category` is retained in JSON evidence.
+See `docs/convergence-loops.md` for the cycle protocol and stable exit codes.

{constraintloop-0.1.0 → constraintloop-0.3.0}/docs/faq.md

@@ -132,8 +132,10 @@ trusted completion boundary.
 ### Will setup overwrite existing hooks?
 
 No. `constraintloop setup` merges owned hook entries and preserves unrelated
-configuration. `constraintloop uninstall` removes only owned entries. Review
-and trust newly installed Codex project hooks through `/hooks`.
+configuration. In a monorepo, hooks retain the exact directory selected with
+`--project` instead of falling back to the Git root. `constraintloop uninstall`
+removes only owned entries. Review and trust newly installed Codex project hooks
+through `/hooks`.
 
 ### Why does a hook say `Missing option --project`?
 
@@ -168,7 +170,7 @@ journal and releases the lease.
 
 ## Compatibility and release
 
-### Which platforms are supported in v0.1?
+### Which platforms are supported in v0.2?
 
 Linux and macOS on Python 3.11 through 3.14. Windows is not supported until
 hook commands, locking, process control, and installed-wheel behavior have

{constraintloop-0.1.0 → constraintloop-0.3.0}/docs/release-readiness.md

@@ -23,13 +23,13 @@ ConstraintLoop currently has:
 - a self-contract that passes its deterministic gates.
 
 The public GitHub repository, protected `main` branch, cross-platform CI,
-community-health files, production `pypi` environment, and pending Trusted
-Publisher are configured. The first production publication and external
-installation verification remain.
+community-health files, production `pypi` environment, and Trusted Publisher
+are configured. Version 0.1.0 was published through that identity,
+both distributions expose PyPI provenance, and a clean public-index install
+passed the CLI initialization and contract-validation smoke test.
 
-The PyPI JSON endpoint for `constraintloop` returned 404 during this assessment,
-so the name appeared unoccupied. A name is not reserved until the project is
-actually registered and published.
+The canonical package page is
+[pypi.org/project/constraintloop](https://pypi.org/project/constraintloop/).
 
 ## v0.1 release gates
 

{constraintloop-0.1.0 → constraintloop-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "constraintloop"
-version = "0.1.0"
+version = "0.3.0"
 description = "Evidence-based completion gates for AI coding agents"
 readme = "README.md"
 license = "MIT"
@@ -66,6 +66,7 @@ include = [
     "/tests",
     "/docs",
     "/scripts",
+    "/schema",
     "/pyproject.toml",
     "/README.md",
     "/LICENSE",