grounding-gate 0.1.0__tar.gz

grounding_gate-0.1.0/.gitattributes

@@ -0,0 +1 @@
+* text=auto eol=lf

grounding_gate-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,31 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest]
+        python-version: ["3.9", "3.13"]
+        include:
+          - os: windows-latest
+            python-version: "3.13"
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: pip install -e ".[dev]"
+      - name: Test suite
+        run: pytest -q
+      - name: Zero-dependency check (tests run on bare python)
+        run: python tests/test_gate.py
+      - name: Demo
+        run: python examples/demo.py

grounding_gate-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,44 @@
+name: release
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - name: Test
+        run: |
+          pip install -e ".[dev]"
+          pytest -q
+      - name: Build sdist and wheel
+        run: |
+          pip install build twine
+          python -m build
+          twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    # Trusted Publishing (OIDC): configure this repo + workflow + environment
+    # as a (pending) publisher for the project on pypi.org — no API token.
+    environment:
+      name: pypi
+      url: https://pypi.org/p/grounding-gate
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

grounding_gate-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+dist/
+build/
+.venv/
+venv/
+.idea/
+.vscode/

grounding_gate-0.1.0/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+## 0.1.0 — 2026-07-10
+
+Initial release.
+
+- `classify_observation` — novelty ∧ relevance ∧ consequence-tier observation
+  classifier (corrected C1/C3 behavior preserved from review).
+- `boundary_check` / `turn_loop` — submit-boundary choke point and reference
+  loop wiring (latched flags, qualifying-only halt clear, starving refusals).
+- `GateState.for_model_class` with `skipper` / `diverger` / `default` presets,
+  including strict-G enforcement for the skipper class (assertions require
+  verified-tier grounding).
+- 19-case acceptance suite, runnable on bare Python with zero dependencies.

grounding_gate-0.1.0/LICENSE

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

grounding_gate-0.1.0/PKG-INFO

