plan_fold_gate.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# tools/plan_fold_gate.py
 
"""
Fold-landing gate for review-hardened plans (built for plan 151).
 
Purpose
-------
What this is — and, honestly, what it is NOT (2026-07-15, reviews 151/R17+R18).
This is a **region-scoped exact-substring checker**. For each folded finding it
asserts:
 
  * NEW  — the new mechanism's literal appears INSIDE the finding's executing
           region (a bounded span between two anchor strings — a step, a Gate,
           an AC row), **not merely somewhere in the document**. This is the
           capability whose absence let the v1 gate certify step-landings that
           were only in prose (Opus R18 O18-P0-1: the `/save` check passed while
           the T8 step had no `/save`).
  * GONE  — the retired literal and its listed paraphrases appear nowhere outside
           the sanctioned historical narrative.
 
It is **NOT** semantic paraphrase detection. The ``gone`` lists are a hand-curated
exact-substring denylist, case-sensitive; an unforeseen rewording is not caught.
The v1 tool over-claimed "concept-aware"; that claim is RETRACTED. A deterministic
checker cannot prove a concept is gone — so a MANDATORY HUMAN CONCEPT AUDIT remains
part of the fold procedure (plan §7(iii)); this gate is the mechanical floor under
it, not a replacement for it.
 
It is also NOT a completeness proof. ``CHECKS`` is reconciled against ``MANIFEST``
(the review-finding IDs it must cover) so the denominator cannot silently shrink by
deleting a check — but a finding nobody added to the manifest is still uncovered.
 
V30 (Sol R25 SOL25-03): the R24 lifecycle literals are the smallest complete OPERATIVE
contracts (the T8 custody phrase with its ledger-hash equality; the freeze-marker
baseline comparison) instead of bare tokens — Sol executed two single-leg mutations
that deleted the safety action while keeping the token, and the V29 checks stayed
green; both are now pinned regression tests. The three T8 blocked-path surfaces
(step / Gate / AC 22) are checked per-surface, and the receipt enumerates every
audited source. Still a phrase floor, not a lifecycle proof.
 
V31 (operator re-scope directive 2026-07-16 + Fable/Sol R26): the plan's evidence-layer
dispatch gates were retired by operator directive (threat-matched for a sole-operator,
local, reversible migration), so SOL25-01/SOL25-01-probe/SOL25-01-vars (the
authenticated-ledger dispatch gate), TERRA22-04 (the SOL20-04 pre-dispatch commit at
AC 22), and S23-P1-3 (the retired section-1.0 commit variable) are RETIRED from
CHECKS+MANIFEST — their anchor text no longer exists in the plan. SOL25-04 is
RETARGETED to the simple one-commit receipt form of section 7 clause v, and the
SOL25-02 blocked-path window is WIDENED over the two new close items. New checks:
F26-01 (the T2 PRESERVE equality oracle), F26-02-step/-gate/-ac22 (the terminal
artifact manifest blocked-path item, per surface), F26-03 (the rollback-copy and
DACL-save blocked-path items), R25-01-root (the durable-root declaration — Sol R26
mutation C, executed false-green at V30, now red), and V31-T8-RECONCILE (the kept T8
terminal-transition contract at AC 22). The V30 claim that each new check carried a
single-leg adversarial test was FALSE for five of the nine (Sol R26 SOL26-05); the
test suite now carries a META-TEST mapping every manifest fid to a named test or the
documented untested-phrase-floor list, failing on drift.
 
Usage
-----
    python tools/plan_fold_gate.py            # gate the committed HEAD blob (authoritative)
    python tools/plan_fold_gate.py --worktree # gate the working tree (iterating a fold)
 
Responsibilities
----------------
- :class:`Region` — a bounded span of the plan, located between two anchor strings.
- :class:`Check` — one finding: its ``new`` literal + the ``region`` it must land in,
  plus whole-document ``gone`` literals.
- :data:`CHECKS` / :data:`MANIFEST` — the fold set and the review IDs it must cover.
- :func:`evaluate` — THE single production predicate: returns the problems for one
  check against the plan text (the tests call this — they do not re-implement it).
- :func:`read_plan` / :func:`run` / :func:`main`.
 
Exit codes
----------
- 0 — every check passed and the manifest is covered.
- 1 — a finding did not land at its region, a retired literal survived, or the
      manifest/checks disagree.
- 2 — the plan file could not be read.
 
Diagnostics
-----------
Domain: OC_CHAT.MAIN
Levels:
    L2 — lifecycle events (the pass/fail tally)
    L3 — semantic details
    L4 — deep tracing
 
Contracts
---------
- The committed blob (``git show HEAD:<plan>``) is authoritative; ``--worktree`` is
  only for iterating a fold before committing.
- Historical-scope decision (Opus R17 O17-P1-4): ``gone`` targets a retired concept's
  OPERATIVE phrasing; a dated statement of fact ("renamed from X", "branch Y is merged
  and deleted") is allowed, which is why ``gone`` lists operative phrasings not bare
  nouns.
 
Dependencies
------------
- oc_diagnostics (structured debug logging via _dbg)
"""
from __future__ import annotations
 
