constraintloop 0.3.1__tar.gz → 0.5.0__tar.gz

{constraintloop-0.3.1 → constraintloop-0.5.0}/.gitignore

@@ -16,3 +16,6 @@ dist/
 .constraintloop/
 constraintloop.local.yml
 constraintloop.local.yaml
+.claude/settings.local.json
+.codex/hooks.json
+.gemini/settings.json

{constraintloop-0.3.1 → constraintloop-0.5.0}/CHANGELOG.md

@@ -5,6 +5,60 @@ Versioning, with the usual initial-development flexibility for `0.y.z`.
 
 ## [Unreleased]
 
+## [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
+  80% to 90%.
+- Add behavioral coverage for lifecycle CLI boundaries, hook configuration
+  failures, native evaluator entrypoints, timeout escalation, project
+  scaffolding, environment parsing, and contract validation.
+
+## [0.4.0] - 2026-09-04
+
+- Enforce finite command timeouts across complete POSIX process groups so
+  leaked Docker/TestContainers descendants cannot hold Stop gates open.
+- Add an explicit `push` phase and opt-in managed Git pre-push hook for heavy
+  integration gates while keeping frequent Stop checks fast.
+- Install Claude hooks in gitignored local settings, persist explicit uninstall
+  tombstones, and remove ConstraintLoop's own committed agent settings files.
+- Defer lifecycle evaluation for subagents and turns paused on background or
+  scheduled work.
+- Compact hook failure output to counts, failing checks, and high-signal error
+  lines while retaining full evidence for `constraintloop debug`.
+- Run commands and command evaluators from a stable project context with the
+  project root on `PYTHONPATH`.
+
 ## [0.3.1] - 2026-08-31
 
 - Prevent recursive Claude Stop-hook invocations from repeatedly blocking completion.

{constraintloop-0.3.1 → constraintloop-0.5.0}/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.3.1 → constraintloop-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: constraintloop
-Version: 0.3.1
+Version: 0.5.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
@@ -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 |
@@ -123,6 +129,7 @@ uv tool install constraintloop
 
 constraintloop init
 constraintloop setup --adapter all
+# Or add --pre-push above to wire heavyweight push gates locally.
 constraintloop run
 constraintloop ci
 ```
@@ -137,7 +144,7 @@ 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:
+The five core commands above establish this flow:
 
 ```mermaid
 sequenceDiagram
@@ -147,7 +154,7 @@ sequenceDiagram
     participant T as Project tools
     U->>CL: init + review contract
     U->>CL: setup hooks
-    A->>CL: run change/stop phase
+    A->>CL: run change/stop/push phase
     CL->>T: execute ready constraints
     T-->>CL: exit codes, metrics, artifacts
     CL-->>A: pass, repair, wait, or escalate
@@ -160,18 +167,27 @@ sequenceDiagram
 version: 1
 settings:
   max_auto_retries: 2
+  hook_output_limit: 4096
 
 constraints:
   tests:
     kind: command
     command: [python, -m, pytest, -q]
-    phases: [stop, ci]
+    phases: [stop, push, ci]
     watch: ["src/**/*.py", "tests/**/*.py", pyproject.toml]
     retry:
       max_attempts: 3
       exit_codes: [1]
       delay_seconds: 2
 
+  integration_tests:
+    kind: command
+    command: [python, -m, pytest, -q, -m, integration]
+    phases: [push, ci]
+    watch: ["src/**/*.py", "tests/**/*.py", pyproject.toml]
+    needs: [tests]
+    timeout_seconds: 900
+
   coverage:
     kind: metric
     command: [python, -m, pytest, --cov, "--cov-report=json:coverage.json"]
@@ -266,16 +282,22 @@ advisory until their false-positive and false-negative rates are measured.
 | --- | --- | --- |
 | `change` | After a file-changing tool action | Fast syntax, formatting, or diff checks |
 | `stop` | When the agent attempts to finish | Tests, build checks, and advisory review |
+| `push` | Explicit local run or opt-in Git pre-push hook | Full integration and platform suites |
 | `ci` | Protected hosted workflow | Authoritative uncached and waiver-free verification |
 
 1. `SessionStart` tells the coding agent which required gates exist.
 2. The prompt hook records the user's goal as review evidence.
 3. Before tool execution, agent attempts to edit the contract or create a
    waiver are denied.
-4. After tool execution, `change` gates run and fresh results are injected.
+4. After a main-agent tool execution, `change` gates run and fresh results are
+   injected. Subagent tool and stop events are ignored because their working
+   tree may be intentionally transient.
 5. Before compaction, the completion policy is restated.
 6. At `Stop` / `AfterAgent`, required `stop` gates block completion. The agent
-   receives precise evidence and may repair the code a bounded number of times.
+   receives compact evidence and may repair the code a bounded number of times.
+   ConstraintLoop defers this evaluation while background tasks or scheduled
+   wakeups are active. Full retained output remains available through
+   `constraintloop debug ID`.
 7. Advisory failures require either passing fresh evidence or an explicit
    snapshot-bound explanation; delivery alone never counts as review.
 8. Repeated required failure stops autonomous repair and requests a human