@@ -0,0 +1,194 @@
+Metadata-Version: 2.4
+Name: grounding-gate
+Version: 0.1.0
+Summary: Zero-token structural verifier for agent loops: one choke point at the submit boundary enforcing grounding and budget invariants. No LLM calls, stdlib only.
+Project-URL: Homepage, https://github.com/CiphemonJY/grounding-gate
+Project-URL: Repository, https://github.com/CiphemonJY/grounding-gate
+Project-URL: Issues, https://github.com/CiphemonJY/grounding-gate/issues
+Project-URL: Changelog, https://github.com/CiphemonJY/grounding-gate/blob/main/CHANGELOG.md
+Author: Ciphemon
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent-loop,agents,grounding,guardrails,hallucination,llm,verification
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# grounding-gate
+
+[![ci](https://github.com/CiphemonJY/grounding-gate/actions/workflows/ci.yml/badge.svg)](https://github.com/CiphemonJY/grounding-gate/actions/workflows/ci.yml)
+
+**Zero-token structural verifier for agent loops.** One choke point at the
+submit boundary decides whether an agent is allowed to say "X is true" or
+"I did X" — using hash, set, and integer operations only. No LLM calls, no
+per-turn prompt injection, no dependencies.
+
+```
+pip install grounding-gate      # stdlib only, Python >= 3.9
+```
+
+The demo ships in the repo (not the wheel):
+
+```
+git clone https://github.com/CiphemonJY/grounding-gate && cd grounding-gate
+python examples/demo.py         # the whole idea in 30 seconds
+```
+
+## The problem
+
+Agents fail in two characteristic ways, and both ship *confident* wrong answers:
+
+- **Skip-and-hallucinate** — emit a terminal claim ("done, config fixed")
+  without ever observing reality after acting on it.
+- **Reason-and-diverge** — loop in closed context, burning steps on
+  reasoning about stale beliefs, until a confident wrong answer ships.
+
+The standard fix is prose: "remember to verify your work" injected into every
+turn. Prose costs tokens on every turn, behaves differently per model, and —
+critically — is *skippable*. A reminder is not an invariant.
+
+## The idea
+
+Move enforcement out of the prompt and into **control flow**. A single gate
+wraps the submit/conclude boundary, and a terminal output is emitted only if
+both invariants hold:
+
+- **G (grounding)** — a *qualifying* observation happened this turn, or the
+  output makes no factual claim. Qualifying means **novel** (result hash not
+  seen before, after stripping timestamps/ids) **∧ relevant** (touches the
+  identifiers the claim is about) **∧ consequence-tier-correct** (see below).
+- **B (budget)** — reasoning rope remains. Qualifying observations *refill*
+  the budget (up to a cap); pure reasoning steps decrement it. Grounded work
+  runs effectively unbounded; closed-loop reasoning hits a hard floor.
+
+Fail either → the terminal is **rejected** and the agent is told its only
+legal moves: make a qualifying tool call, or exit with a typed **`unverified`**
+terminal. `unverified` is a first-class, always-legal escape hatch — the gate
+never traps an agent, it only forbids *confident* ungrounded claims.
+
+### Consequence tiers
+
+The gate distinguishes what kind of claim an observation can support:
+
+| Claim type   | Example                  | Requires |
+|--------------|--------------------------|----------|
+| `assertion`  | "X is true"              | a novel, relevant, read-only observation this turn |
+| `completion` | "I changed X"            | a novel, relevant read taken **after** the mutation — a mutating call never self-grounds its own effect |
+| `unverified` | "couldn't confirm X"     | nothing — always legal |
+| `none`       | no factual claim         | nothing — exempt |
+
+That second row is the heart of it: *writing a file and claiming success is
+not verification; reading it back afterwards is.*
+
+## Quickstart
+
+```python
+from grounding_gate import GateState, classify_observation, boundary_check
+
+state = GateState.for_model_class("default", claim_surface={"app.cfg"})
+
+# after EVERY tool call in your agent loop:
+state.current_step += 1
+obs = classify_observation(tool, args, result, state, read_only=not mutating)
+state.grounded_this_turn |= obs["grounds_assertion"]
+state.verified_this_turn |= obs["grounds_completion"]
+if mutating:
+    state.last_mutation_step = state.current_step   # a completion now needs a read AFTER this
+
+# at every submit/conclude attempt — this must be the ONLY path to output:
+verdict = boundary_check({"claim_type": "completion", "content": answer}, state)
+if verdict["verdict"] == "REJECT":
+    ...  # surface verdict["legal_next"] to the model and continue the loop
+```
+
+Note the mutation bookkeeping: without `last_mutation_step` ever being set, no
+read can reach the verified tier and a `completion` can never be accepted —
+that is the gate working as designed, not a bug.
+
+`turn_loop` in [boundary.py](https://github.com/CiphemonJY/grounding-gate/blob/main/src/grounding_gate/boundary.py)
+is the complete reference wiring (budget refill, mutation tracking, halt
+semantics, signal mapping) — use it as the integration template. The
+[demo](https://github.com/CiphemonJY/grounding-gate/blob/main/examples/demo.py)
+runs the same scripted agent through an ungated and a gated loop, side by side.
+
+## Model-class presets
+
+Fleet variance is absorbed as integers, not prose. Pick the preset matching
+how your model fails:
+
+| Preset     | CAP | REFILL | Strict G | For |
+|------------|-----|--------|----------|-----|
+| `skipper`  | 5   | 2      | yes      | models that hallucinate-and-skip |
+| `diverger` | 4   | 1      | no       | models that reason forever |
+| `default`  | 6   | 2      | no       | everything else |
+
+Strict G means even plain *assertions* require verified-tier grounding (a
+post-mutation observation) — an observed-tier read is not enough. In a task
+that never mutates anything, a strict-G agent can only exit via the typed
+`unverified` terminal; that hard line is the point of the skipper preset, so
+pick `default` for read-only/Q&A workloads.
+
+## Declarative rails
+
+A task can declare signals that must be verified before any completion is
+accepted (`state.goal_predicates = ["tests_passed"]`). The gate never
+interprets meaning — it only checks that a signal named `tests_passed` was
+registered by a mapped, real command outcome. Semantic judgment stays out of
+the floor by design.
+
+## What the gate does NOT do
+
+Honest scope, from the design's leak audit:
+
+- **No semantic correctness.** A grounded claim can still be wrong (the model
+  can misread a real result). That is punted to a declared verifier tier
+  (`verify_with`), not smuggled into the floor.
+- **Relevance can be spoofed** by a model that deliberately mentions the right
+  identifiers in an irrelevant call. The floor defends against *lazy*
+  ungroundedness, which is the overwhelmingly common failure; adversarial
+  self-deception needs the verifier tier.
+- **Nondeterministic tools** need per-tool `normalize()` extensions or the
+  audited `novelty_exempt` allowlist — too-weak normalization quietly disables
+  the no-op defense.
+
+## How this was built
+
+The modules were drafted by different LLMs and adversarially reviewed before
+assembly; the final behavior is pinned by a 19-case acceptance suite
+([tests/test_gate.py](https://github.com/CiphemonJY/grounding-gate/blob/main/tests/test_gate.py))
+that runs on bare Python with zero dependencies. Two review findings shaped
+the method and are preserved in the docstrings:
+
+- A drafting model shipped a consequence-tier bug **and authored the test that
+  ratified it** — since then, expected outcomes are authored by the reviewer,
+  never by the generator
+  ([docs/module-2-classifier.md](https://github.com/CiphemonJY/grounding-gate/blob/main/docs/module-2-classifier.md)).
+- The remaining leaks lived *between* individually-passing test cases —
+  latch-vs-assignment, halt cleared by non-qualifying calls
+  ([docs/module-4-boundary.md](https://github.com/CiphemonJY/grounding-gate/blob/main/docs/module-4-boundary.md)).
+
+Full design spec:
+[docs/spec.md](https://github.com/CiphemonJY/grounding-gate/blob/main/docs/spec.md).
+
+## Status & roadmap
+
+This is the reference implementation — correct, minimal, and framework-free.
+Planned next:
+
+- Adapters: Claude Agent SDK hook, LangGraph middleware, OpenAI Agents SDK.
+- A real signal-mapper module (command exit code → declared signal).
+- Empirical preset tuning across model classes.
+
+## License
+
+MIT

grounding_gate-0.1.0/README.md

@@ -0,0 +1,168 @@
+# grounding-gate
+
+[![ci](https://github.com/CiphemonJY/grounding-gate/actions/workflows/ci.yml/badge.svg)](https://github.com/CiphemonJY/grounding-gate/actions/workflows/ci.yml)
+
+**Zero-token structural verifier for agent loops.** One choke point at the
+submit boundary decides whether an agent is allowed to say "X is true" or
+"I did X" — using hash, set, and integer operations only. No LLM calls, no
+per-turn prompt injection, no dependencies.
+
+```
+pip install grounding-gate      # stdlib only, Python >= 3.9
+```
+
+The demo ships in the repo (not the wheel):
+
+```
+git clone https://github.com/CiphemonJY/grounding-gate && cd grounding-gate
+python examples/demo.py         # the whole idea in 30 seconds
+```
+
+## The problem
+
+Agents fail in two characteristic ways, and both ship *confident* wrong answers:
+
+- **Skip-and-hallucinate** — emit a terminal claim ("done, config fixed")
+  without ever observing reality after acting on it.
+- **Reason-and-diverge** — loop in closed context, burning steps on
+  reasoning about stale beliefs, until a confident wrong answer ships.
+
+The standard fix is prose: "remember to verify your work" injected into every
+turn. Prose costs tokens on every turn, behaves differently per model, and —
+critically — is *skippable*. A reminder is not an invariant.
+
+## The idea
+
+Move enforcement out of the prompt and into **control flow**. A single gate
+wraps the submit/conclude boundary, and a terminal output is emitted only if
+both invariants hold:
+
+- **G (grounding)** — a *qualifying* observation happened this turn, or the
+  output makes no factual claim. Qualifying means **novel** (result hash not
+  seen before, after stripping timestamps/ids) **∧ relevant** (touches the
+  identifiers the claim is about) **∧ consequence-tier-correct** (see below).
+- **B (budget)** — reasoning rope remains. Qualifying observations *refill*
+  the budget (up to a cap); pure reasoning steps decrement it. Grounded work
+  runs effectively unbounded; closed-loop reasoning hits a hard floor.
+
+Fail either → the terminal is **rejected** and the agent is told its only
+legal moves: make a qualifying tool call, or exit with a typed **`unverified`**
+terminal. `unverified` is a first-class, always-legal escape hatch — the gate
+never traps an agent, it only forbids *confident* ungrounded claims.
+
+### Consequence tiers
+
+The gate distinguishes what kind of claim an observation can support:
+
+| Claim type   | Example                  | Requires |
+|--------------|--------------------------|----------|
+| `assertion`  | "X is true"              | a novel, relevant, read-only observation this turn |
+| `completion` | "I changed X"            | a novel, relevant read taken **after** the mutation — a mutating call never self-grounds its own effect |
+| `unverified` | "couldn't confirm X"     | nothing — always legal |
+| `none`       | no factual claim         | nothing — exempt |
+
+That second row is the heart of it: *writing a file and claiming success is
+not verification; reading it back afterwards is.*
+
+## Quickstart
+
+```python
+from grounding_gate import GateState, classify_observation, boundary_check
+
+state = GateState.for_model_class("default", claim_surface={"app.cfg"})
+
+# after EVERY tool call in your agent loop:
+state.current_step += 1
+obs = classify_observation(tool, args, result, state, read_only=not mutating)
+state.grounded_this_turn |= obs["grounds_assertion"]
+state.verified_this_turn |= obs["grounds_completion"]
+if mutating:
+    state.last_mutation_step = state.current_step   # a completion now needs a read AFTER this
+
+# at every submit/conclude attempt — this must be the ONLY path to output:
+verdict = boundary_check({"claim_type": "completion", "content": answer}, state)
+if verdict["verdict"] == "REJECT":
+    ...  # surface verdict["legal_next"] to the model and continue the loop
+```
+
+Note the mutation bookkeeping: without `last_mutation_step` ever being set, no
+read can reach the verified tier and a `completion` can never be accepted —
+that is the gate working as designed, not a bug.
+
+`turn_loop` in [boundary.py](https://github.com/CiphemonJY/grounding-gate/blob/main/src/grounding_gate/boundary.py)
+is the complete reference wiring (budget refill, mutation tracking, halt
+semantics, signal mapping) — use it as the integration template. The
+[demo](https://github.com/CiphemonJY/grounding-gate/blob/main/examples/demo.py)
+runs the same scripted agent through an ungated and a gated loop, side by side.
+
+## Model-class presets
+
+Fleet variance is absorbed as integers, not prose. Pick the preset matching
+how your model fails:
+
+| Preset     | CAP | REFILL | Strict G | For |
+|------------|-----|--------|----------|-----|
+| `skipper`  | 5   | 2      | yes      | models that hallucinate-and-skip |
+| `diverger` | 4   | 1      | no       | models that reason forever |
+| `default`  | 6   | 2      | no       | everything else |
+
+Strict G means even plain *assertions* require verified-tier grounding (a
+post-mutation observation) — an observed-tier read is not enough. In a task
+that never mutates anything, a strict-G agent can only exit via the typed
+`unverified` terminal; that hard line is the point of the skipper preset, so
+pick `default` for read-only/Q&A workloads.
+
+## Declarative rails
+
+A task can declare signals that must be verified before any completion is
+accepted (`state.goal_predicates = ["tests_passed"]`). The gate never
+interprets meaning — it only checks that a signal named `tests_passed` was
+registered by a mapped, real command outcome. Semantic judgment stays out of
+the floor by design.
+
+## What the gate does NOT do
+
+Honest scope, from the design's leak audit:
+
+- **No semantic correctness.** A grounded claim can still be wrong (the model
+  can misread a real result). That is punted to a declared verifier tier
+  (`verify_with`), not smuggled into the floor.
+- **Relevance can be spoofed** by a model that deliberately mentions the right
+  identifiers in an irrelevant call. The floor defends against *lazy*
+  ungroundedness, which is the overwhelmingly common failure; adversarial
+  self-deception needs the verifier tier.
+- **Nondeterministic tools** need per-tool `normalize()` extensions or the
+  audited `novelty_exempt` allowlist — too-weak normalization quietly disables
+  the no-op defense.
+
+## How this was built
+
+The modules were drafted by different LLMs and adversarially reviewed before
+assembly; the final behavior is pinned by a 19-case acceptance suite
+([tests/test_gate.py](https://github.com/CiphemonJY/grounding-gate/blob/main/tests/test_gate.py))
+that runs on bare Python with zero dependencies. Two review findings shaped
+the method and are preserved in the docstrings:
+
+- A drafting model shipped a consequence-tier bug **and authored the test that
+  ratified it** — since then, expected outcomes are authored by the reviewer,
+  never by the generator
+  ([docs/module-2-classifier.md](https://github.com/CiphemonJY/grounding-gate/blob/main/docs/module-2-classifier.md)).
+- The remaining leaks lived *between* individually-passing test cases —
+  latch-vs-assignment, halt cleared by non-qualifying calls
+  ([docs/module-4-boundary.md](https://github.com/CiphemonJY/grounding-gate/blob/main/docs/module-4-boundary.md)).
+
+Full design spec:
+[docs/spec.md](https://github.com/CiphemonJY/grounding-gate/blob/main/docs/spec.md).
+
+## Status & roadmap
+
+This is the reference implementation — correct, minimal, and framework-free.
+Planned next:
+
+- Adapters: Claude Agent SDK hook, LangGraph middleware, OpenAI Agents SDK.
+- A real signal-mapper module (command exit code → declared signal).
+- Empirical preset tuning across model classes.
+
+## License
+
+MIT

grounding_gate-0.1.0/docs/module-2-classifier.md

@@ -0,0 +1,75 @@
+# Module 2 — Observation classifier (corrected)
+
+The classifier decides whether one completed tool call `(tool, args, result)` grounds a
+claim. A call qualifies only if **novel ∧ relevant ∧ consequence-tier-correct**.
+
+## Review history — and why it shaped the method
+
+The first draft of this module was produced by one model and reviewed by another. The
+review found:
+
+- **(C1)** The consequence tier let a plain read ground a **completion** ("I changed X")
+  when nothing had ever mutated: with `last_mutation_step = 0`, the step comparison was
+  trivially true. The fix requires a mutation to have *occurred*
+  (`last_mutation_step > 0`) before any read can count as post-mutation verification.
+- **(C2)** The drafting model had also **authored the test case that ratified its own
+  bug** — its test #1 expected `{true, true}` for a read with no prior mutation. The
+  expectation was corrected to `{true, false}`.
+- **(C3)** The draft recorded the novelty hash before the relevance check — a
+  novel-but-irrelevant read burned its hash and was wrongly denied credit if the same
+  read later became relevant. The hash is now recorded only after the relevance gate
+  passes.
+
+C2 is the important lesson, and it became a standing rule for this project: **expected
+outcomes are authored by the reviewer, never by the generator.** A model grading its own
+work will happily certify its own bug.
+
+## Corrected pseudocode
+
+```text
+function classify_observation(tool, args, result, state) -> {grounds_assertion, grounds_completion}:
+    ret = {grounds_assertion: false, grounds_completion: false}
+
+    # 1. NOVELTY (check only; do not record yet — see C3)
+    h = null
+    if tool not in state.novelty_exempt:
+        h = hash(tool + normalize(args) + normalize(result))
+        if h in state.recent_result_hashes:
+            return ret
+
+    # 2. RELEVANCE
+    identifiers = extract_identifiers(args, result)
+    if not intersects(identifiers, state.claim_surface):
+        return ret
+
+    # record novelty only for calls that actually qualify (C3)
+    if h != null:
+        state.recent_result_hashes.add(h)
+
+    # 3. CONSEQUENCE TIER
+    if is_read_only(tool):
+        ret.grounds_assertion = true
+        # a completion needs a mutation to have OCCURRED and this read to follow it (C1)
+        if state.last_mutation_step > 0 and state.current_step > state.last_mutation_step:
+            ret.grounds_completion = true
+
+    return ret
+```
+
+## Acceptance cases
+
+| # | Case | Expected |
+|---|------|----------|
+| T1 | read with NO prior mutation | `{true, false}` ← corrected (C1/C2) |
+| T2 | repeated identical read (novelty defeat) | `{false, false}` |
+| T3 | unrelated file touched (relevance defeat) | `{false, false}` |
+| T4 | mutating call claiming its own effect (consequence defeat) | `{false, false}` |
+| T5 | read predating the mutation | `{true, false}` |
+| T6 | post-mutation re-read (valid verified) | `{true, true}` |
+
+## Open implementation risks (flagged, not resolved here)
+
+- `normalize()` must strip timestamps/rng or novelty never fires on nondeterministic
+  tools; `novelty_exempt` is a small audited allowlist.
+- `extract_identifiers()` must be conservative — over-extraction leaks relevance,
+  under-extraction false-rejects cross-cutting work.

grounding_gate-0.1.0/docs/module-4-boundary.md

@@ -0,0 +1,76 @@
+# Module 4 — Submit-boundary choke point (corrected)
+
+`boundary_check` is the single decision that matters: it must be the **sole path to any
+terminal output**. `turn_loop` is the reference wiring of the whole gate around an agent.
+
+## Review history — leaks live BETWEEN the test cases
+
+The draft of this module passed all 8 authored boundary cases (R1–A3) on the first try —
+`boundary_check` itself survived review unchanged. Every bug was in `turn_loop`, in the
+seams the per-case suite didn't cover:
+
+- **(C1)** The draft assigned grounding flags from the *last* call
+  (`verified_this_turn = obs.grounds_completion`), so any later non-completion-grade call
+  overwrote a valid verification back to `false` — false-rejecting legitimate work.
+  Flags are **latches** within a turn (`|=`), cleared only at turn boundaries.
+- **(C2)** The draft cleared `halted` on *any* tool call — a halted model could escape via
+  a novelty-defeated no-op read, reintroducing the no-op gaming vector at loop level.
+  Halt is cleared **only by a qualifying observation** (or a typed `unverified` exit).
+- **(C3)** The draft invented an `obs.signals` field that Module 2 does not return.
+  Signal population goes through the declarative-rails signal mapper (declared command
+  outcome → signal name), never through the classifier.
+- **(C4)** Refused reasoning while halted must surface `legal_next` to the agent
+  (re-prompt) or the loop livelocks; refusals also decrement budget, so a halted spinner
+  still starves its way to the typed `unverified` exit.
+
+The takeaway generalizes: a module can score 100% on its authored acceptance cases and
+still leak — integration cases (L1–L3 below) exist precisely to cover the seams.
+
+## Corrected pseudocode
+
+```text
+function boundary_check(terminal_attempt, state):
+    ct = terminal_attempt.claim_type          # none | assertion | completion | unverified
+
+    if ct == unverified:                      # universal escape hatch (typed, not content-matched)
+        state.halted = false
+        return { verdict: ACCEPT, legal_next: [] }
+
+    is_claim_bearing = (ct == assertion) OR (ct == completion)
+
+    if is_claim_bearing AND state.budget <= 0:
+        state.halted = true
+        return { verdict: REJECT, legal_next: [qualifying_tool_call, unverified_terminal] }
+
+    if ct == completion:
+        if NOT state.verified_this_turn:
+            reject as above
+        for sig in state.goal_predicates:
+            if sig NOT in state.verified_signals:
+                reject as above
+        state.halted = false
+        return { verdict: ACCEPT, legal_next: [] }
+
+    if ct == assertion:
+        grounded = state.verified_this_turn if state.strict_g    # strict G (module 6):
+                   else state.grounded_this_turn                 # skipper preset requires
+        if NOT grounded:                                         # verified tier even here
+            reject as above
+        state.halted = false
+        return { verdict: ACCEPT, legal_next: [] }
+
+    return { verdict: ACCEPT, legal_next: [] }   # ct == none: exempt
+```
+
+`turn_loop` wiring (see [boundary.py](../src/grounding_gate/boundary.py) for the runnable
+version): reasoning decrements budget (refused or not); tool calls are classified, latch
+the flags, refill budget and clear halt only when qualifying, and record mutation steps;
+terminal attempts go through `boundary_check`, and an ACCEPT is the loop's only emit.
+
+## Integration cases the corrections cover
+
+| # | Case | Verdict |
+|---|------|---------|
+| L1 | edit → re-read (verified) → novelty-defeated repeat read → completion | ACCEPT (was falsely REJECTED pre-C1) |
+| L2 | halted → novelty-defeated repeat read → reasoning | reasoning still refused (was allowed pre-C2) |
+| L3 | halted → reasoning × N | budget starves to typed `unverified` (was free spin pre-C4) |