import argparse
import subprocess
import sys
from dataclasses import dataclass, field
from pathlib import Path
 
import oc_diagnostics
from oc_diagnostics import _dbg
 
_REPO = Path(__file__).resolve().parent.parent
PLAN = "oc_chat/plans/completed/151-monorepo-migration.md"  # moved by the 2026-07-19 completed/ sweep
DEFERRED = "tools/151_deferred_sol20_tooling.md"
# Every source a check may evaluate against. The plan is the default; a CROSS-FILE
# check names another source (V29 — Sol R24 SOL24-03: the plan-only gate could not see
# a retired phrase surviving in the deferred-tooling doc — the sibling-leg miss one file over).
_SOURCES = {"plan": PLAN, "deferred": DEFERRED}
_REGION_MAX = 20000  # a step/Gate/AC span; wider means the anchor is too loose (Opus R19 O19-P0-1)
 
 
@dataclass(frozen=True)
class Region:
    """A bounded span of the plan, from the line containing ``start`` up to (but not
    including) the next line containing ``end``. ``end=None`` runs to end-of-document.
    ``label`` names the surface (step / Gate / AC) for the receipt."""
 
    label: str
    start: str
    end: str | None = None
 
    def slice(self, text: str) -> str | None:
        i = text.find(self.start)
        if i < 0:
            return None
        if self.end is None:
            return text[i:]
        j = text.find(self.end, i + len(self.start))
        return text[i:] if j < 0 else text[i:j]
 
 
@dataclass
class Check:
    """One folded finding. ``new`` must appear INSIDE ``region``; ``gone`` literals
    must be ABSENT from the whole document."""
 
    fid: str                       # the review-finding ID (reconciled against MANIFEST)
    name: str
    new: str | None = None
    region: Region | None = None
    gone: list[str] = field(default_factory=list)
    source: str = "plan"           # which _SOURCES text this check evaluates against (V29 SOL24-03: cross-file)
 
 
# Executing regions (anchors chosen to be stable substrings of the plan).
# _T8_CLOSE end tightened at V30 (Sol R25 SOL25-03: the "## " end made it a ~10k-char
# span — too loose to be an executing site; it now covers the canonical close list only).
_T8_CLOSE = Region("T8 close order", "close order (ONE canonical list", "Pin the mechanism as")
_T1_STEP3 = Region("T1 step 3 (fetch)", "OC_MIGRATION_BRANCH=<pinned>", "**⚠️")
_T2_D4 = Region("T2 D4 step", "D4 — distribution-SUPPLY fix", "D5 — ONE")
_T0_LEDGER = Region("§2.1 ledger schema", "ledger_schema_version, tranche", "**")
_S24_ROLLBACK = Region("§2.4 rollback", "rollback of the structural move", "###")
_T1_REHEARSAL = Region("T1 rehearsal Gate", "the rehearsal runs on a MERGED", "**")
# _T0_GATE end anchor retargeted at V31: F26-03 renamed the free-space clause to the
# per-volume budget receipt.
_T0_GATE = Region("T0 Gate", "each anchor tag (`pre-oc-chat-merge`", "free-space PER-VOLUME BUDGET receipt")
_T8_MIRROR = Region("T8 terminal transition (canonical close step 6)",
                    "LIFT the freeze (a marker removal, not a failure-capable gate)", "NEVER the artifact root")
