constraintloop 0.4.1__tar.gz → 0.5.1__tar.gz

{constraintloop-0.4.1 → constraintloop-0.5.1}/CHANGELOG.md

@@ -5,6 +5,48 @@ Versioning, with the usual initial-development flexibility for `0.y.z`.
 
 ## [Unreleased]
 
+## [0.5.1] - 2026-09-08
+
+- Isolate local evidence, sessions, waivers, acknowledgments, journals, and leases
+  by resolved project/worktree and branch (commit for detached HEAD). Bind input
+  digests to checkout identity and HEAD, keeping branch retry budgets across commits.
+- Reject checkout changes during gate evaluation and supervision. Report project,
+  worktree, branch, HEAD, and state directory in `doctor` and `explain`.
+- Migration: Git projects start fresh state under `.constraintloop/state/checkouts/`;
+  prior unscoped state is retained but never imported into a branch. All prior input
+  digests become stale. Run checks again and start a fresh challenge cycle if used.
+
+## [0.5.0] - 2026-09-06
+
+- Add optional session challenge gates for Claude Code, Codex, and Gemini CLI:
+  generate configurable domain-grounded scenarios, record immutable plans,
+  verify outcomes against fresh deterministic evidence, and repair defects
+  without launching a model evaluator.
+- Add challenge show/submit commands, challenge/verify cycle states, Gemini
+  loop prompts, and persisted continuation budgets for all three adapters.
+- Preserve task goals through generated continuation prompts and stop Gemini
+  sessions on exhausted budgets instead of requesting another retry.
+- Fix all ten pre-release findings: frame content hashes unambiguously; bound
+  ordinary recursive Stop hooks and advisory continuations; fail closed on
+  malformed evidence and unexpected hook errors; reject push/CI waivers in
+  every engine entry point; report repairable dependency failures by root
+  cause; renew budgets for completed tasks; refresh pending hook evidence on
+  the shared cycle interval; reject non-finite metrics, thresholds, and
+  baselines; redact retained evidence; and deny observed agent baseline
+  weakening and direct baseline edits.
+- Reject disabled or phase-incompatible prerequisites, keep CI loops free of
+  local overlays, bound subprocess collection to 8 MiB, and renew supervisor
+  leases during long evaluations and polling waits.
+- Add regression matrices for adapters, phase policy, malformed numbers, digest
+  boundaries, lifecycle sequences, and installed-package challenge workflows.
+- Cover every changed executable line, including submission rejection,
+  missing requests, unreadable files, and lost leases. Report malformed YAML
+  by location without raw source excerpts that could disclose credentials.
+- Migration: existing evidence and waivers become stale under the new input
+  digest. Re-run checks; review incompatible prerequisite phases and invalid
+  numeric baselines. Challenge gates remain opt-in. Re-run hook setup after
+  upgrading if hooks use a pinned ephemeral executable.
+
 ## [0.4.1] - 2026-09-04
 
 - Raise enforced statement coverage from 90% to 95% and branch coverage from

{constraintloop-0.4.1 → constraintloop-0.5.1}/CONTRIBUTING.md

@@ -5,7 +5,7 @@ By participating, you agree to follow the
 the contact method documented there.
 
 ConstraintLoop accepts focused changes that strengthen evidence, state,
-budgeting, locks, and stopping. It is not a general agent runtime and v0.1 must
+budgeting, locks, and stopping. It is not a general agent runtime and must
 not launch provider CLIs for repair turns or offer unbounded repair loops.
 Opt-in native CLI evaluators are limited to isolated, tool-disabled reviews.
 
@@ -43,5 +43,5 @@ Releases are prepared through a focused release pull request and published only
 through GitHub Trusted Publishing. See `RELEASE.md`. Contributors and agents
 must not run local package upload commands or add long-lived registry tokens.
 
-The supported v0.1 platforms are macOS and Linux. Windows is not supported
+The supported platforms are macOS and Linux. Windows is not supported
 until hook command generation and clean-wheel tests are implemented there.

