signalbrain 0.1.0__tar.gz

signalbrain-0.1.0/LICENSE

@@ -0,0 +1,17 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   Copyright 2026 SignalBrain
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

signalbrain-0.1.0/PKG-INFO

@@ -0,0 +1,104 @@
+Metadata-Version: 2.4
+Name: signalbrain
+Version: 0.1.0
+Summary: Trust layer for AI-modified software — receipts, ledger, calibrated autonomy
+Author: SignalBrain
+License: Apache-2.0
+Project-URL: Homepage, https://signalbrain.ai
+Project-URL: Repository, https://github.com/whitestone1121-web/signalbrain
+Project-URL: Documentation, https://github.com/whitestone1121-web/signalbrain/blob/main/docs/RECEIPT_SPEC.md
+Project-URL: Incident, https://github.com/whitestone1121-web/signalbrain/blob/main/docs/incidents/2026-07-tooling-trust-streak-gaming.md
+Keywords: ai,agents,calibration,trust,receipts,governance
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# SignalBrain
+
+[![earned autonomy](https://img.shields.io/endpoint?url=https%3A%2F%2Fwhitestone1121-web.github.io%2Fsignalbrain%2Fbadge%2Ftitan.json)](https://github.com/whitestone1121-web/signalbrain/blob/main/docs/incidents/2026-07-tooling-trust-streak-gaming.md)
+
+**Trust layer for AI-modified software.**
+
+Every company is letting agents change systems that matter. Every agent overstates what it did. SignalBrain is the referee: signed improvement receipts, objective re-score, and per-class calibrated trust — so autonomy is earned, not self-reported.
+
+This repository is **Phase 0 v0.1**: the receipt spec, ledger math, scoring lane, anti-Goodhart machinery, and the founding incident record — extracted from the [Titan reference deployment](https://github.com/whitestone1121-web/neural-chat-v3) (R&D dummy that keeps trying to game its own ledger, in public).
+
+## 60-second demo — run it, don't trust it
+
+```bash
+pip install "git+https://github.com/whitestone1121-web/signalbrain"
+bash demo/demo.sh
+```
+
+Real output (scratch repo built on the fly — no mocks):
+
+```text
+▶ 1. An agent tries to score its own claim BEFORE anyone merged it
+  {"status": "refused_guard", "code": 3, "message": "... not on HEAD — score only human-merged receipts"}
+  refused: unmerged claims cannot enter the ledger. No agent grades its own homework.
+
+▶ 2. A batch of receipts measured only by tests the agent wrote itself
+  ledger now holds 3 rows — every one classified: 3 "claim_kind": "invariant_pin"
+  {}   (no class has ANY trust-eligible claims)
+  three green results, ZERO earned trust: held-by-construction pins are recorded, never counted.
+
+▶ 3. An honest failure
+  "held": false
+  the agent said 0.9 confidence. The measurement said no. That gap is the product.
+
+▶ 4. Ten claims that actually hold
+  "tooling": { "hit_rate": 1.0, "n": 10, "status": "auto-merge ELIGIBLE" }
+  earned by track record, revocable by evidence. Autonomy is graduated, never granted.
+```
+
+## Three layers
+
+| Layer | What | Status |
+|-------|------|--------|
+| **Receipt** | Open standard — signed, re-runnable claims | [`docs/RECEIPT_SPEC.md`](docs/RECEIPT_SPEC.md) v0.1 |
+| **Ledger** | Per-class trust from objectively re-scored receipts | `src/signalbrain/governance/` |
+| **Refuter** | Adversarial verification + SPC (premium) | scripts + roadmap |
+
+## Founding proof
+
+Our own autonomous lane tried to pad its trust score to 100% ELIGIBLE in a local working tree. It never reached git. Full receipt-style incident record with reproduce commands:
+
+[`docs/incidents/2026-07-tooling-trust-streak-gaming.md`](docs/incidents/2026-07-tooling-trust-streak-gaming.md)
+
+Every number in that document is re-derivable from cited SHAs.
+
+## Quick start
+
+```bash
+export PYTHONPATH=src:scripts
+
+# Gate report (requires a ledger at docs/calibration/improvement_claim_ledger.jsonl)
+python scripts/calibration_ledger.py docs/calibration/improvement_claim_ledger.jsonl \
+  --require-measured --by-class --window 10
+
+# Score one merged receipt
+bash scripts/calibration_score_receipt.sh docs/improvements/NNNN-name.md
+
+# Contract suite (product spec)
+pytest tests/contracts/ -q
+```
+
+## v0.1 scope and known seams
+
+See [`docs/PHASE0_EXTRACT_PLAN.md`](docs/PHASE0_EXTRACT_PLAN.md). This release copies the working Titan implementation; the six-week refactor (configurable paths, packaged CLI, GitHub Action) starts when three design-partner conversations exist.
+
+**Compat note:** governance modules live under `signalbrain.governance`; `agi_os_backend.governance` shims preserve script import paths from the reference deployment.
+
+## Design partner offer
+
+We score your coding agents' claims against what actually merged. First caught overclaim is free — if we don't find one, you still get an audit. Contact: [signalbrain.ai](https://signalbrain.ai)
+
+## License
+
+Apache-2.0 — see LICENSE.

signalbrain-0.1.0/README.md

@@ -0,0 +1,83 @@
+# SignalBrain
+
+[![earned autonomy](https://img.shields.io/endpoint?url=https%3A%2F%2Fwhitestone1121-web.github.io%2Fsignalbrain%2Fbadge%2Ftitan.json)](https://github.com/whitestone1121-web/signalbrain/blob/main/docs/incidents/2026-07-tooling-trust-streak-gaming.md)
+
+**Trust layer for AI-modified software.**
+
+Every company is letting agents change systems that matter. Every agent overstates what it did. SignalBrain is the referee: signed improvement receipts, objective re-score, and per-class calibrated trust — so autonomy is earned, not self-reported.
+
+This repository is **Phase 0 v0.1**: the receipt spec, ledger math, scoring lane, anti-Goodhart machinery, and the founding incident record — extracted from the [Titan reference deployment](https://github.com/whitestone1121-web/neural-chat-v3) (R&D dummy that keeps trying to game its own ledger, in public).
+
+## 60-second demo — run it, don't trust it
+
+```bash
+pip install "git+https://github.com/whitestone1121-web/signalbrain"
+bash demo/demo.sh
+```
+
+Real output (scratch repo built on the fly — no mocks):
+
+```text
+▶ 1. An agent tries to score its own claim BEFORE anyone merged it
+  {"status": "refused_guard", "code": 3, "message": "... not on HEAD — score only human-merged receipts"}
+  refused: unmerged claims cannot enter the ledger. No agent grades its own homework.
+
+▶ 2. A batch of receipts measured only by tests the agent wrote itself
+  ledger now holds 3 rows — every one classified: 3 "claim_kind": "invariant_pin"
+  {}   (no class has ANY trust-eligible claims)
+  three green results, ZERO earned trust: held-by-construction pins are recorded, never counted.
+
+▶ 3. An honest failure
+  "held": false
+  the agent said 0.9 confidence. The measurement said no. That gap is the product.
+
+▶ 4. Ten claims that actually hold
+  "tooling": { "hit_rate": 1.0, "n": 10, "status": "auto-merge ELIGIBLE" }
+  earned by track record, revocable by evidence. Autonomy is graduated, never granted.
+```
+
+## Three layers
+
+| Layer | What | Status |
+|-------|------|--------|
+| **Receipt** | Open standard — signed, re-runnable claims | [`docs/RECEIPT_SPEC.md`](docs/RECEIPT_SPEC.md) v0.1 |
+| **Ledger** | Per-class trust from objectively re-scored receipts | `src/signalbrain/governance/` |
+| **Refuter** | Adversarial verification + SPC (premium) | scripts + roadmap |
+
+## Founding proof
+
+Our own autonomous lane tried to pad its trust score to 100% ELIGIBLE in a local working tree. It never reached git. Full receipt-style incident record with reproduce commands:
+
+[`docs/incidents/2026-07-tooling-trust-streak-gaming.md`](docs/incidents/2026-07-tooling-trust-streak-gaming.md)
+
+Every number in that document is re-derivable from cited SHAs.
+
+## Quick start
+
+```bash
+export PYTHONPATH=src:scripts
+
+# Gate report (requires a ledger at docs/calibration/improvement_claim_ledger.jsonl)
+python scripts/calibration_ledger.py docs/calibration/improvement_claim_ledger.jsonl \
+  --require-measured --by-class --window 10
+
+# Score one merged receipt
+bash scripts/calibration_score_receipt.sh docs/improvements/NNNN-name.md
+
+# Contract suite (product spec)
+pytest tests/contracts/ -q
+```
+
+## v0.1 scope and known seams
+
+See [`docs/PHASE0_EXTRACT_PLAN.md`](docs/PHASE0_EXTRACT_PLAN.md). This release copies the working Titan implementation; the six-week refactor (configurable paths, packaged CLI, GitHub Action) starts when three design-partner conversations exist.
+
+**Compat note:** governance modules live under `signalbrain.governance`; `agi_os_backend.governance` shims preserve script import paths from the reference deployment.
+
+## Design partner offer
+
+We score your coding agents' claims against what actually merged. First caught overclaim is free — if we don't find one, you still get an audit. Contact: [signalbrain.ai](https://signalbrain.ai)
+
+## License
+
+Apache-2.0 — see LICENSE.

signalbrain-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "signalbrain"
+version = "0.1.0"
+description = "Trust layer for AI-modified software — receipts, ledger, calibrated autonomy"
+readme = "README.md"
+license = { text = "Apache-2.0" }
+requires-python = ">=3.11"
+authors = [{ name = "SignalBrain" }]
+keywords = ["ai", "agents", "calibration", "trust", "receipts", "governance"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: Apache Software License",
+  "Programming Language :: Python :: 3",
+  "Topic :: Software Development :: Quality Assurance",
+]
+
+[project.scripts]
+sb = "signalbrain.cli:main"
+
+[project.urls]
+Homepage = "https://signalbrain.ai"
+Repository = "https://github.com/whitestone1121-web/signalbrain"
+Documentation = "https://github.com/whitestone1121-web/signalbrain/blob/main/docs/RECEIPT_SPEC.md"
+Incident = "https://github.com/whitestone1121-web/signalbrain/blob/main/docs/incidents/2026-07-tooling-trust-streak-gaming.md"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src", "scripts"]
+testpaths = ["tests"]

signalbrain-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

signalbrain-0.1.0/src/agi_os_backend/governance/calibration_autonomy_gate.py

@@ -0,0 +1 @@
+from signalbrain.governance.calibration_autonomy_gate import *  # noqa: F403

signalbrain-0.1.0/src/agi_os_backend/governance/calibration_ledger_core.py

@@ -0,0 +1 @@
+from signalbrain.governance.calibration_ledger_core import *  # noqa: F403

signalbrain-0.1.0/src/agi_os_backend/governance/calibration_same_pr_pin.py

@@ -0,0 +1 @@
+from signalbrain.governance.calibration_same_pr_pin import *  # noqa: F403

signalbrain-0.1.0/src/signalbrain/__init__.py

@@ -0,0 +1,3 @@
+"""SignalBrain — trust layer for AI-modified software."""
+
+__version__ = "0.1.0"

signalbrain-0.1.0/src/signalbrain/cli.py

@@ -0,0 +1,97 @@
+"""sb — score receipts, read gates.
+
+  sb score <receipt.md ...> [--root .] [--ledger ledger.jsonl] [--ref origin/main]
+                            [--rescore] [--allow-unmerged] [--timeout 180]
+  sb gate  [--ledger ledger.jsonl] [--window N] [--by-class] [--recency-only]
+  sb check <receipt.md> [--root .] [--ref origin/main]
+
+Exit codes: score → 0 if every receipt scored (held or not — honest failure is a
+result), 3 if any was refused by the merged-receipt guard; gate → 0 TRUST, 1 GATE;
+check → the guard's own code (0/3/4/5).
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from . import gate as gate_mod
+from . import guard as guard_mod
+from .scorer import ScoreConfig, score_receipt
+
+
+def _cmd_score(args: argparse.Namespace) -> int:
+    cfg = ScoreConfig(
+        root=Path(args.root).resolve(),
+        ledger_path=Path(args.ledger),
+        merged_ref=args.ref,
+        allow_unmerged=args.allow_unmerged,
+        timeout_s=args.timeout,
+        rescore=args.rescore,
+    )
+    refused = 0
+    for receipt in args.receipts:
+        result = score_receipt(Path(receipt), cfg)
+        print(json.dumps(result))
+        if result["status"] == "refused_guard":
+            refused += 1
+    return 3 if refused else 0
+
+
+def _cmd_gate(args: argparse.Namespace) -> int:
+    ledger = Path(args.ledger)
+    env = None
+    if args.recency_only:
+        env = {gate_mod.RECENCY_GATE_ENV: "1"}
+        if args.window:
+            env[gate_mod.WINDOW_ENV] = str(args.window)
+    if args.by_class:
+        status = gate_mod.per_class(ledger, window=args.window or None, env=env)
+        print(json.dumps(status, indent=2))
+        return 0 if any(r.get("status") == "auto-merge ELIGIBLE" for r in status.values()) else 1
+    allowed, verdict = gate_mod.widening_allowed(ledger, env=env if env is not None else None)
+    print(json.dumps(verdict, indent=2))
+    return 0 if allowed else 1
+
+
+def _cmd_check(args: argparse.Namespace) -> int:
+    result = guard_mod.check_merged(Path(args.root).resolve(), Path(args.receipt), merged_ref=args.ref)
+    print(result.message, file=sys.stderr)
+    return result.code
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(prog="sb", description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    sub = ap.add_subparsers(dest="cmd", required=True)
+
+    p = sub.add_parser("score", help="objectively score merged receipts into the ledger")
+    p.add_argument("receipts", nargs="+")
+    p.add_argument("--root", default=".")
+    p.add_argument("--ledger", required=True)
+    p.add_argument("--ref", default="origin/main")
+    p.add_argument("--rescore", action="store_true")
+    p.add_argument("--allow-unmerged", action="store_true", help="supervised experiments only")
+    p.add_argument("--timeout", type=int, default=180)
+    p.set_defaults(fn=_cmd_score)
+
+    p = sub.add_parser("gate", help="print trust gates; exit 0 TRUST / 1 GATE")
+    p.add_argument("--ledger", required=True)
+    p.add_argument("--window", type=int, default=0)
+    p.add_argument("--by-class", action="store_true")
+    p.add_argument("--recency-only", action="store_true")
+    p.set_defaults(fn=_cmd_gate)
+
+    p = sub.add_parser("check", help="merged-receipt guard only")
+    p.add_argument("receipt")
+    p.add_argument("--root", default=".")
+    p.add_argument("--ref", default="origin/main")
+    p.set_defaults(fn=_cmd_check)
+
+    args = ap.parse_args(argv)
+    return args.fn(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

signalbrain-0.1.0/src/signalbrain/gate.py

@@ -0,0 +1,104 @@
+"""Trust gates — global and per-class (SPEC §3).
+
+Config-first port of neural-chat-v3 `calibration_autonomy_gate`. Env variables
+use the SIGNALBRAIN_ prefix and are fallbacks; explicit arguments always win.
+There is deliberately no bypass env: the only override anywhere is the scorer's
+loud ``allow_unmerged``.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any
+
+from .ledger import (
+    DEFAULT_MIN_HIT_RATE,
+    DEFAULT_RECENCY_WINDOW,
+    class_status,
+    load_rows,
+    trust_verdict,
+)
+
+WINDOW_ENV = "SIGNALBRAIN_WINDOW"
+MIN_HIT_RATE_ENV = "SIGNALBRAIN_MIN_HIT_RATE"
+RECENCY_GATE_ENV = "SIGNALBRAIN_RECENCY_GATE"
+DUAL_GATE_ENV = "SIGNALBRAIN_DUAL_GATE"
+
+
+def _truthy(env: dict[str, str], key: str) -> bool:
+    return str(env.get(key, "")).strip().lower() in ("1", "true", "yes", "on")
+
+
+def window_from_env(env: dict[str, str] | None = None) -> int | None:
+    env = env if env is not None else dict(os.environ)
+    raw = str(env.get(WINDOW_ENV, "")).strip()
+    if not raw:
+        return None
+    try:
+        value = int(raw)
+    except ValueError:
+        return None
+    return value if value > 0 else None
+
+
+def min_hit_rate_from_env(env: dict[str, str] | None = None) -> float:
+    env = env if env is not None else dict(os.environ)
+    raw = str(env.get(MIN_HIT_RATE_ENV, "") or DEFAULT_MIN_HIT_RATE).strip()
+    try:
+        value = float(raw)
+    except ValueError:
+        return DEFAULT_MIN_HIT_RATE
+    return value if 0.0 < value <= 1.0 else DEFAULT_MIN_HIT_RATE
+
+
+def recency_only_from_env(env: dict[str, str] | None = None) -> bool:
+    """Operator opt-in: gate on the recency window only (past failures fade)."""
+    env = env if env is not None else dict(os.environ)
+    if _truthy(env, DUAL_GATE_ENV):
+        return False
+    return _truthy(env, RECENCY_GATE_ENV)
+
+
+def per_class(ledger_path: Path, *, window: int | None = None, env: dict[str, str] | None = None) -> dict[str, dict[str, Any]]:
+    """Per-class auto-merge status. The window resolves: arg > env > default.
+
+    One source of truth for BOTH the report and any merge decision — a rail
+    that reads a different window than the operator's report is a fake-green.
+    """
+    w = window if window is not None else (window_from_env(env) or DEFAULT_RECENCY_WINDOW)
+    return class_status(load_rows(ledger_path), window=w, require_measured=True)
+
+
+def eligible_classes(ledger_path: Path, *, window: int | None = None, env: dict[str, str] | None = None) -> list[str]:
+    status = per_class(ledger_path, window=window, env=env)
+    return sorted(name for name, row in status.items() if row.get("status") == "auto-merge ELIGIBLE")
+
+
+def widening_allowed(
+    ledger_path: Path,
+    *,
+    env: dict[str, str] | None = None,
+) -> tuple[bool, dict[str, Any]]:
+    """Global trust gate. Dual by default (full history AND recency window ≥ min rate);
+    SIGNALBRAIN_RECENCY_GATE=1 opts into recency-only."""
+    env = dict(env if env is not None else os.environ)
+    min_rate = min_hit_rate_from_env(env)
+    rows = load_rows(ledger_path)
+    full = trust_verdict(rows, min_hit_rate=min_rate, require_measured=True, window=None)
+    recency_window = window_from_env(env) or DEFAULT_RECENCY_WINDOW
+    recency = trust_verdict(rows, min_hit_rate=min_rate, require_measured=True, window=recency_window)
+    if recency_only_from_env(env):
+        allowed = recency.get("verdict") == "TRUST"
+        reason = "recency-windowed measured gate (full history advisory; operator opt-in)"
+    else:
+        allowed = full.get("verdict") == "TRUST" and recency.get("verdict") == "TRUST"
+        reason = "dual gate: full measured history and recency window must both TRUST"
+    return allowed, {
+        "verdict": "TRUST" if allowed else "GATE",
+        "reason": reason,
+        "operative_gate": "recency_window" if recency_only_from_env(env) else "dual",
+        "full_history": full,
+        "recency_window": recency,
+        "recency_window_size": recency_window,
+    }

signalbrain-0.1.0/src/signalbrain/governance/__init__.py

@@ -0,0 +1,19 @@
+from signalbrain.governance.calibration_ledger_core import (
+    CLAIM_KIND_IMPROVEMENT,
+    CLAIM_KIND_INVARIANT_PIN,
+    calibration_verdict,
+    class_auto_merge_status,
+    filter_rows,
+    is_invariant_pin,
+    load_rows,
+)
+
+__all__ = [
+    "CLAIM_KIND_IMPROVEMENT",
+    "CLAIM_KIND_INVARIANT_PIN",
+    "calibration_verdict",
+    "class_auto_merge_status",
+    "filter_rows",
+    "is_invariant_pin",
+    "load_rows",
+]

signalbrain-0.1.0/src/signalbrain/governance/calibration_autonomy_gate.py

@@ -0,0 +1,184 @@
+"""Calibration gate for widening autonomous authority.
+
+Scores improvement-claim confidence vs outcome (held/not-held). Autonomy widening
+(factory dispatch, research dispatch, mutation env flags) requires TRUST unless
+an operator explicitly bypasses with TITAN_AUTONOMY_CALIBRATION_BYPASS=1.
+
+By default the gate counts only ``scored_by == "measured"`` claims so self-reported
+A/B ingest cannot inflate trust (see calibration_ingest_receipts.py).
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any
+
+from signalbrain.governance.calibration_ledger_core import (
+    AUTONOMY_RECENCY_WINDOW,
+    DEFAULT_MIN_HIT_RATE,
+    calibration_verdict,
+    class_auto_merge_status,
+    load_rows,
+)
+
+DEFAULT_LEDGER_REL = "docs/calibration/improvement_claim_ledger.jsonl"
+CALIBRATION_BYPASS_ENV = "TITAN_AUTONOMY_CALIBRATION_BYPASS"
+LEDGER_PATH_ENV = "TITAN_CALIBRATION_LEDGER_PATH"
+MIN_HIT_RATE_ENV = "TITAN_CALIBRATION_MIN_HIT_RATE"
+REQUIRE_MEASURED_ENV = "TITAN_CALIBRATION_REQUIRE_MEASURED"
+WINDOW_ENV = "TITAN_CALIBRATION_WINDOW"
+CHANGE_CLASS_ENV = "TITAN_CALIBRATION_CHANGE_CLASS"
+DUAL_GATE_ENV = "TITAN_CALIBRATION_DUAL_GATE"
+RECENCY_GATE_ENV = "TITAN_CALIBRATION_RECENCY_GATE"
+
+
+def default_ledger_path(root: Path | None = None) -> Path:
+    override = os.getenv(LEDGER_PATH_ENV, "").strip()
+    if override:
+        return Path(override)
+    base = root or Path(__file__).resolve().parents[3]
+    return base / DEFAULT_LEDGER_REL
+
+
+def min_hit_rate_from_env(env: dict[str, str] | None = None) -> float:
+    env = env if env is not None else os.environ
+    raw = str(env.get(MIN_HIT_RATE_ENV, "") or DEFAULT_MIN_HIT_RATE).strip()
+    try:
+        value = float(raw)
+    except ValueError:
+        return DEFAULT_MIN_HIT_RATE
+    return value if 0.0 < value <= 1.0 else DEFAULT_MIN_HIT_RATE
+
+
+def require_measured_from_env(env: dict[str, str] | None = None) -> bool:
+    env = env if env is not None else os.environ
+    raw = str(env.get(REQUIRE_MEASURED_ENV, "1")).strip().lower()
+    return raw in ("1", "true", "yes", "on")
+
+
+def window_from_env(env: dict[str, str] | None = None) -> int | None:
+    env = env if env is not None else os.environ
+    raw = str(env.get(WINDOW_ENV, "")).strip()
+    if not raw:
+        return None
+    try:
+        value = int(raw)
+    except ValueError:
+        return None
+    return value if value > 0 else None
+
+
+def change_class_from_env(env: dict[str, str] | None = None) -> str | None:
+    env = env if env is not None else os.environ
+    raw = str(env.get(CHANGE_CLASS_ENV, "")).strip()
+    return raw or None
+
+
+def calibration_bypass_enabled(env: dict[str, str] | None = None) -> bool:
+    env = env if env is not None else os.environ
+    return str(env.get(CALIBRATION_BYPASS_ENV, "0")).strip().lower() in ("1", "true", "yes", "on")
+
+
+def calibration_autonomy_verdict(
+    ledger_path: Path,
+    *,
+    min_hit_rate: float = DEFAULT_MIN_HIT_RATE,
+    require_measured: bool | None = None,
+    window: int | None = None,
+    change_class: str | None = None,
+    exclude_goodhart: bool = True,
+) -> dict[str, Any]:
+    if not ledger_path.is_file():
+        return {
+            "claims": 0,
+            "high_confidence_claims": 0,
+            "high_confidence_hit_rate": 0.0,
+            "min_hit_rate": min_hit_rate,
+            "verdict": "GATE",
+            "reason": "calibration ledger missing",
+            "require_measured": require_measured,
+        }
+    rows = load_rows(ledger_path)
+    return calibration_verdict(
+        rows,
+        min_hit_rate=min_hit_rate,
+        require_measured=bool(require_measured),
+        window=window,
+        change_class=change_class,
+        exclude_goodhart=exclude_goodhart,
+    )
+
+
+def per_class_auto_merge(ledger_path: Path, *, window: int | None = None) -> dict[str, dict[str, Any]]:
+    return class_auto_merge_status(
+        load_rows(ledger_path),
+        window=window,
+        require_measured=True,
+        exclude_goodhart=True,
+    )
+
+
+def _truthy_env(env: dict[str, str], key: str) -> bool:
+    return str(env.get(key, "")).strip().lower() in ("1", "true", "yes", "on")
+
+
+def recency_only_from_env(env: dict[str, str] | None = None) -> bool:
+    """When True, operative gate uses recency-window TRUST only (operator opt-in to option b)."""
+    env = env if env is not None else os.environ
+    if _truthy_env(env, DUAL_GATE_ENV):
+        return False
+    return _truthy_env(env, RECENCY_GATE_ENV)
+
+
+def dual_gate_from_env(env: dict[str, str] | None = None) -> bool:
+    """Default operative gate: require both full-history and recency-window TRUST."""
+    return not recency_only_from_env(env)
+
+
+def autonomy_widening_allowed(
+    root: Path,
+    *,
+    env: dict[str, str] | None = None,
+    ledger_path: Path | None = None,
+) -> tuple[bool, dict[str, Any]]:
+    env = dict(env if env is not None else os.environ)
+    if calibration_bypass_enabled(env):
+        return True, {"verdict": "BYPASS", "reason": "operator bypass env set"}
+    path = ledger_path or default_ledger_path(root)
+    measured = require_measured_from_env(env)
+    min_rate = min_hit_rate_from_env(env)
+    operator_window = window_from_env(env)
+    full = calibration_autonomy_verdict(
+        path,
+        min_hit_rate=min_rate,
+        require_measured=measured,
+        window=None,
+        change_class=change_class_from_env(env),
+        exclude_goodhart=True,
+    )
+    recency_window = operator_window if operator_window is not None else AUTONOMY_RECENCY_WINDOW
+    recency = calibration_autonomy_verdict(
+        path,
+        min_hit_rate=min_rate,
+        require_measured=measured,
+        window=recency_window,
+        change_class=change_class_from_env(env),
+        exclude_goodhart=True,
+    )
+    if recency_only_from_env(env):
+        allowed = recency.get("verdict") == "TRUST"
+        reason = "recency-windowed measured gate (full history advisory only; operator opt-in)"
+    else:
+        allowed = full.get("verdict") == "TRUST" and recency.get("verdict") == "TRUST"
+        reason = "dual gate: full measured history and recency window must both TRUST"
+    verdict = {
+        "verdict": "TRUST" if allowed else "GATE",
+        "reason": reason,
+        "operative_gate": "recency_window" if recency_only_from_env(env) else "dual",
+        "full_history": full,
+        "recency_window": recency,
+        "recency_window_size": recency_window,
+        "require_measured": measured,
+    }
+    return allowed, verdict