@event4u/agent-config 2.9.0 → 2.11.0

package/scripts/_cli/cmd_settings_check.py

@@ -0,0 +1,171 @@
+"""``agent-config settings:check`` — validate ``.agent-settings.yml`` against the supported YAML subset.
+
+Read-only. Implements P3.2 of road-to-proof-not-features.md. The contract
+this checks against is pinned in
+``docs/contracts/settings-sync-yaml-subset.md``; out-of-subset constructs
+cause :class:`sync_yaml_rt` to raise ``ValueError`` during a sync. This
+CLI surfaces the same findings *before* a sync runs, so users can fix
+their file without watching the merge fail.
+
+Output line format::
+
+    line:N  <kind>  <verdict>  <fix hint>
+
+Exit codes:
+
+* ``0`` — file is inside the supported subset (or absent and ``--allow-missing``).
+* ``1`` — one or more findings (verdict ``not supported``).
+* ``2`` — file absent (without ``--allow-missing``) or unreadable.
+"""
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from pathlib import Path
+
+# Imported lazily inside ``main`` so a missing engine cannot break ``--help``.
+
+DEFAULT_PATH = ".agent-settings.yml"
+
+# Out-of-subset patterns detected by a line-level pre-scan. Each rule is
+# (label, regex, fix hint). The regex is applied to the *stripped* body
+# of each non-comment line so leading indent does not affect matching.
+_PRESCAN_RULES: tuple[tuple[str, re.Pattern[str], str], ...] = (
+    (
+        "multi-doc separator",
+        re.compile(r"^(---|\.\.\.)\s*(#.*)?$"),
+        "remove the separator — one YAML document per file only.",
+    ),
+    (
+        "complex key",
+        re.compile(r"^\?\s"),
+        "rewrite as a plain ``key: value`` mapping line.",
+    ),
+    (
+        "block-scalar indicator",
+        re.compile(r":\s*[|>][+-]?\s*(#.*)?$"),
+        "inline the value as a single-line quoted scalar.",
+    ),
+    (
+        "tagged scalar",
+        re.compile(r":\s*!!?[A-Za-z_]"),
+        "remove the ``!tag``; the parser does not honour it.",
+    ),
+    (
+        "anchor / alias",
+        re.compile(r":\s*[&*][A-Za-z_]"),
+        "expand the anchor inline — anchors / aliases are not supported.",
+    ),
+    (
+        "nested flow-mapping",
+        re.compile(r":\s*\{[^}]*:[^}]*\}"),
+        "rewrite as a block-style nested mapping (indented child keys).",
+    ),
+)
+
+
+def _scan_line(stripped: str) -> tuple[str, str] | None:
+    if not stripped or stripped.startswith("#"):
+        return None
+    for label, pattern, hint in _PRESCAN_RULES:
+        if pattern.search(stripped):
+            return label, hint
+    return None
+
+
+def _scan_text(text: str) -> list[dict]:
+    findings: list[dict] = []
+    for lineno, raw in enumerate(text.splitlines(), 1):
+        stripped = raw.strip()
+        if "\t" in raw[: len(raw) - len(raw.lstrip(" \t"))]:
+            findings.append({
+                "line": lineno,
+                "kind": "tab in indent",
+                "verdict": "not supported",
+                "hint": "replace leading tabs with 2 or 4 spaces.",
+            })
+            continue
+        hit = _scan_line(stripped)
+        if hit is not None:
+            label, hint = hit
+            findings.append({
+                "line": lineno,
+                "kind": label,
+                "verdict": "not supported",
+                "hint": hint,
+            })
+    return findings
+
+
+def _format(finding: dict) -> str:
+    return (
+        f"  ❌  line:{finding['line']:<4}  "
+        f"{finding['kind']:<22}  {finding['verdict']:<14}  {finding['hint']}"
+    )
+
+
+def _parse(argv: list[str]) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        prog="agent-config settings:check",
+        description=(
+            "Validate .agent-settings.yml against the supported YAML subset "
+            "(docs/contracts/settings-sync-yaml-subset.md). Read-only."
+        ),
+    )
+    parser.add_argument("--path", default=DEFAULT_PATH,
+                        help=f"target settings file (default: ./{DEFAULT_PATH})")
+    parser.add_argument("--allow-missing", action="store_true",
+                        help="exit 0 when the file is absent (CI-friendly)")
+    parser.add_argument("--quiet", action="store_true",
+                        help="suppress non-essential output")
+    return parser.parse_args(argv)
+
+
+def main(argv: list[str]) -> int:
+    opts = _parse(argv)
+    target = Path(opts.path)
+    if not target.is_file():
+        if opts.allow_missing:
+            if not opts.quiet:
+                print(f"✅  {target}: file absent (allow-missing).")
+            return 0
+        print(f"❌  {target}: file not found.", file=sys.stderr)
+        print("    Run `./agent-config sync-agent-settings` to create it.", file=sys.stderr)
+        return 2
+    try:
+        text = target.read_text(encoding="utf-8")
+    except OSError as exc:
+        print(f"❌  {target}: cannot read: {exc}", file=sys.stderr)
+        return 2
+
+    findings = _scan_text(text)
+    if not findings:
+        # Final gate: run the round-trip parser to catch anything the
+        # pre-scan missed (mismatched indent, malformed mapping lines).
+        from scripts import sync_yaml_rt as _rt  # noqa: PLC0415
+        try:
+            _rt.parse(text)
+        except ValueError as exc:
+            findings.append({
+                "line": 0, "kind": "parser",
+                "verdict": "not supported", "hint": str(exc),
+            })
+
+    if not findings:
+        if not opts.quiet:
+            print(f"✅  {target}: inside the supported subset "
+                  "(docs/contracts/settings-sync-yaml-subset.md).")
+        return 0
+    print(f"❌  {target}: {len(findings)} finding(s) outside the supported subset.",
+          file=sys.stderr)
+    for finding in findings:
+        print(_format(finding), file=sys.stderr)
+    print("", file=sys.stderr)
+    print("    Contract: docs/contracts/settings-sync-yaml-subset.md",
+          file=sys.stderr)
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