_AC22_ATOMIC = Region("AC row 22 (T8 close)", "| 22 | **T8 (close):**", "| T8 report;")
# _S10_VARS start widened at V30 so the whole §1.0 block is covered (the old start
# anchored on the OC_CHAT_DISPATCH_WORKTREE line, which excluded the path roots above it).
_S10_VARS = Region("§1.0 canonical vars", "ACTIVE_FREEZE_PATH       = <dispatch-pinned", "```")
_T2_GATE = Region("T2 Gate (workspaces row)", "the scm `root`-DEPTH re-derivation recorded", "report-T2.")
# V30 (Sol R25 SOL25-02/-04): per-surface T8 blocked-path regions and the §7(v) protocol
# paragraph. (The V30 _T0_DISPATCH region is RETIRED at V31 — the operator re-scope removed
# the pre-dispatch tooling clause it anchored on.)
_T8_FAILPATH = Region("T8 step failure path (blocked-path set)",
                      "Failure path: if ANY close gate fails", "write a NON-terminal")
_T8_GATE_BLOCKED = Region("T8 Gate (blocked-path set)",
                          "non-terminal BLOCKED path taken on any failed close gate",
                          "never `Completed` before the final ledger entry lands")
_S7_V = Region("§7(v) fold-evidence protocol", "(v) THE MECHANICAL FOLD-LANDING GATE", "| # | Check |")
# The tag-receipt item inside the ONE canonical T8 blocked-path enumeration — byte-identical
# at the step, the Gate, and AC row 22 (V30 Sol R25 SOL25-02 added the item to all three;
# V31 F26-03 ≡ SOL26-06 inserted the rollback-copy + DACL-save items directly after it, so
# the window is WIDENED over them). The checked window starts inside the tag-receipt item and
# runs through the items that follow it, so deleting ANY covered item OR moving one past the
# lock breaks the match. (Windows, not the full 16-item set, are pinned: the strict
# no-hardcoded-secrets entropy floor caps single literals at 4.5 bits/char — the widened
# window measures 4.64 as one constant, so it is composed via EXPLICIT `+` from sub-4.5
# literals (4.17/4.11/4.23/3.73 bits/char; implicit adjacent literals are parse-folded into
# ONE constant the floor then measures); the full-set byte-identity is diffed mechanically
# at each fold per the plan's own T8 rule.)
_BLOCKED_WINDOW = ("`tag_receipt_sha256` re-check**, "
                   + "**independent rollback-copy verified**, "
                   + "**archive+parent DACL `/save` verified**, "
                   + "lock, smoke, intact-check")
# The terminal-artifact-manifest item (V31 F26-02 ≡ SOL26-02) — its window pins BOTH presence
# and position (after the final report-hash, before the final ledger-append) at each surface.
_MANIFEST_WINDOW = ("final report-hash, **`terminal_artifact_manifest` compute + read-back**"
                    ", final ledger-append")
# AC-row regions for the OPUS22 positive-phrasing legs (V29 — Opus R24-09: the OPUS22 gate
# checked the positive phrase only in the T2 Gate; a future reworded negative at AC 11 or AC 18
# would pass. These regions exercise the same legs the human concept audit currently must.)
_AC11 = Region("AC row 11 (runtime-state boundary)", "| 11 | **Runtime-state boundary", "| 12 |")
_AC18 = Region("AC row 18 (T2 D5 + settings)", "| 18 | **T2 D5 + settings", "| 19 |")
 