@@ -285,6 +307,12 @@ advisory until their false-positive and false-negative rates are measured.
    is human.
 9. `constraintloop ci` reruns every CI gate without local evidence or waivers.
 
+Every command constraint has a finite timeout (300 seconds by default). On POSIX,
+timeout cleanup terminates the entire spawned process group so TestContainers,
+Docker clients, and other descendants cannot keep inherited output pipes open.
+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
@@ -295,8 +323,12 @@ 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.
+`init` and `setup` add local state, the uninstall tombstone, generated agent hook
+settings, and overlay names to the selected project's `.gitignore`, and warn if
+state is already tracked. Claude uses its dedicated
+`.claude/settings.local.json` path. Explicit uninstall records a local tombstone,
+so a checkout that restores old committed hook wiring does not silently
+reactivate ConstraintLoop; setup clears the tombstone.
 
 ### Verdicts and what they mean
 
@@ -313,19 +345,25 @@ selected project's `.gitignore`, and warn if state is already tracked.
 ## Commands
 
 - `constraintloop init` — generate a reviewable initial contract.
-- `constraintloop setup --adapter claude|codex|gemini|all` — merge hook entries
-  while preserving existing hooks.
+- `constraintloop setup --adapter claude|codex|gemini|all [--pre-push]` — merge
+  agent hook entries while preserving existing hooks; optionally install an
+  owned Git pre-push hook for `push` gates.
 - `constraintloop uninstall --adapter claude|codex|gemini|all` — remove only
-  ConstraintLoop hook entries while preserving unrelated settings.
-- `constraintloop run --phase change|stop` — run local gates with fresh caching.
+  ConstraintLoop hook entries while preserving unrelated settings; pass
+  `--pre-push` to remove an owned Git hook too.
+- `constraintloop run --phase change|stop|push` — run local gates with fresh
+  caching. Push gates do not honor local waivers.
 - `constraintloop ci` — authoritative, uncached, waiver-free run.
 - `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|ci` — show why each constraint
+- `constraintloop explain --phase change|stop|push|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
@@ -346,7 +384,7 @@ selected project's `.gitignore`, and warn if state is already tracked.
 - `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
@@ -381,7 +419,7 @@ responses become `uncertain`; a required rubric therefore fails closed.
 
 ## Compatibility boundary
 
-The supported v0.3 surfaces are the CLI and exit codes, configuration schema,
+The supported v0.4 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.
@@ -401,7 +439,8 @@ policy. ConstraintLoop records which contract ran, which inputs it covered, and
 whether the evidence is still fresh.
 
 **Why do some constraints run after every action?** Put only fast feedback in
-the `change` phase. Expensive tests and reviews belong in `stop` and `ci`.
+the `change` phase. Keep unit checks in `stop`; put heavyweight integration
+suites in `push` and `ci`.
 
 **Can I use Codex or Claude Code instead of an API evaluator?** Yes. The native
 evaluator adapter prefers the active supported CLI and remains read-only.

{constraintloop-0.3.1 → constraintloop-0.5.0}/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 |
@@ -80,6 +86,7 @@ uv tool install constraintloop
 
 constraintloop init
 constraintloop setup --adapter all
+# Or add --pre-push above to wire heavyweight push gates locally.
 constraintloop run
 constraintloop ci
 ```
@@ -94,7 +101,7 @@ 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:
+The five core commands above establish this flow:
 
 ```mermaid
 sequenceDiagram
@@ -104,7 +111,7 @@ sequenceDiagram
     participant T as Project tools
     U->>CL: init + review contract
     U->>CL: setup hooks
-    A->>CL: run change/stop phase
+    A->>CL: run change/stop/push phase
     CL->>T: execute ready constraints
     T-->>CL: exit codes, metrics, artifacts
     CL-->>A: pass, repair, wait, or escalate
@@ -117,18 +124,27 @@ sequenceDiagram
 version: 1
 settings:
   max_auto_retries: 2
+  hook_output_limit: 4096
 
 constraints:
   tests:
     kind: command
     command: [python, -m, pytest, -q]
-    phases: [stop, ci]
+    phases: [stop, push, ci]
     watch: ["src/**/*.py", "tests/**/*.py", pyproject.toml]
     retry:
       max_attempts: 3
       exit_codes: [1]
       delay_seconds: 2
 
+  integration_tests:
+    kind: command
+    command: [python, -m, pytest, -q, -m, integration]
+    phases: [push, ci]
+    watch: ["src/**/*.py", "tests/**/*.py", pyproject.toml]
+    needs: [tests]
+    timeout_seconds: 900
+
   coverage:
     kind: metric
     command: [python, -m, pytest, --cov, "--cov-report=json:coverage.json"]
@@ -223,16 +239,22 @@ advisory until their false-positive and false-negative rates are measured.
 | --- | --- | --- |
 | `change` | After a file-changing tool action | Fast syntax, formatting, or diff checks |
 | `stop` | When the agent attempts to finish | Tests, build checks, and advisory review |