package/scripts/agent-config

@@ -127,10 +127,22 @@ Tier 2 — maintenance / internal (hooks, MCP, memory, telemetry):
                              (experimental — beta gates: docs/contracts/mcp-beta-criteria.md)
   roadmap:progress           Regenerate agents/roadmaps-progress.md from open roadmaps
   roadmap:progress-check     Fail if agents/roadmaps-progress.md is stale (for CI)
+  settings:check             Validate .agent-settings.yml against the YAML-subset contract
+                             (docs/contracts/settings-sync-yaml-subset.md). Read-only.
+                             Exit 0 clean, 1 finding(s), 2 file absent / unreadable.
   hooks:install              Install the pre-commit roadmap-progress hook
                              (use --print to dump it, --force to overwrite an existing hook)
   hooks:status               Print the runtime hook matrix (per-platform install + bindings)
                              Flags: --format json|table, --strict (CI), --project-root <path>
+  hooks:doctor               Diagnose hook health: concerns + fail-open/closed posture,
+                             last dispatcher feedback per concern, missing trampolines.
+                             Wraps hooks:status. Read-only.
+                             Flags: --format json|table, --strict (CI), --project-root <path>
+  hooks:replay               Replay a fixture through the universal dispatcher with
+                             AGENT_CONFIG_REPLAY=1 (no writes under agents/state/).
+                             Usage: hooks:replay --platform <name> --event <event>
+                                    --payload <path|event-name> [--native-event <native>]
+                                    [--manifest <path>] [--json] [--dry-run]
   migrate-state              Migrate a legacy .implement-ticket-state.json file
                              to the v1 .work-state.json schema (preserves .bak)
   memory:lookup              Retrieve memory entries (text or JSON envelope)