# The finding manifest: every ID here MUST have a Check, and every Check's fid MUST be here.
MANIFEST = {
    "O16-P1-1", "O16-P1-3", "V17-1", "V17-3", "V17-4", "V17-6",
    "13b", "SOL16-01", "O16-P2-1", "O16-P2-2", "O17-P1-4", "O17-P2-2",
    "SOL17-01", "SOL17-03",
    # R18 non-landing cluster (O18-P1-1) — must land at executing sites:
    "SOL14-07-rollback-tags", "SOL16-03-parent-acl", "D4-gate-ac",
    "O19-P1-1", "SOL14-04",
    # R23: every V27 fold landed at ONE leg and left a sibling STALE. These checks make a
    # future sibling-leg miss FAIL the gate (Terra R23 + Sonnet5 R23). (TERRA22-04 and
    # S23-P1-3 were RETIRED at V31 with the operator re-scope — the SOL20-04 pre-dispatch
    # commit gate they anchored on is removed from the plan.)
    "TERRA23-01", "S23-P1-2", "OPUS22",
    # R24: the META-PROBLEM fold — generalize the gate to LIFECYCLE + CROSS-FILE misses
    # (Opus R24 + Sol R24). Each has an adversarial-revert test.
    "R24-01", "R24-02", "SOL24-01", "SOL24-03", "SOL24-03-status", "OPUS22-AC11", "OPUS22-AC18",
    # R25 (Opus R25 + Sol R25): operative-contract literals, per-surface blocked-path
    # checks, and the durable receipt pin. (V30 claimed each carried a single-leg
    # adversarial test — FALSE for five of the nine, Sol R26 SOL26-05; the meta-test in the
    # test suite now enforces the mapping. SOL25-01/-probe/-vars — the hard ledger dispatch
    # gate — were RETIRED at V31 with the operator re-scope; SOL25-04 is RETARGETED to the
    # simple one-commit §7(v) receipt form.)
    "R24-02-schema", "R25-01",
    "SOL25-02-step", "SOL25-02-gate", "SOL25-02-ac22", "SOL25-04",
    # V31 (operator re-scope 2026-07-16 + Fable/Sol R26 + the executed rehearsal): the
    # PRESERVE oracle, the terminal-artifact-manifest blocked-path item (per surface), the
    # rollback-copy/DACL-save items, the durable-root declaration (Sol R26 mutation C), and
    # the kept T8 terminal-transition contract. Each has a single-leg test (meta-test-mapped).
    "F26-01", "F26-02-step", "F26-02-gate", "F26-02-ac22", "F26-03",
    "R25-01-root", "V31-T8-RECONCILE",
}
 
