criterion.py

"""Selection rule shared by live agents and bounded catch-up extraction.

Book records require evidence and a future question. Only trail changes
require explicit human approval. This rule is injected at session start.
"""
from __future__ import annotations

# The closed list. Nothing outside it qualifies for automatic recording. Each is written to
# be recognised, not weighed: if you are arguing about whether one fired, it
# did not.
TRIGGERS: list[tuple[str, str]] = [
    ("T1", "the owner states a rule, preference, correction or decision"),
    ("T2", "a measurement — a number, count, rate or pass/fail from running something"),
    ("T3", "a cause established — \"X is broken BECAUSE Y\", with the evidence named"),
    ("T4", "an external source read that changed a decision"),
    ("T5", "a capability boundary moved — possible became impossible, or the reverse"),
    ("T6", "a recorded claim contradicted — a Book says X, we established not-X"),
]

# Where drift actually happens. Naming them is cheaper than re-deciding.
EXCLUDED = ("progress, plans, intentions, \"it works now\", restatements of a "
            "file, and anything git or `--help` answers in under a minute")

# If the criterion is right this is the rate. Zero in a session that established
# six things is a miss; a dozen is drift. A number makes it auditable instead of
# believed.
EXPECTED_PER_SESSION = (2, 5)


def render() -> str:
    """Shared by Claude, Codex and the bounded catch-up extractor."""
    rows = "\n".join(f"   {code}  {what}" for code, what in TRIGGERS)
    return (
        "## Record Books automatically; Button only for trails\n"
        "Both Claude and Codex record qualifying\n"
        "knowledge DURING the live turn, without asking for fact acceptance.\n"
        "Use the current agent; do not launch another model to record a live turn.\n\n"
        "**1. Match one of the six recording triggers:**\n" + rows + "\n\n"
        "**2. Name the future question and the evidence/referent a reader can inspect.**\n"
        "Either missing: do not record automatically. Establish claims from evidence;\n"
        "attribute reported results and preserve uncertainty instead of upgrading them to facts.\n"
        f"Exclude: {EXCLUDED}. Expected 2–5 records is a diagnostic, never a quota.\n\n"
        "Write now: `memex note BOOK TEXT --trigger T# --referent EVIDENCE --question QUESTION`.\n"
        "Use `--replaces OLD` only for an established T6 correction; research stays append-only.\n"
        "Manual `/memex-input` remains available: `--manual` records an explicit user request.\n"
        "Do not label automatic/manual records `--agreed`; that means exact human assent.\n"
        "Only a TRAIL creation/change needs the Button: show the route, step and quoted reason,\n"
        "then use `memex tie ... --agreed` or `pending --accept ID --agreed` after the owner says yes.\n"
        "Links/references may be recorded freely; do not invent causal trail steps.\n"
    )