@@ -217,7 +229,9 @@ Examples (Tier 2):
   ./agent-config mcp:setup
   ./agent-config mcp:run
   ./agent-config roadmap:progress
+  ./agent-config settings:check
   ./agent-config hooks:install
+  ./agent-config hooks:replay --platform augment --event post_tool_use --payload post_tool_use --json
   ./agent-config migrate-state
   ./agent-config memory:lookup --types domain-invariants --key billing
   ./agent-config memory:signal --type architecture-decision --path src/Foo.php --body "…"
@@ -507,6 +521,20 @@ cmd_hooks_status() {
   exec python3 "$script" "$@"
 }
 
+cmd_hooks_doctor() {
+  require_python3
+  local script
+  script="$(resolve_script "scripts/hooks_doctor.py")" || return 1
+  exec python3 "$script" "$@"
+}
+
+cmd_hooks_replay() {
+  require_python3
+  local script
+  script="$(resolve_script "scripts/hooks/replay_hook.py")" || return 1
+  exec python3 "$script" "$@"
+}
+
 cmd_chat_history_checkpoint() {
   require_python3
   local script
@@ -676,6 +704,15 @@ cmd_validate() {
   exec env PYTHONPATH="$PACKAGE_ROOT" python3 -m scripts._cli.cmd_validate "$@"
 }
 
+# `agent-config settings:check` — read-only YAML-subset validator for
+# `.agent-settings.yml` (P3.2 of road-to-proof-not-features.md). Contract
+# pinned in docs/contracts/settings-sync-yaml-subset.md. Exit 0 clean,
+# 1 finding(s), 2 file absent / unreadable.
+cmd_settings_check() {
+  require_python3
+  exec env PYTHONPATH="$PACKAGE_ROOT" python3 -m scripts._cli.cmd_settings_check "$@"
+}
+
 # `agent-config uninstall` — remove bridge markers (project) or lockfile
 # entries (global). Idempotent. Pass `--purge` to also delete deployed
 # content directories under user-scope anchors (destructive). See
@@ -744,6 +781,8 @@ main() {
     context-hygiene:hook)    cmd_context_hygiene_hook "$@" ;;
     dispatch:hook)           cmd_dispatch_hook "$@" ;;
     hooks:status)            cmd_hooks_status "$@" ;;
+    hooks:doctor)            cmd_hooks_doctor "$@" ;;
+    hooks:replay)            cmd_hooks_replay "$@" ;;
     telemetry:record)        cmd_telemetry_record "$@" ;;
     telemetry:status)        cmd_telemetry_status "$@" ;;
     telemetry:report)        cmd_telemetry_report "$@" ;;
@@ -757,6 +796,7 @@ main() {
     export)                  cmd_export "$@" ;;
     sync)                    cmd_sync "$@" ;;
     validate)                cmd_validate "$@" ;;
+    settings:check)          cmd_settings_check "$@" ;;
     uninstall)               cmd_uninstall "$@" ;;
     prune)                   cmd_prune "$@" ;;
     doctor)                  cmd_doctor "$@" ;;

package/scripts/chat_history.py

@@ -48,6 +48,15 @@ SCHEMA_VERSION = 4
 DEFAULT_MAX_SESSIONS = 5
 VALID_FREQS = {"per_turn", "per_phase", "per_tool"}
 VALID_OVERFLOW = {"rotate", "compress"}
+
+# Replay-mode signal — when set, every write to the on-disk transcript
+# is a no-op. Honoured per `docs/contracts/hook-architecture-v1.md`
+# § Replay mode so fixture dispatches never mutate real session state.
+REPLAY_ENV_VAR = "AGENT_CONFIG_REPLAY"
+
+
+def _is_replay_mode() -> bool:
+    return os.environ.get(REPLAY_ENV_VAR, "").strip() == "1"
 _WS_RE = re.compile(r"\s+")
 SESSION_ID_LEN = 16
 SESSION_ID_UNKNOWN = "<unknown>"