CHECKS: list[Check] = [
    Check("O16-P1-1", "fetch pins the migration branch",
          new="OC_MIGRATION_BRANCH", region=_T1_STEP3, gone=["main:occ-import"]),
    Check("SOL17-01", "T1 asserts the POST-filter path + exact tip",
          new="oc_chat/oc_chat/scripts/py_link_check.py", region=_T1_STEP3,
          gone=["occ-import:oc_chat/scripts/py_link_check.py"]),
    Check("O16-P1-3", "session-log against real symbols", new=None,
          gone=["update_changelog", "open(CHANGELOG_PATH", "core/changelog.py:"]),
    Check("V17-1", "rehearsal on a MERGED copy of both repos", new="MERGED throwaway copy of BOTH repos",
          region=_T1_REHEARSAL, gone=["calibrated RED-then-GREEN on the rehearsal clone"]),
    Check("V17-3", "freeze-lift order fixed at the STEP", new=None,
          gone=["no evidence write, no failure-capable gate",
                "LIFT the freeze + write the SEPARATE"]),
    Check("V17-4", "ledger schema carries terminal fields",
          new="expected_terminal_transition", region=_T0_LEDGER),
    Check("V17-6", "DACL /save AT THE T8 STEP", new="/save", region=_T8_CLOSE,
          gone=[]),  # /restore lives in the reversal-record line, a different region; /save at the step is the landing
    Check("SOL16-03-parent-acl", "archive parent-ACL + independent copy AT THE T8 STEP",
          new="rollback copy of the archive medium", region=_T8_CLOSE),
    Check("SOL14-07-rollback-tags", "rollback deletes imported tag refs AT §2.4",
          new="oc_chat-v*", region=_S24_ROLLBACK),
    Check("13b", "143-family is SIX, 143h merged", new=None,
          gone=["the five members", "the 5 members", "all five members"]),
    Check("SOL16-01", "D4 is a distribution-supply defect at the STEP",
          new="prove it in a `--no-index` venv", region=_T2_D4,
          gone=["oc-diagnostics>=2.0.0` (D4)", "D4 — dist-name fix", "dist-name mismatch"]),
    Check("D4-gate-ac", "D4 Gate/AC no longer gate on the cosmetic spelling grep", new=None,
          gone=["D4 verified (`pip check`", "hyphenated-form grep-zero",
                "post-reinstall `python -m pip check` exits 0 AND a grep-zero"]),
    Check("O16-P2-1", "false dev-count receipt deleted", new=None, gone=["0.8.0.dev894"]),
    Check("O16-P2-2", "hardcoded tag counts gone", new=None,
          gone=["EXACTLY the 11", "the 11 renamed", "option_c's own 5", "option_c's own **5**"]),
    Check("O17-P1-4", "no garbled mechanical-replace corruption", new=None,
          gone=["<path> the bare-`main`", "unless the confirmed mechanism supersedes static fields"]),
    Check("O17-P2-2", "pyproject dep-cite re-derived", new=None, gone=["pyproject.toml:41-42"]),
    Check("O19-P1-1", "T0 Gate verifies peeled target, not existence-only", new="PEELED target", region=_T0_GATE),
    Check("SOL14-04", "the real terminal command is present at the canonical close step so that replacing it with prose fails the check",
          new="plan_status set --status Completed --path", region=_T8_MIRROR),
    Check("SOL17-03", "no active ref to the removed writer", new=None,
          gone=["changelog.py:6", "CHANGELOG is updated automatically"]),
    # (TERRA22-04 retired at V31 — the operator re-scope removed the SOL20-04 pre-dispatch
    # commit gate from AC row 22; the kept T8 contract is guarded by V31-T8-RECONCILE below.)
    Check("TERRA23-01", "the T0 tag receipt is external + carried by the ledger schema, not a report-T0 self-reference",
          new="tag_receipt_sha256", region=_T0_LEDGER,
          gone=["preexisting:false}` is written into report-T0"]),
    Check("S23-P1-2", "the T8 Gate does not name validate_migration.py as a T0-dispatch check", new=None,
          gone=["`validate_migration.py` preflights the required-registry mode"]),
    # (S23-P1-3 retired at V31 — the SOL20_04_FIX_COMMIT variable it declared canonical was
    # itself removed from §1.0 by the operator re-scope.)
    Check("OPUS22", "the T2 Gate asserts positive workspaces-row equality, not the retired negative check",
          new="its `workspaces` identity row asserted to equal the pinned", region=_T2_GATE,
          gone=["NO `Option_C` literal in the workspaces row"]),
    # R24 (V29 — Opus R24 + Sol R24): the META-PROBLEM fold. V28's per-finding checks caught
    # REWORDED-sibling misses but were blind to (a) LIFECYCLE-completeness misses and (b) CROSS-FILE
    # misses. These generalize the gate so both classes now FAIL mechanically.
    # V30 (Sol R25 SOL25-03): the two lifecycle literals are now the smallest complete OPERATIVE
    # contracts — the V29 token forms passed Sol's two executed single-leg mutations (delete the
    # custody assertion / the baseline comparison while the token survives nearby).
    Check("R24-01", "lifecycle: the t8 close order performs the tag receipt custody action — the operative contract, not the filename token",
          new="exists + hash unchanged (== ledger entry 0's `tag_receipt_sha256`",
          region=_T8_CLOSE),
    Check("R24-02", "lifecycle: the t8 freeze marker re check names its ledger baseline — the operative comparison, not the field token",
          new="== ledger entry 0's `freeze_marker_sha256`", region=_T8_CLOSE),
    Check("R24-02-schema", "lifecycle: the ledger schema carries the freeze marker hash field",
          new="freeze_marker_sha256", region=_T0_LEDGER),
    Check("SOL24-01", "the append only chain integrity claim is downgraded to the honest mutable ledger model", new=None,
          gone=["binds forward via the append-only"]),
    Check("SOL24-03", "cross file: the retired report t0 receipt model is absent from the deferred tooling doc", new=None,
          gone=["hash-chained into report-T0"], source="deferred"),
    Check("SOL24-03-status", "the retired report t0 tag mapping receipt phrasing is gone from the plan status and gate note", new=None,
          gone=["report-T0 tag mapping receipt", "report-T0 mapping receipt"]),
    Check("OPUS22-AC11", "ac row 11 asserts the positive workspaces equality not the retired negative",
          new="ASSERTED to EQUAL the pinned", region=_AC11),
    Check("OPUS22-AC18", "ac row 18 asserts the positive workspaces equality via the sol22 producer",
          new="REWRITTEN and ASSERTED == pinned", region=_AC18),
    # R25 (V30 — Opus R25 + Sol R25).
    Check("R25-01", "the tag receipt is pinned under the durable artifact root, not at an arbitrary out of worktree path",
          new="T0_TAG_RECEIPT_PATH      = <MIGRATION_ARTIFACT_ROOT>", region=_S10_VARS,
          gone=["T0_TAG_RECEIPT_PATH      = <dispatch-pinned"]),
    # (SOL25-01/-probe/-vars retired at V31 — the operator re-scope re-classified the
    # authenticated ledger as tracked post-migration hardening; its dispatch gate, probe,
    # and §1.0 variable are removed from the plan.)
    Check("SOL25-02-step", "the t8 step blocked path set carries the tag receipt re check and the new close items",
          new=_BLOCKED_WINDOW, region=_T8_FAILPATH),
    Check("SOL25-02-gate", "the t8 gate blocked path set carries the tag receipt re check and the new close items",
          new=_BLOCKED_WINDOW, region=_T8_GATE_BLOCKED),
    Check("SOL25-02-ac22", "the ac row 22 blocked path set carries the tag receipt re check and the new close items",
          new=_BLOCKED_WINDOW, region=_AC22_ATOMIC),
    Check("SOL25-04", "section 7 clause v is the simple one commit receipt form run against the committed head",
          new="run `python tools/plan_fold_gate.py` "
              + "in committed-HEAD mode and confirm the SAME green result", region=_S7_V,
          gone=["records `C`'s SHA, every audited source's blob hash"]),
    # V31 (operator re-scope 2026-07-16 + Fable/Sol R26 + the executed rehearsal).
    Check("F26-01", "the t2 preserve equality oracle is the stripped payload content hash, never the re-export file sha",
          new="the `exported_at`/`signature`-stripped payload "
              "content hash MATCH the T0 receipt", region=_T2_GATE,
          gone=["re-export SHA-256 against T0's receipt",
                "re-export SHA-256 MATCH the T0 receipt",
                "re-export SHA matched"]),
    Check("F26-02-step", "the t8 step blocked path set carries the terminal artifact manifest item in position",
          new=_MANIFEST_WINDOW, region=_T8_FAILPATH),
    Check("F26-02-gate", "the t8 gate blocked path set carries the terminal artifact manifest item in position",
          new=_MANIFEST_WINDOW, region=_T8_GATE_BLOCKED),
    Check("F26-02-ac22", "the ac row 22 blocked path set carries the terminal artifact manifest item in position",
          new=_MANIFEST_WINDOW, region=_AC22_ATOMIC),
    Check("F26-03", "the t8 step blocked path set carries the rollback copy and dacl save items",
          new="**independent rollback-copy verified**, "
              "**archive+parent DACL `/save` verified**", region=_T8_FAILPATH),
    Check("R25-01-root", "the migration artifact root declaration keeps its durable comment (sol r26 mutation c)",
          new="# the DURABLE terminal-evidence root", region=_S10_VARS),
    Check("V31-T8-RECONCILE", "ac row 22 carries the kept t8 contract, monorepo cwd both surfaces and manual reconcile",
          new="documented MANUAL reconcile path on divergence", region=_AC22_ATOMIC),
]
 
 
def evaluate(text: str, check: Check) -> list[str]:
    """THE production predicate. Return the problems for ``check`` against ``text``
    (empty list == pass). Tests call THIS — they do not re-implement it (SOL18-01)."""
    problems: list[str] = []
    if check.new is not None:
        if check.region is None:
            problems.append(f"NEW {check.new!r} has no region (a whole-doc NEW is not a landing)")
        else:
            span = check.region.slice(text)
            r = check.region
            if span is None:
                problems.append(f"region {r.label!r} not found (start anchor moved)")
            elif text.count(r.start) != 1:
                # START-UNIQUENESS (Sol R20 SOL20-03): a start anchor identifies WHICH
                # region. If it appears more than once, slice() silently picks the first
                # occurrence and a cross-site copy (correction prose, a diagnosis paragraph)
                # can stand in for the executing action. Require exactly one match.
                problems.append(f"region {r.label!r} start anchor {r.start!r} is AMBIGUOUS "
                                f"(appears {text.count(r.start)}x, must be exactly 1) — "
                                "cross-site prose could substitute for the executing action")
            elif r.end is not None and r.end not in text[text.find(r.start):]:
                # REGION-INTEGRITY (Opus R19 O19-P0-1): a dead `end` anchor makes slice()
                # fall through to EOF, silently degrading the region to a whole-tail match.
                problems.append(f"region {r.label!r} end anchor {r.end!r} DEAD "
                                f"(span ran to EOF, {len(span)} chars) — region-scoping defeated")
            elif len(span) > _REGION_MAX:
                problems.append(f"region {r.label!r} span {len(span)} > {_REGION_MAX} "
                                "(anchor too loose to be an executing site)")
            elif check.new not in span:
                problems.append(f"NEW {check.new!r} ABSENT from {r.label}")
    for g in check.gone:
        if g in text:
            problems.append(f"RETIRED {g!r} SURVIVES")
    return problems
 
 
