#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""one_register_gate.py — ONE register. Operator ruling, 2026-08-22 (R-369).

WHAT IT CONVICTS ON (a FAIL, exit 1): a row in `ROADMAP.md` that is
  * neither an IDEA (a proposal for something that does not exist yet), nor
  * DONE (shipped / closed / killed / ruled / moved),
and that has **no counterpart row in `OPEN-ITEMS.md`**.

WHY IT EXISTS, and the cost that bought it. Two files held open work and only one of them called
itself the source of truth. R-107 — "no offsite action unpacks the named-volume tars Tier-3
captures" — was written up properly on 2026-07-28, marked READY, and put here. Every standing rule
says "grep the register before minting", and every one of them greps the other file. So it was
invisible, and on 2026-08-21 an overnight drill rediscovered it from scratch by planting files and
watching them not come back. **25 days.**

THE PREDICATE IS THE ROADMAP'S OWN STATE COLUMN, deliberately — it already distinguishes `idea` from
`READY`, so this gate reads data that exists rather than asking anyone to maintain a new marker.

WHAT THIS GATE CANNOT SEE — the residual holes, named rather than implied:

  1. **A finding filed with the state `idea` escapes.** The state column is a human judgement, and a
     defect written under `idea` looks exactly like a proposal to this gate. It is the same shape as
     the problem it fixes, one level up.
  2. **A finding written in prose with no `R-` identifier escapes entirely.** This gate matches ids.
     A survey that enumerates a gap and never numbers it is invisible here — that is the previous
     session's sweep territory and the PROMPT-TEMPLATE rule "an enumerated gap becomes a row".
  3. **A finding that never reaches the roadmap at all escapes.** Nothing here reads audits, spikes
     or inventories.
  4. It checks that a counterpart EXISTS, never that the two say the same thing. A stale register row
     beside a live roadmap row passes.

Run:  python3 scripts/one_register_gate.py [--fast]
"""
import io
import os
import re
import sys

ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
ROADMAP = os.path.join(ROOT, "documentation", "backlog", "ROADMAP.md")
REGISTER = os.path.join(ROOT, "documentation", "backlog", "OPEN-ITEMS.md")

ROW = re.compile(r"^\|\s*\*{0,2}R-(\d+)\*{0,2}\s*\|")
# DONE and IDEA are matched against the row's STATE cell only, never the whole row: the body of a
# finding routinely contains the word "shipped" while describing something else.
# BANKED and PROVEN-LIVE are this project's own done-words and were found by running the gate: a row
# reading "BANKED in full" or "first slice PROVEN-LIVE" is shipped work, not an open finding.
DONE = re.compile(r"\b(SHIPPED|CLOSED|KILLED|DONE|SUPERSEDED|OBSOLETE|WITHDRAWN|MERGED|DISCHARGED|"
                  r"RULED|MOVED|BANKED|PROVEN-LIVE)\b", re.I)
IDEA = re.compile(r"\b(IDEA|SPIKED|PARKED|DEFERRED|BACKLOG|PROPOSAL)\b", re.I)


def rows(path):
    """Yield (id, state_cell, whole_line) for every R- row in a pipe table."""
    for line in io.open(path, encoding="utf-8"):
        line = line.rstrip("\n")
        m = ROW.match(line)
        if not m:
            continue
        cells = line.split("|")
        state = cells[4].strip() if len(cells) > 4 else ""
        yield m.group(1), state, line


def main():
    if not os.path.exists(ROADMAP) or not os.path.exists(REGISTER):
        print("one-register gate: a backlog file is missing — FAILURE, never a skip")
        return 1

    have = set(rid for rid, _, _ in rows(REGISTER))
    offenders, ideas, done, ok = [], 0, 0, 0
    for rid, state, line in rows(ROADMAP):
        if DONE.search(state):
            done += 1
            continue
        if IDEA.search(state):
            ideas += 1
            continue
        if rid in have:
            ok += 1
            continue
        title = re.sub(r"\s+", " ", line.split("|")[2] if len(line.split("|")) > 2 else line)
        offenders.append((rid, state, title.strip()[:120]))

    print("one-register gate — ROADMAP rows: %d done, %d ideas, %d open-with-a-register-row, "
          "%d WITHOUT" % (done, ideas, ok, len(offenders)))

    if offenders:
        print()
        print("CONVICTED — open work in ROADMAP.md with no row in OPEN-ITEMS.md:")
        for rid, state, title in offenders:
            print("   R-%-5s state=%-24s %s" % (rid, state[:24], title))
        print()
        print("OPEN-ITEMS.md is the single source of truth for open work (its own first line).")
        print("Either move the row there keeping its id and filing date, or — if it is a proposal for")
        print("something that does not exist yet — mark its state `idea`, which is what it is.")
        return 1

    print("one-register gate OK — every open ROADMAP row has a register counterpart.")
    return 0


sys.exit(main())