@@ -247,6 +256,8 @@ def init(freq: str = "per_phase", *,
         raise ValueError(f"freq must be one of {sorted(VALID_FREQS)}")
     p = path or file_path()
     header = _build_header(freq)
+    if _is_replay_mode():
+        return header
     p.parent.mkdir(parents=True, exist_ok=True)
     with p.open("w", encoding="utf-8") as fh:
         fh.write(json.dumps(header, ensure_ascii=False) + "\n")
@@ -318,6 +329,8 @@ def append(entry: dict[str, Any], *, path: Path | None = None,
         entry["s"] = session
     elif "s" not in entry and _session_tag_enabled():
         entry["s"] = _last_body_session_id(p)
+    if _is_replay_mode():
+        return
     with p.open("a", encoding="utf-8") as fh:
         fh.write(json.dumps(entry, ensure_ascii=False) + "\n")
 
@@ -328,7 +341,11 @@ def _atomic_write_text(p: Path, text: str) -> None:
     Multiple processes writing to the same target use disjoint tmp paths
     (PID + uuid), so concurrent writes no longer collide on a shared
     ``.tmp`` file. The final ``replace`` is atomic on POSIX.
+
+    Under `AGENT_CONFIG_REPLAY=1` the call is a no-op.
     """
+    if _is_replay_mode():
+        return
     tmp = p.with_suffix(
         f"{p.suffix}.{os.getpid()}.{uuid.uuid4().hex[:8]}.tmp",
     )
@@ -405,6 +422,8 @@ def prepend_entries(entries: list[dict[str, Any]], *,
 
 
 def clear(*, path: Path | None = None) -> None:
+    if _is_replay_mode():
+        return
     p = path or file_path()
     if p.exists():
         p.unlink()

package/scripts/check_beta_review_markers.py

@@ -0,0 +1,127 @@
+#!/usr/bin/env python3
+"""
+Beta-review-marker checker for `docs/contracts/`.
+
+Every contract whose frontmatter declares `stability: beta` MUST carry
+exactly one of the following frontmatter markers (per
+`docs/contracts/STABILITY.md` § Beta-review markers, ratified in
+`road-to-productization.md` § P5.4):
+
+  - `promote-to: stable`
+  - `keep-beta-until: YYYY-MM-DD`     (max 90 days from the last review)
+  - `superseded-by: <contract-id>`
+
+Exit codes: 0 = clean, 1 = violations found, 3 = internal error.
+
+Usage:
+    python3 scripts/check_beta_review_markers.py
+    python3 scripts/check_beta_review_markers.py --json
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from dataclasses import asdict, dataclass
+from datetime import date, timedelta
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+CONTRACTS_DIR = Path("docs/contracts")
+
+FRONTMATTER_RE = re.compile(r"^---\s*\n(.*?)\n---\s*\n", re.DOTALL)
+STABILITY_RE = re.compile(r"^stability:\s*(\w+)\s*$", re.MULTILINE)
+PROMOTE_RE = re.compile(r"^promote-to:\s*stable\s*$", re.MULTILINE)
+KEEP_RE = re.compile(r"^keep-beta-until:\s*(\d{4}-\d{2}-\d{2})\s*$", re.MULTILINE)
+SUPERSEDED_RE = re.compile(r"^superseded-by:\s*\S+\s*$", re.MULTILINE)
+
+MAX_REVIEW_WINDOW_DAYS = 90
+
+
+@dataclass
+class Violation:
+    file: str
+    reason: str
+    severity: str  # "error" | "warning"
+
+
+def read_frontmatter(path: Path) -> str | None:
+    if not path.exists():
+        return None
+    txt = path.read_text(encoding="utf-8")
+    m = FRONTMATTER_RE.match(txt)
+    return m.group(1) if m else None
+
+
+def check_one(path: Path, today: date) -> list[Violation]:
+    fm = read_frontmatter(path)
+    if fm is None:
+        return []
+    sm = STABILITY_RE.search(fm)
+    if not sm or sm.group(1) != "beta":
+        return []
+    markers = [
+        ("promote-to", bool(PROMOTE_RE.search(fm))),
+        ("keep-beta-until", bool(KEEP_RE.search(fm))),
+        ("superseded-by", bool(SUPERSEDED_RE.search(fm))),
+    ]
+    set_markers = [name for name, present in markers if present]
+    rel = str(path.relative_to(ROOT))
+    if not set_markers:
+        return [Violation(
+            file=rel,
+            reason="stability=beta but no review marker; add one of "
+                   "`promote-to: stable` | `keep-beta-until: <date>` | "
+                   "`superseded-by: <id>` (see STABILITY.md § Beta-review markers)",
+            severity="error",
+        )]
+    if len(set_markers) > 1:
+        return [Violation(
+            file=rel,
+            reason=f"multiple beta-review markers set ({', '.join(set_markers)}); "
+                   "exactly one is allowed",
+            severity="error",
+        )]
+    km = KEEP_RE.search(fm)
+    if km:
+        review_date = date.fromisoformat(km.group(1))
+        max_date = today + timedelta(days=MAX_REVIEW_WINDOW_DAYS)
+        if review_date > max_date:
+            return [Violation(
+                file=rel,
+                reason=f"keep-beta-until={review_date} exceeds the "
+                       f"{MAX_REVIEW_WINDOW_DAYS}-day window (max: {max_date})",
+                severity="error",
+            )]
+    return []
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--json", action="store_true", help="machine-readable output")
+    args = ap.parse_args()
+    today = date.today()
+    violations: list[Violation] = []
+    for p in sorted((ROOT / CONTRACTS_DIR).glob("*.md")):
+        violations.extend(check_one(p, today))
+    if args.json:
+        print(json.dumps({"violations": [asdict(v) for v in violations]}, indent=2))
+    else:
+        if not violations:
+            print("✅  All beta contracts carry a valid review marker.")
+        else:
+            for v in violations:
+                icon = "❌" if v.severity == "error" else "⚠️ "
+                print(f"{icon}  {v.file}: {v.reason}")
+            print(f"\n{len(violations)} violation(s).")
+    return 1 if any(v.severity == "error" for v in violations) else 0
+
+
+if __name__ == "__main__":
+    try:
+        sys.exit(main())
+    except Exception as exc:  # pragma: no cover
+        print(f"internal error: {exc}", file=sys.stderr)
+        sys.exit(3)

package/scripts/check_council_references.py

@@ -14,8 +14,10 @@ council files. Directory mentions and placeholder paths
 output-path convention, not a live reference.
 
 Forbidden hits in this codebase exist today (kernel-membership ADRs
-cite real session JSONs as decision traces). Suppress them with an
-inline pragma at the end of the line:
+cite real session JSONs as decision traces). Two source/target shapes
+are exempt structurally — see STRUCTURAL_CARVEOUTS below — because
+they encode immutable decision provenance, not transient drafting
+state. Anything else needs an inline pragma at the end of the line:
 
     `agents/council-sessions/...json` <!-- council-ref-allowed: <reason> -->
 
@@ -82,6 +84,31 @@ ALLOWLIST_FILES: frozenset[str] = frozenset({
 
 INLINE_PRAGMA = re.compile(r"<!--\s*council-ref-allowed:[^>]*-->")
 
+# Structural carve-outs — (source_pattern, target_pattern) pairs where
+# the reference is immutable decision provenance rather than transient
+# drafting state. Driven by the 2026-05-14 P3.4 council round
+# (agents/council-sessions/2026-05-14-p3-4-references/synthesis.md).
+#
+# Each entry: source file matches `source` regex AND the captured
+# reference path matches `target` regex → reference is allowed without
+# an inline pragma.
+STRUCTURAL_CARVEOUTS: tuple[tuple[re.Pattern[str], re.Pattern[str]], ...] = (
+    # (a) evaluation-context → council-question:
+    # the question file is a frozen function-parameter / spend-gate
+    # input, not a documentation link.
+    (
+        re.compile(r"^agents/contexts/evaluation-[^/]+\.md$"),
+        re.compile(r"^agents/council-questions/[^/]+\.md$"),
+    ),
+    # (b) contract → council-session-synthesis:
+    # the synthesis file is the audit-trail receipt the contract cites
+    # as decision provenance; the contract inlines the decision body.
+    (
+        re.compile(r"^docs/contracts/[^/]+\.md$"),
+        re.compile(r"^agents/council-sessions/[^/]+/synthesis\.md$"),
+    ),
+)
+
 
 def _is_allowlisted(rel: str) -> bool:
     if rel in ALLOWLIST_FILES:
@@ -89,8 +116,17 @@ def _is_allowlisted(rel: str) -> bool:
     return any(rel.startswith(prefix) for prefix in ALLOWLIST_PREFIXES)
 
 
+def _is_structurally_allowed(source_rel: str, target_capture: str) -> bool:
+    """True when (source, target) matches a structural carve-out pair."""
+    for src_re, tgt_re in STRUCTURAL_CARVEOUTS:
+        if src_re.match(source_rel) and tgt_re.match(target_capture):
+            return True
+    return False
+
+
 def _scan_file(path: Path) -> list[tuple[int, str]]:
     findings: list[tuple[int, str]] = []
+    rel = path.as_posix()
     try:
         text = path.read_text(encoding="utf-8")
     except (OSError, UnicodeDecodeError):
@@ -99,6 +135,8 @@ def _scan_file(path: Path) -> list[tuple[int, str]]:
         if INLINE_PRAGMA.search(line):
             continue
         for m in PATTERN.finditer(line):
+            if _is_structurally_allowed(rel, m.group(0)):
+                continue
             findings.append((ln, m.group(0)))
     return findings
 
@@ -136,10 +174,13 @@ def main() -> int:
     print(
         "\nRule: .agent-src/rules/no-roadmap-references.md (council clause)\n"
         "Fix: inline the convergence summary (members + date) instead of\n"
-        "linking the file. Append "
+        "linking the file. Two source/target shapes are exempt structurally\n"
+        "(evaluation-context → council-question, contract →\n"
+        "council-session-synthesis) — see STRUCTURAL_CARVEOUTS in this\n"
+        "script. Otherwise append "
         "<!-- council-ref-allowed: <reason> --> on the same line to\n"
-        "suppress when the reference is genuinely required (ADR / contract\n"
-        "decision trace)."
+        "suppress when the reference is genuinely required (ADR decision\n"
+        "trace)."
     )
     return 1
 

package/scripts/check_release_trunk_sync.py

@@ -0,0 +1,152 @@
+#!/usr/bin/env python3
+"""
+Release-trunk-sync CI gate (road-to-productization P1.3).
+
+Fails if `main` is more than one tagged release behind the current
+release-prep branch's target version. No-ops on every other branch
+class. Owner contract: `docs/contracts/release-trunk-sync.md`.
+
+Exit codes: 0 = pass / no-op, 1 = main is too far behind, 3 = internal
+error (git unavailable, malformed tag, etc.).
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+RELEASE_BRANCH_RE = re.compile(r"^release/(\d+)\.(\d+)\.(\d+)$")
+SEMVER_TAG_RE = re.compile(r"^(\d+)\.(\d+)\.(\d+)$")
+BOOTSTRAP_FILE = Path("docs/contracts/release-trunk-sync.bootstrap")
+
+
+def _git(*args: str) -> str:
+    proc = subprocess.run(
+        ["git", *args], capture_output=True, text=True, check=False
+    )
+    if proc.returncode != 0:
+        return ""
+    return proc.stdout.strip()
+
+
+def _current_branch() -> str:
+    return _git("rev-parse", "--abbrev-ref", "HEAD")
+
+
+def _parse_semver(text: str) -> tuple[int, int, int] | None:
+    m = SEMVER_TAG_RE.match(text)
+    if not m:
+        return None
+    return int(m.group(1)), int(m.group(2)), int(m.group(3))
+
+
+def _all_tags() -> list[tuple[int, int, int]]:
+    raw = _git("tag", "--list")
+    tags = []
+    for line in raw.splitlines():
+        parsed = _parse_semver(line.strip())
+        if parsed is not None:
+            tags.append(parsed)
+    tags.sort()
+    return tags
+
+
+def _main_tag() -> tuple[int, int, int] | None:
+    """Highest semver tag whose commit is reachable from main."""
+    # Try local main, fall back to origin/main.
+    for ref in ("refs/heads/main", "refs/remotes/origin/main"):
+        head = _git("rev-parse", "--verify", ref)
+        if head:
+            break
+    else:
+        return None
+    # `git tag --merged <main>` lists tags reachable from main.
+    raw = _git("tag", "--merged", head)
+    reachable: list[tuple[int, int, int]] = []
+    for line in raw.splitlines():
+        parsed = _parse_semver(line.strip())
+        if parsed is not None:
+            reachable.append(parsed)
+    if not reachable:
+        return None
+    return max(reachable)
+
+
+def _prior_release(
+    target: tuple[int, int, int], tags: list[tuple[int, int, int]]
+) -> tuple[int, int, int] | None:
+    earlier = [t for t in tags if t < target]
+    return max(earlier) if earlier else None
+
+
+def _bootstrap_ok(target: tuple[int, int, int]) -> bool:
+    if not BOOTSTRAP_FILE.exists():
+        return False
+    target_s = "{0}.{1}.{2}".format(*target)
+    for line in BOOTSTRAP_FILE.read_text().splitlines():
+        line = line.strip()
+        if not line or line.startswith("#"):
+            continue
+        if line == target_s:
+            return True
+    return False
+
+
+def main() -> int:
+    branch = _current_branch()
+    if branch == "HEAD" or not branch:
+        print("::warning::detached HEAD — release-trunk-sync gate skipped")
+        return 0
+    # CI override: GitHub Actions sometimes runs on the merge ref.
+    ci_ref = os.environ.get("GITHUB_HEAD_REF") or os.environ.get(
+        "GITHUB_REF_NAME"
+    )
+    if ci_ref:
+        branch = ci_ref
+    m = RELEASE_BRANCH_RE.match(branch)
+    if not m:
+        return 0  # non-release branch class — gate is a no-op
+    target = (int(m.group(1)), int(m.group(2)), int(m.group(3)))
+    tags = _all_tags()
+    if not tags:
+        print(
+            "::warning::no semver tags found — release-trunk-sync gate skipped"
+        )
+        return 0
+    main_tag = _main_tag()
+    if main_tag is None:
+        print(
+            "::warning::no semver tag reachable from main — gate skipped"
+        )
+        return 0
+    if main_tag >= target:
+        return 0  # main already at or ahead of release target
+    prior = _prior_release(target, tags)
+    if prior is not None and main_tag >= prior:
+        return 0  # within the one-release tolerance
+    if _bootstrap_ok(target):
+        target_s = "{0}.{1}.{2}".format(*target)
+        print(
+            f"::warning::release-trunk-sync gate suppressed for {target_s} "
+            "via bootstrap file"
+        )
+        return 0
+    main_s = "{0}.{1}.{2}".format(*main_tag)
+    target_s = "{0}.{1}.{2}".format(*target)
+    print(
+        f"::error::main is at {main_s}; release-prep branch targets "
+        f"{target_s}. Main must be no more than one tagged release behind. "
+        "See docs/contracts/release-trunk-sync.md."
+    )
+    return 1
+
+
+if __name__ == "__main__":
+    try:
+        sys.exit(main())
+    except Exception as exc:  # noqa: BLE001
+        print(f"::error::release-trunk-sync gate internal error: {exc}")
+        sys.exit(3)