def _manifest_problems() -> list[str]:
    """Return problems if CHECKS and MANIFEST have drifted (a required finding uncovered, or a check not in the manifest)."""
    fids = {c.fid for c in CHECKS}
    problems = []
    for missing in sorted(MANIFEST - fids):
        problems.append(f"manifest ID {missing!r} has NO check (a required finding is uncovered)")
    for extra in sorted(fids - MANIFEST):
        problems.append(f"check {extra!r} is NOT in the manifest (denominator drift)")
    return problems
 
 
def read_source(rel_path: str, worktree: bool) -> str | None:
    """Return a source file's text: the committed HEAD blob (authoritative) or the worktree.
    Generalizes ``read_plan`` so a CROSS-FILE check can gate a second file (V29 SOL24-03)."""
    func = "read_source"
    _dbg("OC_CHAT.MAIN", func, f"{rel_path} worktree={worktree}", 4)
    if worktree:
        p = _REPO / rel_path
        return p.read_text(encoding="utf-8") if p.is_file() else None
    proc = subprocess.run(
        ["git", "show", f"HEAD:{rel_path}"], cwd=str(_REPO),
        text=True, capture_output=True, encoding="utf-8",
    )
    return proc.stdout if proc.returncode == 0 else None
 
 
def read_plan(worktree: bool) -> str | None:
    """Return the plan text (back-compat shim over :func:`read_source`)."""
    return read_source(PLAN, worktree)
 
 