{constraintloop-0.4.1 → constraintloop-0.5.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: constraintloop
-Version: 0.4.1
+Version: 0.5.1
 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
@@ -69,11 +69,17 @@ The central distinction is deliberate:
 ConstraintLoop supports Claude Code, Codex, and Gemini CLI through their hook
 lifecycles. CI is the final authority: it ignores local caches and human waivers.
 
-Bounded convergence loops are included in the v0.1 release scope. The design
+Bounded convergence loops are implemented. The design
 keeps ConstraintLoop in control of evidence, budgets, and stopping while native
 Claude or Codex loops perform at most one requested repair per transition. See
 [docs/convergence-loops.md](docs/convergence-loops.md).
 
+Completion loops can also require the current coding session to generate and
+investigate N domain-grounded failure scenarios before stopping. Claude Code,
+Codex, and Gemini CLI use their existing session context and tools; this
+challenge gate requires no separate model evaluator. See
+[session challenge gates](docs/convergence-loops.md#session-challenge-gates).
+
 ## At a glance
 
 | Question | ConstraintLoop answer |
@@ -308,10 +314,13 @@ Commands run from their configured project-contained `cwd`, with the selected
 project root prepended to `PYTHONPATH`.
 
 Evidence is keyed by the constraint definition and the bytes of every file
-matched by `watch`. A source change therefore makes old evidence and waivers
-stale without a mutable invalidation list. Local state lives under the
+matched by `watch`, plus the resolved project/worktree, branch, and HEAD. A source
+change or new HEAD therefore makes old evidence and waivers stale without a
+mutable invalidation list. Local state lives under the
 gitignored `.constraintloop/state` directory; set `CONSTRAINTLOOP_CACHE_DIR` to
-override it.
+override it. Git projects use a separate state subdirectory per branch in each
+worktree. Use one worktree per concurrent line of work; `doctor` and `explain`
+show the active scope. See [worktrees and concurrent sessions](docs/worktrees.md).
 
 For stronger machine-local gates, create a gitignored
 `constraintloop.local.yml`. ConstraintLoop recursively merges mappings over the
@@ -351,8 +360,11 @@ reactivate ConstraintLoop; setup clears the tombstone.
 - `constraintloop cycle NAME --json` — execute one journaled loop transition.
 - `constraintloop supervise NAME` — poll pending evidence under a recoverable
   single-writer lease and exit whenever repair or termination is required.
-- `constraintloop loop-prompt NAME --adapter claude|codex` — print the bounded
-  native-agent repair protocol without launching an agent.
+- `constraintloop loop-prompt NAME --adapter claude|codex|gemini` — print the bounded
+  native-agent repair and challenge protocol without launching an agent.
+- `constraintloop challenge show NAME` — inspect saved scenarios and the submission schema.
+- `constraintloop challenge submit NAME --file PATH` — record session-authored
+  discovery or verification for the current request and input snapshot.
 - `constraintloop status` — inspect evidence without executing commands.
 - `constraintloop explain --phase change|stop|push|ci` — show why each constraint
   runs or is skipped, including matched and changed watch paths, cache state,
@@ -375,7 +387,7 @@ reactivate ConstraintLoop; setup clears the tombstone.
 - `constraintloop author` — write a review-only QA/test-authoring proposal.
 
 `enhance` and `author` intentionally do not install dependencies or modify the
-active contract in v0.1. Their proposal files make the future self-improvement
+active contract. Their proposal files make the future self-improvement
 path auditable.
 
 ## Documentation

{constraintloop-0.4.1 → constraintloop-0.5.1}/README.md

@@ -26,11 +26,17 @@ The central distinction is deliberate:
 ConstraintLoop supports Claude Code, Codex, and Gemini CLI through their hook
 lifecycles. CI is the final authority: it ignores local caches and human waivers.
 
-Bounded convergence loops are included in the v0.1 release scope. The design
+Bounded convergence loops are implemented. The design
 keeps ConstraintLoop in control of evidence, budgets, and stopping while native
 Claude or Codex loops perform at most one requested repair per transition. See
 [docs/convergence-loops.md](docs/convergence-loops.md).
 
+Completion loops can also require the current coding session to generate and
+investigate N domain-grounded failure scenarios before stopping. Claude Code,
+Codex, and Gemini CLI use their existing session context and tools; this
+challenge gate requires no separate model evaluator. See
+[session challenge gates](docs/convergence-loops.md#session-challenge-gates).
+
 ## At a glance
 
 | Question | ConstraintLoop answer |
@@ -265,10 +271,13 @@ Commands run from their configured project-contained `cwd`, with the selected
 project root prepended to `PYTHONPATH`.
 
 Evidence is keyed by the constraint definition and the bytes of every file
-matched by `watch`. A source change therefore makes old evidence and waivers
-stale without a mutable invalidation list. Local state lives under the
+matched by `watch`, plus the resolved project/worktree, branch, and HEAD. A source
+change or new HEAD therefore makes old evidence and waivers stale without a
+mutable invalidation list. Local state lives under the
 gitignored `.constraintloop/state` directory; set `CONSTRAINTLOOP_CACHE_DIR` to
-override it.
+override it. Git projects use a separate state subdirectory per branch in each
+worktree. Use one worktree per concurrent line of work; `doctor` and `explain`
+show the active scope. See [worktrees and concurrent sessions](docs/worktrees.md).
 
 For stronger machine-local gates, create a gitignored
 `constraintloop.local.yml`. ConstraintLoop recursively merges mappings over the
@@ -308,8 +317,11 @@ reactivate ConstraintLoop; setup clears the tombstone.
 - `constraintloop cycle NAME --json` — execute one journaled loop transition.
 - `constraintloop supervise NAME` — poll pending evidence under a recoverable
   single-writer lease and exit whenever repair or termination is required.
-- `constraintloop loop-prompt NAME --adapter claude|codex` — print the bounded
-  native-agent repair protocol without launching an agent.
+- `constraintloop loop-prompt NAME --adapter claude|codex|gemini` — print the bounded
+  native-agent repair and challenge protocol without launching an agent.
+- `constraintloop challenge show NAME` — inspect saved scenarios and the submission schema.
+- `constraintloop challenge submit NAME --file PATH` — record session-authored
+  discovery or verification for the current request and input snapshot.
 - `constraintloop status` — inspect evidence without executing commands.
 - `constraintloop explain --phase change|stop|push|ci` — show why each constraint
   runs or is skipped, including matched and changed watch paths, cache state,
@@ -332,7 +344,7 @@ reactivate ConstraintLoop; setup clears the tombstone.
 - `constraintloop author` — write a review-only QA/test-authoring proposal.
 
 `enhance` and `author` intentionally do not install dependencies or modify the
-active contract in v0.1. Their proposal files make the future self-improvement
+active contract. Their proposal files make the future self-improvement
 path auditable.
 
 ## Documentation

constraintloop-0.5.1/docs/completion-policy.md

@@ -0,0 +1,74 @@
+# Completion policy and v0.5 migration
+
+## Entry points
+
+| Entry point | Local overlays | Local waivers | Pending refresh | Task completion |
+| --- | --- | --- | --- | --- |
+| `run --phase change/stop` | Strengthening only | Deterministic gates only | Use `--no-cache` for a fresh observation | Constraint report only |
+| `run --phase push` | Strengthening only | Never | Use `--no-cache` | Constraint report only |
+| `ci` / `run --phase ci` | Never | Never | Always uncached | Independent CI evidence |
+| `cycle` / `supervise` | Except CI phase | Except push/CI | Refresh after loop interval | Persisted bounded transition; includes configured challenge work |
+| Stop / AfterAgent hooks | Strengthening only | Deterministic gates only | Shared cycle interval, or refresh each event without a loop | Required evidence, configured challenges, and advisory dispositions |
+
+The engine enforces waiver and CI-cache policy regardless of caller defaults.
+`run` does not finish a session challenge gate. Use `cycle` and the native Stop
+hook for completion. CI verifies committed deterministic/rubric constraints;
+it does not trust a local challenge journal or start an interactive session.
+
+Failed prerequisites produce blocked dependents with `blocked_by` IDs, not
+spurious evaluation errors. A cycle's `blocking_constraints` names the root
+causes, including advisory prerequisites needed by required gates. Missing
+tools, parser failures, and uncertain evaluations remain blocking errors.
+
+## Task lifecycle
+
+After a loop passes, a changed watched input or task goal starts a new run with
+a fresh budget. Restarting an unfinished run, changing its code, or changing
+its goal does not reset its limits. Unchanged completed evidence stays passed
+even after the old time budget elapses. One project loop has one journal;
+use separate worktrees for independent concurrent tasks.
+
+Recursive Stop hooks are completion boundaries too. Ordinary loops use their
+repair and duration budgets. Challenge loops also bound session continuations.
+Without a loop, `max_auto_retries` bounds repair and advisory-disposition
+continuations across changing evidence until completion succeeds. Exhaustion
+returns `continue: false`, including Gemini, rather than silently allowing
+completion or asking the agent to retry indefinitely.
+
+`supervise` renews its lease during checks and waits, and checks ownership
+before yielding a transition. It does not launch an agent or perform repairs.
+
+## Evidence and redaction
+
+The input-digest format is versioned and length-framed: filename/content
+boundaries, unreadable files, and missing baselines cannot alias ordinary
+content. Upgrading invalidates old evidence and snapshot-bound waivers.
+
+Known sensitive environment values of at least eight characters are scrubbed,
+as are credential assignments such as `password=...`, `api_key=...`, and
+`access_token=...`. Structured sensitive keys are scrubbed recursively.
+Scrubbing applies to evidence messages, findings, structured artifact fields,
+retained command output, cached reads, and native-hook feedback. Command output
+is scrubbed before tail truncation so truncation cannot sever the credential
+label from its value.
+
+This is best-effort redaction, not a data-loss-prevention boundary. Unknown,
+encoded, split, or unlabeled secrets may escape detection. Raw command output
+exists transiently in memory for parsing, bounded to 8 MiB per subprocess.
+Pre-existing files from older releases are not retroactively erased. Avoid
+printing credentials and restrict access to local state. Repository artifacts
+and challenge submissions remain author-controlled data; do not put secrets
+in them. No new remote model API is used by the session challenge gate.
+
+## Upgrade checklist
+
+1. Upgrade ConstraintLoop to 0.5.0 and re-run `constraintloop setup --adapter all`
+   in projects whose hooks pin an ephemeral package version.
+2. Re-run checks to replace stale cached evidence. Revisit any intentional
+   local waiver against the new exact evidence; CI and push cannot use it.
+3. Ensure prerequisites are enabled in every dependent phase. Correct invalid
+   numeric baselines; finite numeric strings are still accepted.
+4. Keep noisy tool output below 8 MiB or write detailed reports to artifacts
+   and emit a compact command summary.
+5. Enable `loops.NAME.challenge` explicitly where domain-driven self-review is
+   desired. Omitted challenge configuration preserves ordinary gating.

{constraintloop-0.4.1 → constraintloop-0.5.1}/docs/configuration.md

@@ -41,6 +41,10 @@ Every constraint supports `description`, `enforcement` (`required` or
 `advisory`), `phases` (`change`, `stop`, `push`, `ci`), `watch` globs, dependency IDs
 in `needs`, `timeout_seconds`, and `enabled`. Dependencies must exist and the
 graph must be acyclic.
+Every enabled dependent must have its prerequisites enabled in all of its
+phases. A failed prerequisite blocks its dependents without running them;
+cycles report the root cause for repair, even if that prerequisite is advisory.
+Genuine evaluation errors still require human inspection.
 Identifiers may contain letters, numbers, dots, underscores, and hyphens.
 `watch` and `include` values must be nonempty project-relative POSIX globs.
 
@@ -75,11 +79,18 @@ 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. Command and command-evaluator processes run from the selected
 project root by default, and ConstraintLoop prepends that root to `PYTHONPATH`.
+Collection of combined stdout/stderr has a separate hard 8 MiB limit per
+process. Exceeding it terminates the process group and produces an error;
+truncated output is never treated as a complete metric or evaluator response.
+`evidence_output_limit` controls the smaller, redacted tail retained afterward.
 
 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`.
+Measurements, thresholds, and baselines must be finite numbers. Finite numeric
+strings remain supported; booleans, nulls, containers, NaN, and infinities are
+rejected. `--allow-regression` never overrides numeric validation.
 
 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
@@ -94,7 +105,11 @@ 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
+project-relative JSON file. Observed agent commands using `--allow-regression`
+and direct edits to baseline files are denied by pre-tool hooks; ask the human
+to perform intentional policy changes outside the hooked session. Strengthening
+through the ordinary baseline-update command remains allowed. 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.
 
@@ -142,3 +157,16 @@ Hook responses use `hook_output_limit` to retain failing test names and the firs
 useful traceback line without injecting the complete test log. The unabridged
 retained tail remains available with `constraintloop debug CONSTRAINT`.
 See `docs/convergence-loops.md` for the cycle protocol and stable exit codes.
+
+Stop-phase loops optionally accept `challenge` for discovery and verification
+performed in the active Claude Code, Codex, or Gemini CLI session. Defaults are
+`count: 10` (1–100), `max_rounds: 2` (1–10), `max_continuations: 8` (1–100),
+`watch: ["**/*"]`, and `domain_context: []`. Context and watch entries are
+project-relative globs. The existing loop duration and repair budgets also
+apply; challenge work uses no model evaluator configuration. Omit `challenge`
+to retain the ordinary completion behavior. See
+[session challenge gates](convergence-loops.md#session-challenge-gates) for
+submission examples, evidence requirements, and adapter behavior.
+
+See [completion policy](completion-policy.md) for the cross-entry-point matrix,
+task lifecycle, redaction policy, and upgrade notes.