+| `push` | Explicit local run or opt-in Git pre-push hook | Full integration and platform suites |
 | `ci` | Protected hosted workflow | Authoritative uncached and waiver-free verification |
 
 1. `SessionStart` tells the coding agent which required gates exist.
 2. The prompt hook records the user's goal as review evidence.
 3. Before tool execution, agent attempts to edit the contract or create a
    waiver are denied.
-4. After tool execution, `change` gates run and fresh results are injected.
+4. After a main-agent tool execution, `change` gates run and fresh results are
+   injected. Subagent tool and stop events are ignored because their working
+   tree may be intentionally transient.
 5. Before compaction, the completion policy is restated.
 6. At `Stop` / `AfterAgent`, required `stop` gates block completion. The agent
-   receives precise evidence and may repair the code a bounded number of times.
+   receives compact evidence and may repair the code a bounded number of times.
+   ConstraintLoop defers this evaluation while background tasks or scheduled
+   wakeups are active. Full retained output remains available through
+   `constraintloop debug ID`.
 7. Advisory failures require either passing fresh evidence or an explicit
    snapshot-bound explanation; delivery alone never counts as review.
 8. Repeated required failure stops autonomous repair and requests a human
@@ -242,6 +264,12 @@ advisory until their false-positive and false-negative rates are measured.
    is human.
 9. `constraintloop ci` reruns every CI gate without local evidence or waivers.
 
+Every command constraint has a finite timeout (300 seconds by default). On POSIX,
+timeout cleanup terminates the entire spawned process group so TestContainers,
+Docker clients, and other descendants cannot keep inherited output pipes open.
+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
@@ -252,8 +280,12 @@ 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.
+`init` and `setup` add local state, the uninstall tombstone, generated agent hook
+settings, and overlay names to the selected project's `.gitignore`, and warn if
+state is already tracked. Claude uses its dedicated
+`.claude/settings.local.json` path. Explicit uninstall records a local tombstone,
+so a checkout that restores old committed hook wiring does not silently
+reactivate ConstraintLoop; setup clears the tombstone.
 
 ### Verdicts and what they mean
 
@@ -270,19 +302,25 @@ selected project's `.gitignore`, and warn if state is already tracked.
 ## Commands
 
 - `constraintloop init` — generate a reviewable initial contract.
-- `constraintloop setup --adapter claude|codex|gemini|all` — merge hook entries
-  while preserving existing hooks.
+- `constraintloop setup --adapter claude|codex|gemini|all [--pre-push]` — merge
+  agent hook entries while preserving existing hooks; optionally install an
+  owned Git pre-push hook for `push` gates.
 - `constraintloop uninstall --adapter claude|codex|gemini|all` — remove only
-  ConstraintLoop hook entries while preserving unrelated settings.
-- `constraintloop run --phase change|stop` — run local gates with fresh caching.
+  ConstraintLoop hook entries while preserving unrelated settings; pass
+  `--pre-push` to remove an owned Git hook too.
+- `constraintloop run --phase change|stop|push` — run local gates with fresh
+  caching. Push gates do not honor local waivers.
 - `constraintloop ci` — authoritative, uncached, waiver-free run.
 - `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|ci` — show why each constraint
+- `constraintloop explain --phase change|stop|push|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
@@ -303,7 +341,7 @@ selected project's `.gitignore`, and warn if state is already tracked.
 - `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
@@ -338,7 +376,7 @@ responses become `uncertain`; a required rubric therefore fails closed.
 
 ## Compatibility boundary
 
-The supported v0.3 surfaces are the CLI and exit codes, configuration schema,
+The supported v0.4 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.
@@ -358,7 +396,8 @@ policy. ConstraintLoop records which contract ran, which inputs it covered, and
 whether the evidence is still fresh.
 
 **Why do some constraints run after every action?** Put only fast feedback in
-the `change` phase. Expensive tests and reviews belong in `stop` and `ci`.
+the `change` phase. Keep unit checks in `stop`; put heavyweight integration
+suites in `push` and `ci`.
 
 **Can I use Codex or Claude Code instead of an API evaluator?** Yes. The native
 evaluator adapter prefers the active supported CLI and remains read-only.

constraintloop-0.5.0/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.3.1 → constraintloop-0.5.0}/docs/configuration.md

@@ -22,6 +22,7 @@ Settings default to:
 | `max_auto_retries` | 2 | 0–20 |
 | `concurrency` | 4 | 1–32 |
 | `evidence_output_limit` | 65536 | 1024–1048576 bytes |
+| `hook_output_limit` | 4096 | 512–32768 bytes |
 | `evaluation_bundle_limit` | 102400 | 4096–2097152 bytes |
 | `progress_interval_seconds` | 15 | 0.1–300 seconds |
 
@@ -37,9 +38,13 @@ 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
+`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.
 
@@ -63,18 +68,29 @@ retry:
 
 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
+Every attempt is capped by the constraint's normal timeout, which defaults to
+300 seconds and is always finite. On POSIX, a timeout terminates the entire
+spawned process group, including descendants that inherited the command's output
+pipes. 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.
+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
@@ -89,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.
 
@@ -133,4 +153,20 @@ 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.
+Hook responses use `hook_output_limit` to retain failing test names and the first
+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.