def run(worktree: bool) -> int:
    """Evaluate every check, print the labelled receipt, return the process exit code."""
    func = "run"
    texts: dict[str, str] = {}
    for name, rel in _SOURCES.items():
        t = read_source(rel, worktree)
        if not t:
            print(f"!! could not read {rel}", file=sys.stderr)
            return 2
        texts[name] = t
    src = "WORKTREE" if worktree else "HEAD"
    print(f"fold landing gate, region scoped and exact substring, at {src}")
    # Enumerate EVERY audited source (V30 — Sol R25 SOL25-03: the old banner named only
    # the plan even when the cross-file deferred doc affected the result).
    for name in sorted(_SOURCES):
        print(f"audited source {name}: {_SOURCES[name]} at {src}")
    print("=" * 80)
    fails = 0
    for c in CHECKS:
        problems = evaluate(texts[c.source], c)
        print(f"[{'PASS' if not problems else 'FAIL'}] {c.fid:24} {c.name}")
        for p in problems:
            print(f"         - {p}")
        if problems:
            fails += 1
    mprobs = _manifest_problems()
    for p in mprobs:
        print(f"[FAIL] MANIFEST                  {p}")
    total = len(CHECKS) + (1 if mprobs else 0)
    fails += 1 if mprobs else 0
    print("=" * 80)
    print(f"{total - fails} of {total} checks pass and {fails} failed. the new text is region scoped and the retired text is gone; the human concept audit is still required.")
    _dbg("OC_CHAT.MAIN", func, f"{total - fails}/{total} pass ({src})", 2)
    return 1 if fails else 0
 
 
def main(argv: list[str] | None = None) -> int:
    """CLI entry point."""
    func = "main"
    # Initialize diagnostics before the first _dbg so the CLI run does not emit
    # "RuntimeWarning: _dbg() called before init()" (Opus R19/R20 O19-P3-1). Streams
    # and exceptions are NOT intercepted — the gate owns its stdout receipt, and
    # stream interception swallows summary lines (see the pytest-summary lesson).
    oc_diagnostics.init(intercept_streams=False, intercept_exceptions=False)
    _dbg("OC_CHAT.MAIN", func, "parsing args", 4)
    ap = argparse.ArgumentParser(prog="plan_fold_gate.py", description="Fold-landing gate for plan 151.")
    ap.add_argument("--worktree", action="store_true",
                    help="gate the working tree instead of the committed HEAD blob")
    args = ap.parse_args(argv)
    return run(args.worktree)
 
 
if __name__ == "__main__":
    raise SystemExit(main())