constraintloop 0.4.1__tar.gz → 0.5.0__tar.gz

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

@@ -5,6 +5,37 @@ 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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: constraintloop
-Version: 0.4.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 |
@@ -351,8 +357,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 +384,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.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 |
@@ -308,8 +314,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 +341,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.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.4.1 → constraintloop-0.5.0}/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.

constraintloop-0.5.0/docs/convergence-loops.md

@@ -0,0 +1,370 @@
+# Bounded convergence loops
+
+Bounded convergence loops are part of the ConstraintLoop v0.1 release scope.
+They connect completion evidence to repeated agent work and delayed external
+state without turning ConstraintLoop into another general-purpose agent
+runtime.
+
+## Product boundary
+
+ConstraintLoop owns the state machine, evidence, budgets, locking, and stop
+decision. Claude Code, Codex, or Gemini CLI may perform a repair after
+ConstraintLoop requests one. A native scheduler may wake the workflow.
+
+Neither the agent nor the scheduler decides that work is complete. Only a fresh
+contract evaluation can do that.
+
+The first release will not launch provider CLIs for repair turns, manage
+provider credentials, or implement a general autonomous task queue. An
+explicitly configured command evaluator may invoke one isolated, read-only
+Codex or Claude Code review and return the existing evaluator protocol. The
+loop engine itself remains provider-neutral.
+
+## Loop types
+
+### Completion
+
+Runs during an active coding session. A failed required gate produces one
+focused repair instruction. Passing evidence stops the loop once any configured
+session challenge gate is also satisfied.
+
+### Monitor
+
+Polls delayed deterministic evidence such as CI, deployments, integration
+environments, or review state. Unchanged pending evidence waits without calling
+a model.
+
+### Maintenance
+
+Starts an independent contract run on a recurring schedule, usually through
+Claude/Codex scheduled tasks or CI. Examples include mutation testing,
+dependency audits, and coverage regression checks.
+
+## Contract shape
+
+The v0.1 schema is:
+
+```yaml
+loops:
+  completion:
+    phase: stop
+    interval_seconds: 10
+    max_repair_attempts: 3
+    max_unchanged_repairs: 2
+    max_duration_seconds: 1200
+    on_pass: stop
+    on_failure: repair
+    on_pending: wait
+    on_budget_exhausted: human_required
+
+  ci_watch:
+    phase: ci
+    interval_seconds: 120
+    max_repair_attempts: 2
+    max_unchanged_repairs: 1
+    max_duration_seconds: 2700
+    on_pass: stop
+    on_failure: repair
+    on_pending: wait
+    on_budget_exhausted: human_required
+```
+
+All fields are explicit and schema-validated. There is no unbounded mode.
+
+Commands that monitor asynchronous state can declare pending exit codes. The
+default convention reserves exit code `75` for a temporary pending result:
+
+```yaml
+constraints:
+  deployment:
+    kind: command
+    command: [scripts/deployment-status]
+    success_codes: [0]
+    pending_codes: [75]
+    phases: [stop, ci]
+```
+
+Pending is neither pass nor failure. It never authorizes completion and never
+consumes a repair attempt.
+
+## Cycle protocol
+
+`constraintloop cycle NAME --json` executes exactly one transition. It does not
+sleep and does not launch an agent.
+
+```json
+{
+  "schema_version": 1,
+  "loop": "ci_watch",
+  "state": "repair",
+  "snapshot": "sha256:...",
+  "observation": 4,
+  "repair_attempt": 1,
+  "next_action": "Repair the failing required constraints, then run one cycle.",
+  "wake_after_seconds": 0,
+  "blocking_constraints": ["integration_tests"]
+}
+```
+
+States are:
+
+- `passed`: fresh required evidence passes; stop.
+- `repair`: new repairable failure; allow one focused agent turn.
+- `waiting`: evidence is pending or unchanged without an attempted repair.
+- `human_required`: unchanged repairs or policy require a human decision.
+- `budget_exhausted`: attempts or elapsed time reached a hard limit.
+- `error`: ConstraintLoop could not evaluate the contract reliably.
+- `challenge`: the current coding session must generate domain-grounded scenarios.
+- `verify`: the current coding session must investigate recorded scenarios and
+  submit evidence for unresolved or stale outcomes.
+
+Exit codes will remain stable for automation:
+
+| Code | State |
+| ---: | --- |
+| 0 | passed |
+| 10 | repair |
+| 11 | waiting |
+| 12 | human required |
+| 13 | budget exhausted |
+| 14 | engine error |
+| 15 | challenge discovery |
+| 16 | challenge verification |
+
+## Supervisor
+
+`constraintloop supervise NAME` repeatedly calls the same state machine while
+holding a project lease. It polls deterministic constraints locally and emits
+JSON Lines when state changes.
+
+The supervisor does not launch coding agents. On `repair`, `challenge`, or
+`verify`, it exits with code 10, 15, or 16 so the native session or another
+explicit controller can perform the requested work. Optional native rubric evaluators are
+single-shot, tool-disabled reviews and cannot perform a repair transition.
+
+The supervisor:
+
+- use a single-writer lease under `.constraintloop/state/loops/`;
+- recover leases after a bounded TTL;
+- handle cancellation signals;
+- never count polling observations as repair attempts;
+- avoid rerunning unchanged expensive evidence before its configured interval;
+- journal transitions atomically;
+- redact secrets and cap retained output;
+- stop at every attempt and duration budget.
+
+## Native integration
+
+`constraintloop loop-prompt NAME --adapter claude|codex|gemini` prints a durable
+prompt that tells the native agent to:
+
+1. run one cycle;
+2. follow only the returned `next_action`;
+3. make at most one repair per `repair` transition;
+4. make no edits while `waiting`;
+5. stop on `passed`, `human_required`, `budget_exhausted`, or `error`;
+6. never edit the contract or create a waiver.
+7. perform `challenge` and `verify` work in the current session, read the saved
+   request with `challenge show`, and submit evidence with `challenge submit`.
+
+The generated prompt can be copied into a Claude Code, Codex, or Gemini CLI session. It
+is provider-neutral except for adapter-specific command framing. ConstraintLoop
+does not create account-level scheduled tasks or launch either provider CLI.
+
+## Session challenge gates
+
+An optional `challenge` block on a Stop-phase loop requires the current coding
+session to explore failure scenarios before completion. The session supplies
+its existing context, reasoning, and tools. ConstraintLoop does not call an
+evaluator or launch another agent for this gate. Separately configured rubric
+constraints still run normally.
+
+```yaml
+loops:
+  completion:
+    phase: stop
+    interval_seconds: 10
+    max_repair_attempts: 3
+    max_unchanged_repairs: 2
+    max_duration_seconds: 1200
+    challenge:
+      count: 10
+      max_rounds: 2
+      max_continuations: 8
+      watch: ["src/**/*.py", "tests/**/*.py", "docs/**/*.md", README.md]
+      domain_context: [README.md, "docs/**/*.md"]
+```
+
+Install the existing hooks with `constraintloop setup --adapter all`, or use
+`loop-prompt` for a specific adapter. The same state machine serves every agent:
+
+| Agent | Completion event | Continue current session | Budget exhausted |
+| --- | --- | --- | --- |
+| Claude Code | `Stop` | `decision: block` with reason | `continue: false` |
+| Codex | `Stop` | `decision: block` with reason | `continue: false` |
+| Gemini CLI | `AfterAgent` | `decision: deny` with reason | `continue: false` |
+
+These responses follow the official [Claude Code hooks](https://code.claude.com/docs/en/hooks#stop),
+[Codex hooks](https://learn.chatgpt.com/docs/hooks#stop), and
+[Gemini CLI hooks](https://geminicli.com/docs/hooks/reference/#afteragent) protocols.
+Challenge-enabled loops recheck recursive completion events against their
+persisted budgets. Other loops retain the legacy recursive-hook guard.
+Generated continuation feedback does not replace the saved user goal.
+
+Run `constraintloop cycle completion --json`. After required checks pass, the
+cycle returns `challenge`. `constraintloop challenge show completion` returns
+the goal, context paths, current request ID and input snapshot, saved scenarios,
+and the exact JSON submission schema. The session reads the relevant domain
+sources and produces a discovery submission:
+
+```json
+{
+  "kind": "discovery",
+  "request_id": "COPY_FROM_CHALLENGE_SHOW",
+  "input_snapshot": "COPY_FROM_CHALLENGE_SHOW",
+  "domain_summary": "Pending evidence must never authorize completion.",
+  "domain_sources": ["docs/convergence-loops.md"],
+  "challenges": [
+    {
+      "id": "r1-c1",
+      "perspective": "recovery",
+      "assumption": "Pending state survives process restarts.",
+      "scenario": "Restart the supervisor while its evidence is pending.",
+      "expected_behavior": "The restarted supervisor waits and does not pass.",
+      "verification_plan": "Run the restart regression in the tests gate.",
+      "source_refs": ["docs/convergence-loops.md"]
+    }
+  ]
+}
+```
+
+The example contains one scenario; submit exactly `count` scenarios per round.
+At least three distinct perspective labels are required, or `count` when it is
+smaller. IDs and normalized scenario text must be unique across every round.
+Source references must name existing files covered by challenge `watch` or
+`domain_context`; references are project-relative paths, without line suffixes.
+The prompt requests distinct failure mechanisms and rejects invented domain
+requirements. Structural checks cannot establish semantic diversity or creativity.
+
+Save the submission under the gitignored `.constraintloop/state/` directory, then run:
+
+```bash
+constraintloop challenge submit completion --file .constraintloop/state/discovery.json
+constraintloop cycle completion --json
+constraintloop challenge show completion
+```
+
+The cycle now returns `verify`. The session investigates the scenarios using
+existing tests, new regression tests, and other domain-appropriate evidence.
+Submit a verification document using the current request ID and input snapshot:
+
+```json
+{
+  "kind": "verification",
+  "request_id": "COPY_FROM_CHALLENGE_SHOW",
+  "input_snapshot": "COPY_FROM_CHALLENGE_SHOW",
+  "resolutions": [
+    {
+      "challenge_id": "r1-c1",
+      "outcome": "verified",
+      "evidence": "The restart regression asserts that pending state remains blocking.",
+      "constraint_ids": ["tests"],
+      "source_refs": ["tests/test_loops.py"]
+    }
+  ]
+}
+```
+
+Verification can be submitted in batches. `verified` requires at least one
+enabled deterministic Stop constraint ID; the cycle checks that every cited
+gate passes. A waiver, skipped result, rubric verdict, or the session's claim
+alone does not satisfy this check. `defect` requests a focused repair;
+`unresolved` continues verification; `rejected` requires a written explanation
+and watched source references. Rejections are recorded self-review judgments,
+not independently proven dispositions. The session must explain why the cited
+checks or source evidence actually address the scenario.
+
+Accepted discovery plans cannot be replaced through the submission protocol.
+Every accepted submission rotates the request token to reject stale replays.
+Changes to the goal, contract, constraint inputs, or watched domain/source files
+invalidate prior verification. After edits, run one cycle to refresh the
+snapshot before submitting evidence. A source change during evaluation prevents
+completion until a fresh evaluation. Keep generated reports outside the watched
+set; `.constraintloop/` is excluded automatically.
+
+After repairs or input changes, resolving the current scenarios starts a fresh
+discovery round if `max_rounds` allows it. Earlier scenarios remain recorded.
+The round cap limits further exploration; it never excuses unresolved scenarios.
+An unchanged successful round can pass immediately. A new goal or changed inputs
+after completion starts a new challenge run.
+
+Discovery and verification do not consume repair attempts. Each hook-requested
+continuation for challenge, verification, or repair consumes the separate
+`max_continuations` budget. Reading requests, submitting results, and polling
+cycles do not consume that budget. The time budget bounds the entire loop;
+repair and unchanged-repair budgets still apply. Journals and budgets survive
+session restarts, and startup/compaction hooks point back to the saved work.
+Native runtimes may impose their own continuation caps; the generated loop
+prompt lets the session perform several steps before another completion event.
+
+This gate applies to completion loops and their hooks. `constraintloop run`
+evaluates ordinary constraints; use `cycle` to evaluate the full completion
+decision. Challenge configuration on a non-Stop loop is rejected. CI continues
+to execute committed constraints without trusting local challenge judgments.
+This is evidence-backed self-review, with the author's potential blind spots;
+it does not provide independent model review or exhaustive correctness proof.
+
+## Snapshot and accounting rules
+
+The snapshot includes the contract digest plus each applicable constraint ID,
+input digest, verdict, and normalized findings. A repair attempt is consumed
+only when:
+
+1. the prior transition returned `repair`; and
+2. a later cycle observes the result of that agent turn.
+
+Repeated polling of the same pending snapshot increments observations but not
+repair attempts. A changed source or external-evidence snapshot resets the
+unchanged-repair counter, but not the total duration budget.
+
+Required non-deterministic rubrics retain their existing quorum rules. Repeating
+a rubric until it happens to pass is forbidden; all configured runs belong to
+one evaluation and one snapshot.
+
+Advisory feedback is actionable but does not require a passing verdict. A Stop
+transition remains blocked until the agent either changes the evidence and a
+fresh review passes, or records an explicit explanation with `constraintloop
+acknowledge`. The explanation is bound to the exact input, verdict, rationale,
+and findings; changed feedback requires a new disposition. Acknowledgment never
+changes the verdict and is not a waiver.
+
+## First-release acceptance criteria
+
+- The schema rejects unknown loop fields, missing referenced phases, zero
+  budgets, and unbounded configurations.
+- `cycle` produces stable structured output and exit codes for every state.
+- Pending evidence cannot pass the contract or consume repairs.
+- Identical polling does not invoke an evaluator or consume repair attempts.
+- Changed evidence invalidates the prior transition.
+- Attempt and time budgets survive process restarts.
+- A second supervisor cannot acquire an active project lease.
+- A stale lease is safely recoverable.
+- SIGINT/SIGTERM release the lease and preserve the journal.
+- Claude and Codex prompt fixtures follow the same provider-neutral protocol.
+- Stop hooks and cycles share one attempt ledger rather than double-counting.
+- CI continues to ignore local waivers and cached evidence.
+- The ConstraintLoop repository dogfoods a bounded completion-loop
+  configuration before v0.1 is tagged.
+
+## Implementation sequence
+
+1. Add `PENDING`, `pending_codes`, and strict loop models.
+2. Extract the current Stop retry accounting into a shared loop state machine.
+3. Implement atomic journals, leases, snapshots, and budget accounting.
+4. Add `cycle` with stable JSON and exit codes.
+5. Add the deterministic `supervise` process.
+6. Generate Claude and Codex native prompts.
+7. Connect Stop hooks to the same completion loop.
+8. Add integration tests for restart, locking, pending, cancellation, and
+   unchanged evidence.
+9. Enable and exercise the completion loop in this repository.