@r1z4x/tezgah 1.9.2 → 1.13.0

package/bin/tezgah-skill

@@ -25,7 +25,7 @@ import json
 import os
 import sys
 
-HERE = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+HERE = os.path.dirname(os.path.dirname(os.path.realpath(__file__)))
 sys.path.insert(0, os.path.join(HERE, "hooks"))
 import tezgah_skill_pick as sp  # noqa: E402
 

package/bin/tezgah-status

@@ -29,6 +29,22 @@ their status line; this CLI is how every host (and a human) gets it:
                            The MCP half of a retirement decision is manual:
                            `tezgah-setup --mcp-schemas` measures what a server
                            costs, this counts what it fires.
+  tezgah-status --rates --since DATE --until DATE [--json]
+                           every real ledger's rows in [since, until), folded per
+                           window and per calendar day: turns, `claim` rows and
+                           the Stop classes that blocked them, the shape flags
+                           every judged reply carried, denies by rule, and the
+                           rates (blocks per 100 turns, denies per 100 sessions,
+                           the claim block and Stop shape shares, blocked claims
+                           per 100 sessions by class). A repeated `--since`/
+                           `--until` pair prints one block each and the pp delta
+                           between adjacent windows - the unit plan 066's 056 row
+                           states its bar in. A window that read more than one
+                           row contract prints the split, and a delta across two
+                           contracts says so (plan 135). `--json` prints
+                           `{"windows": [...]}`.
+                           `--until` is exclusive, so adjacent windows partition
+                           their span.
   tezgah-status --skill-fitness
                            per shipped skill, over the recorded sessions: how
                            many opened it and which were never opened. A
@@ -78,6 +94,16 @@ their status line; this CLI is how every host (and a human) gets it:
                            the set renders as dim "no state" instead of claiming
                            "armed, not used yet". A host that cannot see a skill
                            read (dsh) passes the tool-use four.
+  tezgah-status --manifest=FILE
+                           read the repository extension from FILE instead of
+                           the `.tezgah/extension.json` discovered from PATH (a
+                           manifest outside the tree, e.g. an engagement's).
+                           With `statusline.override: true` in the manifest the
+                           project owns its line and points its own statusLine
+                           here: the host's status-line payload on stdin (its
+                           `cwd`/`workspace.current_dir` and `session_id`) is
+                           read when no PATH is given, so this is the only line
+                           and it keeps the built-in marks and the chips.
 
 The session id may be passed as the second argument or via TEZGAH_SESSION;
 without it the "used" marks cannot light up, so a host that knows the id should
@@ -97,6 +123,26 @@ from tezgah_context import (  # noqa: E402
 # the line and `--json` carries every row, so a reader can always see what was
 # cut.
 TOP = 15
+# The host payload an override reads on stdin: a status-line host writes one
+# small JSON object and closes the pipe, so the read is bounded in bytes and in
+# how long an empty pipe is waited for - a caller that never writes costs this
+# long, never a hang.
+PAYLOAD_MAX = 65536
+PAYLOAD_WAIT = 0.2
+
+
+def host_payload():
+    """The status-line host's JSON payload on stdin, or {} - a terminal, an
+    empty or silent pipe, malformed JSON or no stdin at all."""
+    import select
+    try:
+        if sys.stdin.isatty() or not select.select([sys.stdin], [], [],
+                                                   PAYLOAD_WAIT)[0]:
+            return {}
+        payload = json.loads(sys.stdin.read(PAYLOAD_MAX) or "{}")
+    except (OSError, ValueError, AttributeError):
+        return {}
+    return payload if isinstance(payload, dict) else {}
 
 
 def weeks_arg(args):
@@ -241,6 +287,115 @@ def print_orca(cwd, as_json):
     return 0
 
 
+def window_pairs(args):
+    """`args` with the `--since`/`--until` pairs folded out, and the pairs in the
+    order written. Each `--until` closes the `--since` before it, and a flag
+    without its partner is ValueError: half a window is a question the reader
+    did not finish asking.
+
+    The spaced form is read here for the reason `--weeks`' is: the split in
+    `main` sends every non-`--` argument to `pos`, where a date would be read as
+    a session id."""
+    out, pairs, since, i = [], [], None, 0
+    while i < len(args):
+        a = args[i]
+        name = a.split("=", 1)[0]
+        if name not in ("--since", "--until"):
+            out.append(a)
+            i += 1
+            continue
+        if "=" in a:
+            value, i = a.split("=", 1)[1], i + 1
+        else:
+            value = args[i + 1] if i + 1 < len(args) else ""
+            i += 2 if i + 1 < len(args) else 1
+        if name == "--since":
+            if since is not None:
+                raise ValueError("--since %s has no --until" % since)
+            since = value
+        else:
+            if since is None:
+                raise ValueError("--until %s has no --since" % value)
+            pairs.append((since, value))
+            since = None
+    if since is not None:
+        raise ValueError("--since %s has no --until" % since)
+    return out, pairs
+
+
+def share(value, numerator, denominator):
+    """A share in the unit 056's `+2 pp` bar reads, or `n/a` with no
+    denominator - a window that decided nothing has no rate."""
+    return ("n/a" if value is None
+            else "%.2f%% (%d/%d)" % (100 * value, numerator, denominator))
+
+
+def dominant_contract(window):
+    """The row contract that wrote most of a window's rows, or `-` for a window
+    that read none. `claims` is one quantity under a contract and another across
+    a change to it (plan 135), so the delta line names both sides' contract."""
+    counts = window.get("row_versions") or {}
+    if not counts:
+        return "-"
+    return max(sorted(counts), key=lambda name: counts[name])
+
+
+def print_rates(found):
+    """The windowed rates, for `--rates`: one block per window, then the pp delta
+    between each adjacent pair - the unit plan 066's rows state their bars in."""
+    for w in found:
+        rates = w["rates"]
+        print("window %s..%s: %d days, %d sessions, %d turns, %d claims, %d "
+              "replies" % (w["since"], w["until"], w["days"], w["sessions"],
+                           w["turns"], w["claims"], w["replies"]))
+        for key, label in (("blocked_claims", "blocked_claims"),
+                           ("shapes", "stop shapes"), ("denies", "denies")):
+            print("  %-15s %s" % (label, ", ".join(
+                "%s=%d" % kv for kv in sorted(w[key].items())) or "none"))
+        print("  %-15s %d" % ("shape_blocked", w["shape_blocked"]))
+        print("  %-15s blocks/100 turns %s, denies/100 sessions %s" % (
+            "rates", "n/a" if rates["blocks_per_100_turns"] is None
+            else "%.4f" % rates["blocks_per_100_turns"],
+            "n/a" if rates["denies_per_100_sessions"] is None
+            else "%.4f" % rates["denies_per_100_sessions"]))
+        print("  %-15s claim block %s, stop shape %s" % (
+            "shares", share(rates["claim_block_rate"],
+                            sum(w["blocked_claims"].values()), w["claims"]),
+            share(rates["stop_shape_rate"], w["shape_flagged"], w["replies"])))
+        print("  %-15s %s" % ("blocked/100 sess", ", ".join(
+            "%s=%.4f" % kv for kv in
+            sorted(rates["blocked_claims_per_100_sessions"].items()))
+            or "none"))
+        # Which row contract wrote the rows, printed only when a window mixes
+        # two: `claims` means "every judged reply" before ROW_VERSION 3 and "a
+        # reply that claimed" after it, so a share read off a mixed or shifted
+        # window is not the same quantity as its neighbour's (plan 135).
+        if len(w["row_versions"]) > 1:
+            print("  %-15s %s" % ("contracts", ", ".join(
+                "%s=%d" % kv for kv in sorted(w["row_versions"].items()))))
+    for before, after in zip(found, found[1:]):
+        parts, unknown, over = [], False, False
+        for key, label in (("claim_block_rate", "claim block"),
+                           ("stop_shape_rate", "stop shape")):
+            a, b = before["rates"][key], after["rates"][key]
+            if a is None or b is None:
+                unknown = True
+                parts.append("%s n/a" % label)
+                continue
+            parts.append("%s %+.2f pp" % (label, 100 * (b - a)))
+            over = over or round(b - a, 4) > 0.02
+        shift = dominant_contract(before) != dominant_contract(after)
+        print("delta %s..%s -> %s..%s: %s; 056 bar (+2 pp): %s%s" % (
+            before["since"], before["until"], after["since"], after["until"],
+            ", ".join(parts),
+            "unreadable (no denominator in a window)" if unknown
+            else "FAILS" if over else "holds",
+            "; the two windows' rows come from different contracts (%s vs %s), "
+            "so the shares are not one quantity" % (
+                dominant_contract(before), dominant_contract(after))
+            if shift else ""))
+
+
 def main():
     # `--` ends the options: what follows is PATH and SESSION_ID even when it
     # starts with a dash. The dsh route and the MCP tool hand caller-chosen
@@ -250,6 +405,11 @@ def main():
     rest = argv[argv.index("--") + 1:] if "--" in argv else []
     argv = argv[:argv.index("--")] if "--" in argv else argv
     args, weeks = weeks_arg(argv)
+    try:
+        args, windows = window_pairs(args)
+    except ValueError as err:
+        sys.stderr.write("tezgah-status: %s\n" % err)
+        return 2
     # A sanity bound, not a policy: ten years of weeks is longer than any ledger
     # this machine holds, and a number the reader mistyped should say so rather
     # than print a thousand rows of nothing.
@@ -260,9 +420,11 @@ def main():
     pos = [a for a in args if not a.startswith("--")] + rest
     known = {"--legend", "--json", "--color", "--no-color", "--counters",
              "--all", "--trend", "--skill-fitness", "--failure-shapes",
-             "--rule-yield", "--enforcers", "--orca", "--judge", "--help"}
+             "--rule-yield", "--enforcers", "--orca", "--judge", "--rates",
+             "--help"}
     unknown = sorted(f for f in flags
-                     if f not in known and not f.startswith("--observable="))
+                     if f not in known
+                     and not f.startswith(("--observable=", "--manifest=")))
     if unknown:
         sys.stderr.write("tezgah-status: unknown option(s): %s (try --help)\n"
                          % ", ".join(unknown))
@@ -293,6 +455,26 @@ def main():
         sys.stderr.write("tezgah-status: %s only means something with "
                          "--counters\n" % modifier)
         return 2
+    if windows and "--rates" not in flags:
+        sys.stderr.write("tezgah-status: --since/--until only mean something "
+                         "with --rates\n")
+        return 2
+    if "--rates" in flags and not windows:
+        sys.stderr.write("tezgah-status: --rates wants --since and --until\n")
+        return 2
+    if "--rates" in flags:
+        import tezgah_integrity as ti
+        try:
+            found = [ti.rates(since, until) for since, until in windows]
+        except ValueError as err:
+            sys.stderr.write("tezgah-status: %s\n" % err)
+            return 2
+        if "--json" in flags:
+            # one shape for one window and for many: a consumer never branches
+            print(json.dumps({"windows": found}, sort_keys=True))
+            return 0
+        print_rates(found)
+        return 0
     if "--judge" in flags:
         import tezgah_judge as tj
         last = tj.last_use()
@@ -430,7 +612,23 @@ def main():
     spec = next((f.split("=", 1)[1] for f in flags
                  if f.startswith("--observable=")), None)
     observable = set(spec.split(",")) if spec else None
-    segs = health_segments(cwd, session, observable=observable)
+    manifest = next((f.split("=", 1)[1] for f in flags
+                     if f.startswith("--manifest=")), None) or None
+    if not pos:
+        import tezgah_extension
+        if tezgah_extension.override(cwd, manifest):
+            # the project's own statusLine runs this renderer: the host says
+            # which directory and session the line is for
+            payload = host_payload()
+            workspace = payload.get("workspace")
+            where = ((workspace.get("current_dir")
+                      if isinstance(workspace, dict) else None)
+                     or payload.get("cwd"))
+            if isinstance(where, str) and where:
+                cwd = os.path.realpath(where)
+            if isinstance(payload.get("session_id"), str) and payload["session_id"]:
+                session = payload["session_id"]
+    segs = health_segments(cwd, session, observable=observable, manifest=manifest)
     if "--json" in flags:
         print(json.dumps(segs))
         return 0

package/bin/tezgah-task

@@ -6,7 +6,7 @@
   tezgah-task allow GLOB ... | --any-path --why REASON         replace the allowlist, recording why
   tezgah-task stop                                            deactivate (clear phase)
   tezgah-task status [--json]                                 the active task, then every open plan: progress, what it waits on, what can run at once
-  tezgah-task review <NNN|path> <reviewer> approve|changes    record a fresh review's verdict
+  tezgah-task review <NNN|path> <reviewer> approve|changes [--no-slice WHY]  record a fresh review's verdict; approve needs the reviewer's slice record, or WHY it has none
   tezgah-task close <NNN|path> done|discarded [--resolved TEXT] move a plan to .tezgah/plans/done, deactivate it, remove merged worktrees
   tezgah-task tick <NNN|path> <n> [--undo]                   tick (or untick) Acceptance item n, counted from 1
   tezgah-task note <NNN|path> state|next "<text>"            replace the body of `## State` (the newest one) or `## Next`
@@ -122,7 +122,10 @@ history) is printed as `not judged` and the exit is 1. `review ... approve`
 is refused while a record whose id or agent is that reviewer is not done.
 
 Exit codes: 0 ok, 1 a refusal or a problem - one `FAIL <what>` line per problem,
-with nothing written - 2 misuse.
+with nothing written - 2 misuse. In a repository whose `tezgah.owner` says
+`tasks: off` (or `harness: excluded`) every command above that writes a record
+is refused, and the read-only ones still answer
+(`bin/tezgah-task::owner_mark`).
 """
 import glob
 import json
@@ -136,7 +139,12 @@ import time
 HERE = os.path.dirname(os.path.dirname(os.path.realpath(__file__)))
 sys.path.insert(0, os.path.join(HERE, "hooks"))
 import tezgah_task as tt  # noqa: E402
-from tezgah_paths import project_top, say, work_tree  # noqa: E402
+from tezgah_paths import config, ocr_bin, omp_bin, project_top, say, work_tree  # noqa: E402
+
+# Mirrors hooks/tezgah_gate.py::PLAN_TRUNKS: the gate reads these as unplanned
+# whatever a plan declares, so `start --branch` refuses them (plan 113). Not
+# imported: the gate hook pulls in every rule module for this one tuple.
+PLAN_TRUNKS = ("main", "master")
 
 
 def repo_root(path):
@@ -152,6 +160,43 @@ def repo_root(path):
     return os.path.realpath(path)
 
 
+# Commands that write a plan's record. A repository that carries `tezgah.owner`
+# saying `tasks: off` (or `harness: excluded`) keeps its records to itself: the
+# phase would arm nothing there - `tezgah_task._phased` answers no task
+# (`hooks/tezgah_paths.py::tasks_disabled`) - so writing one would report
+# success for a guard that never fired. `writes_a_record` reads both tuples, and
+# the read-only commands are untouched.
+RECORD_COMMANDS = ("start", "phase", "allow", "stop", "review", "close",
+                   "tick", "note", "spike", "unmet")
+# The journal's own writers, and `sweep`, which clears an orphan `phase:` and
+# closes the slices of the worktrees it prunes. The rest of `slice` only reads
+# (stats, board, merge-plan), and so does `status`.
+SLICE_WRITERS = ("open", "done", "stop", "reconcile", "resume")
+
+
+def writes_a_record(cmd, rest):
+    """True when this invocation writes the task machine's records: the plan
+    file, the slice journal, or the phases and slices `sweep` clears. The
+    readers write none, so a repository that is not this harness's still answers
+    them (`status`, `slice stats`, `slice board`, `slice merge-plan`)."""
+    if cmd in RECORD_COMMANDS:
+        return True
+    if cmd == "slice":
+        return bool(rest) and rest[0] in SLICE_WRITERS
+    return cmd == "sweep"
+
+
+def owner_mark(root):
+    """Why this repository's records are not this machine's to write, else
+    None. Through `tasks_disabled`, so the CLI and the gate read one answer."""
+    from tezgah_paths import OWNER_MARKER, tasks_disabled
+    if not tasks_disabled(root):
+        return None
+    return ("%s says `tasks: off` in %s: its records are the repository's own, so "
+            "this machine writes none there - edit them directly"
+            % (root, os.path.join(root, OWNER_MARKER)))
+
+
 def misuse(message):
     """Misuse exits 2, so a caller can tell it from a record that refuses."""
     print("tezgah-task: %s" % message, file=sys.stderr)
@@ -434,6 +479,139 @@ MERGE_CHECKS = (
      "python3 skills/plan-add/render_table.py --acceptance --strict"),
 )
 
+# OCR's texts vendored with tezgah (plan 125): the review prompt each per-group
+# reviewer reads as an appendix, the filter prompt the refuter pass follows
+OCR_PROMPTS = os.path.join(HERE, "third_party", "open-code-review", "prompts")
+
+
+def ocr_json(ocr, args):
+    """One `ocr delegate ... --format json` answer as a dict, or the reason it
+    is not one: a non-zero exit, a timeout, output that is not a JSON object."""
+    try:
+        out = subprocess.run([ocr, "delegate"] + args, capture_output=True,
+                             text=True, timeout=30,
+                             env=dict(os.environ, OCR_NO_UPDATE="1"))
+    except subprocess.TimeoutExpired:
+        return "`ocr delegate %s` timed out after 30 s" % args[0]
+    except OSError as exc:
+        return "`ocr delegate %s` did not start: %s" % (args[0], exc)
+    if out.returncode:
+        return "`ocr delegate %s` exited %d" % (args[0], out.returncode)
+    try:
+        data = json.loads(out.stdout)
+    except ValueError:
+        data = None
+    return data if isinstance(data, dict) else \
+        "`ocr delegate %s` printed no JSON object" % args[0]
+
+
+def ocr_spec(where, base):
+    """OCR's deterministic review spec for `base..HEAD`: (preview, rule groups,
+    the rule command), the reason it is skipped, or None without `ocr` or with
+    the `ocr` feature not enabled (`tezgah-setup --enable ocr`) - the step is
+    then today's."""
+    ocr = ocr_bin()
+    if ocr is None or "ocr" not in (config().get("features") or []):
+        return None
+    if base == "<base>":
+        return "no diff base to preview"
+    preview = ocr_json(ocr, ["preview", "--format", "json", "--from", base,
+                             "--to", "HEAD", "--repo", where])
+    if isinstance(preview, str):
+        return preview
+    # the JSON shape this reader was written against (OCR 375f64c / 1.13.2)
+    if preview.get("schema_version") != "1":
+        return "`ocr delegate preview` schema_version %r is not \"1\"" % (
+            preview.get("schema_version"),)
+    files = preview.get("reviewable_files")
+    excluded = preview.get("excluded_files", [])
+    if not isinstance(files, list) or not isinstance(excluded, list):
+        return "`ocr delegate preview` JSON has no file lists"
+    # a row with no string path is dropped here, so neither the rule argv nor
+    # the printed list can meet a None
+    files = [f for f in files if isinstance(f, dict) and isinstance(f.get("path"), str)]
+    preview["reviewable_files"] = files
+    paths = [f["path"] for f in files]
+    groups = []
+    # `--` ends OCR's options, so a changed file named like a flag stays a path
+    rule_cmd = [ocr, "delegate", "rule", "--format", "json", "--repo", where, "--"] + paths
+    if paths:
+        rule = ocr_json(ocr, rule_cmd[2:])
+        if isinstance(rule, str):
+            return rule
+        if rule.get("schema_version") != "1":
+            return "`ocr delegate rule` schema_version %r is not \"1\"" % (
+                rule.get("schema_version"),)
+        groups = rule.get("groups")
+        if not isinstance(groups, list):
+            return "`ocr delegate rule` JSON has no groups"
+    return preview, groups, rule_cmd
+
+
+def print_ocr_spec(where, base):
+    """Step 2's OCR lines: the reviewable files, the exclusions (still in scope),
+    one reviewer per rule group, the refuter pass and the quote check. Prints
+    nothing without `ocr`, one `OCR spec skipped:` line when it fails."""
+    spec = ocr_spec(where, base)
+    if spec is None:
+        return
+    if isinstance(spec, str):
+        print("     OCR spec skipped: %s" % spec)
+        return
+    preview, groups, rule_cmd = spec
+    paths = [f.get("path") for f in preview["reviewable_files"] if isinstance(f, dict)]
+    print("     OCR review spec (`ocr delegate`; its output is input to the "
+          "review, never a verdict):")
+    print("     - reviewable files (%d): %s" % (len(paths), ", ".join(paths) or "none"))
+    out = ["%s (%s)" % (f.get("path"), f.get("exclude_reason", "no reason"))
+           for f in preview.get("excluded_files", []) if isinstance(f, dict)]
+    print("     - excluded by OCR, NOT covered by OCR rules but still in the "
+          "reviewer's scope (tests and docs stay in scope; one more "
+          "tezgah-reviewer reads them over the dimensions above): %s"
+          % (", ".join(out) or "none"))
+    if groups:
+        # OCR's own bundling below its LLM-grouping threshold (task_template.json
+        # GROUPING_MIN_FILES 4, GROUPING_BUNDLE_LINE_THRESHOLD 200): fewer than 4
+        # files are one bundle under 200 changed lines, else one file each.
+        churn = sum(n for f in preview["reviewable_files"]
+                    for n in (f.get("insertions"), f.get("deletions"))
+                    if isinstance(n, int) and not isinstance(n, bool))
+        if len(paths) < 4 and churn < 200:
+            who = ("one tezgah-reviewer for the whole small change set (%d files, "
+                   "%d changed lines), its brief carrying every group's rule text"
+                   % (len(paths), churn))
+        elif len(paths) < 4:
+            who = "one tezgah-reviewer per file, in ONE message"
+        else:
+            who = "one tezgah-reviewer per rule group below, in ONE message"
+        print("     - instead of one reviewer per dimension, spawn %s: a brief "
+              "carries its group's rule text verbatim (`groups[].rule` of `%s`) "
+              "and names %s as an appendix to read; each reviewer accounts for "
+              "every file it owns as reviewed or skipped-with-reason"
+              % (who, shlex.join(rule_cmd),
+                 os.path.join(OCR_PROMPTS, "main_task_system.md")))
+        for g in groups:
+            if isinstance(g, dict):
+                print("       - rule group %s: source %s, pattern %s, files %s"
+                      % (g.get("group_id"), g.get("source"), g.get("pattern"),
+                         ", ".join(g.get("files") or []) or "none"))
+    else:
+        print("     - no OCR rule group: the dimension fan-out above stands")
+    print("     - refuter pass: after merging the findings, one fresh "
+          "tezgah-reviewer reads %s as its instructions and removes only "
+          "findings the diff proves wrong"
+          % os.path.join(OCR_PROMPTS, "review_filter_task_system.md"))
+    print("     - quote check: `tezgah-review-quote --repo %s --from %s "
+          "FINDINGS.json` over the merged findings (a JSON list of path, quote, "
+          "start_line, end_line); an `unlocated` finding goes back to its "
+          "reviewer" % (shlex.quote(where), base))
+    # V4, omp only: OCR's own loop on omp's model; candidates, never findings
+    if os.environ.get("OMPCODE") and omp_bin():
+        print("     - omp: `tezgah-ocr-review --repo %s --from %s --to HEAD "
+              "--output OCR.json` runs OCR's own review on omp's model; hand its "
+              "comments to the reviewers as candidates to confirm or refute, "
+              "never as findings" % (shlex.quote(where), base))
+
 
 def verification_steps(text, path):
     """What the verification phase requires before the plan is done: the plan's
@@ -510,6 +688,7 @@ def verification_steps(text, path):
               "without a new round, or recorded fix-later under ## State only "
               "when it waits on a user decision (%s), and the verdict is "
               "`approve`" % say()["decision"])
+        print_ocr_spec(where, base)
     print("  3. record its verdict: `tezgah-task review %s <reviewer> approve|changes`"
           " (records the reviewed sha);"
           " `tezgah-task close %s done` refuses without an approve" % (ident, ident))
@@ -552,6 +731,11 @@ def cmd_start(args):
             if i + 1 >= len(rest) or rest[i + 1].startswith("--"):
                 return misuse("--branch needs the branch name to bind the plan to")
             branch = rest[i + 1]
+            if branch in PLAN_TRUNKS:
+                return misuse("--branch %s: a trunk (%s) never binds a plan - the gate "
+                              "reads every PLAN_TRUNKS name as unplanned; bind a "
+                              "plan/NNN-slug branch instead"
+                              % (branch, ", ".join(PLAN_TRUNKS)))
             i += 2
             continue
         if rest[i] == ANY_PATH:
@@ -619,7 +803,19 @@ def cmd_start(args):
     bad = write_fields(path, **fields)
     if bad:
         return problems(bad)
-    return show(path)
+    shown = show(path)
+    top = repo_root(os.getcwd())
+    if main_root(top) != top:
+        # a worktree bound to a plan gets its graph now, seeded from the main
+        # checkout's (plan 118); an index that cannot start costs the line, never
+        # the start the record already holds
+        try:
+            from tezgah_context import autoindex, under
+            if under(top):
+                print("graph: %s" % autoindex(top))
+        except Exception:
+            pass
+    return shown
 
 
 def cmd_phase(args):
@@ -886,7 +1082,7 @@ def budget_spent(path, ident):
             % (path, REVIEW_ROUNDS, ident, say()["decision"], ident))
 
 
-def unfinished_review(root, reviewer, plan="", since=0):
+def unfinished_review(root, reviewer, plan="", since=0, no_slice="", ran_since=0):
     """The refusal of an `approve` while a slice journal record whose id or agent
     is `reviewer` is open, stopped or stale: a review slice that died on a
     provider limit had its approve recorded anyway, and a NameError it would have
@@ -901,7 +1097,11 @@ def unfinished_review(root, reviewer, plan="", since=0):
     `tt.open_slice`) counts too. Under TEZGAH_SESSION only this session's
     records and unowned ones count, by id, agent or name alike: another
     session's review is not this approve's. The refusal names the exact id,
-    which `slice resume` and `slice done` take from any session."""
+    which `slice resume` and `slice done` take from any session. No finished
+    record changed at or after `ran_since` refuses too: a requested reviewer with
+    no status did not run, and a plan-readiness review before the checkpoint, an
+    earlier round's review or a `resumed` record with no re-run is not this
+    review - unless `no_slice` says why the reviewer ran outside the journal."""
     from tezgah_paths import off
     if off("slices-off"):
         return []
@@ -917,21 +1117,42 @@ def unfinished_review(root, reviewer, plan="", since=0):
             return rec["plan"] == plan
         return (_stamp(rec.get("updated")) or 0) >= since
 
-    return ["review slice %s is %s%s: let it finish, or resume it with `tezgah-task "
-            "slice resume %s` and wait for that run; if the review was finished "
-            "another way, record it with `tezgah-task slice done %s` - an approve "
-            "from a review that did not finish reads nothing"
-            % (rec["id"], rec.get("status"),
-               (" (%s)" % rec["failure"]) if rec.get("failure") else "",
-               rec["id"], rec["id"])
-            for rec in tt.slices(root)
-            if rec.get("status") in ("open", "stopped", "stale")
-            and named(rec) and ours(rec)]
+    found = [rec for rec in tt.slices(root) if named(rec) and ours(rec)]
+    refusals = ["review slice %s is %s%s: let it finish, or resume it with `tezgah-task "
+                "slice resume %s` and wait for that run; if the review was finished "
+                "another way, record it with `tezgah-task slice done %s` - an approve "
+                "from a review that did not finish reads nothing"
+                % (rec["id"], rec.get("status"),
+                   (" (%s)" % rec["failure"]) if rec.get("failure") else "",
+                   rec["id"], rec["id"])
+                for rec in found if rec.get("status") in ("open", "stopped", "stale")]
+    ran = [rec for rec in found if rec.get("status") == "done"
+           and (_stamp(rec.get("updated")) or 0) >= ran_since]
+    if not ran and not refusals and not no_slice:
+        # a requested reviewer with no finished record since the work is a
+        # review that did not run
+        refusals.append(
+            "no finished review slice names %s for this plan since its work began: "
+            "a reviewer with no record did not run, and a readiness review, an "
+            "earlier round or a resumed record is not this review. Spawn the fresh "
+            "reviewer and approve once its slice is done; a host that keeps no "
+            "slice journal records why with "
+            "`--no-slice \"<why: the reviewer ran outside the slice journal>\"`"
+            % reviewer)
+    return refusals
 
 
 def cmd_review(args):
+    no_slice = ""
+    if "--no-slice" in args:
+        i = args.index("--no-slice")
+        no_slice = " ".join((args[i + 1:i + 2] or [""])[0].split())
+        args = args[:i] + args[i + 2:]
+        if not no_slice:
+            return misuse("--no-slice takes why the reviewer ran outside the slice journal")
     if len(args) != 3 or args[2] not in VERDICTS:
-        return misuse("review takes <NNN|path> <reviewer> %s" % "|".join(VERDICTS))
+        return misuse("review takes <NNN|path> <reviewer> %s [--no-slice WHY]"
+                      % "|".join(VERDICTS))
     path, problem = open_plan(args[0])
     if problem:
         return problems([problem])
@@ -948,9 +1169,21 @@ def cmd_review(args):
         mark = (fields.get("checkpoint") or "").split()
         since = (git_out(root, "log", "-1", "--format=%ct", mark[-1])
                  if mark and mark[-1] != tt.CHECKPOINT_PENDING else None)
+        since = int(since) if (since or "").isdigit() else 0
+        # this round's review finished after the first commit of the work it
+        # reads: past the checkpoint in round one (a plan-readiness review ran
+        # before it), past the commit round one read in round two (round one's
+        # reviewer finished before it); with no such commit, after the base itself
         ident = fields.get("id") or os.path.basename(path).split("-")[0]
-        bad = unfinished_review(root, args[1], ident,
-                                int(since) if (since or "").isdigit() else 0)
+        base = fields.get("reviewed_sha") or (
+            mark[-1] if mark and mark[-1] != tt.CHECKPOINT_PENDING else "")
+        first = ""
+        if base:
+            after = (git_out(tt.plan_holders(root).get(ident) or root, "log",
+                             "--reverse", "--format=%ct", base + "..HEAD") or "").split()
+            first = after[0] if after else git_out(root, "log", "-1", "--format=%ct", base)
+        ran_since = max(since, int(first) if (first or "").isdigit() else 0)
+        bad = unfinished_review(root, args[1], ident, since, no_slice, ran_since)
         if bad:
             return problems(bad)
     # a plan held by its own worktree is built on that branch: its HEAD is the
@@ -958,7 +1191,8 @@ def cmd_review(args):
     ident = fields.get("id") or os.path.basename(path).split("-")[0]
     where = tt.plan_holders(root).get(ident) or root
     sha = (git_out(where, "rev-parse", "HEAD") or "")[:12]
-    record = {"review": "%s %s %s" % (args[1], args[2], today()),
+    record = {"review": "%s %s %s%s" % (args[1], args[2], today(),
+                                        " no-slice: " + no_slice if no_slice else ""),
               "review_round": str(int(prior) + 1 if prior.isdigit() else 1),
               "updated": today()}
     if sha:
@@ -1814,6 +2048,10 @@ def main(argv):
         print(__doc__, file=sys.stderr)
         return 2
     cmd, rest = argv[1], argv[2:]
+    if writes_a_record(cmd, rest):
+        mark = owner_mark(repo_root(os.getcwd()))
+        if mark:
+            return problems([mark])
     if cmd == "start":
         return cmd_start(rest)
     if cmd == "phase":

package/commands/adhd.md

@@ -1,4 +1,4 @@
-Run `tezgah-adhd $ARGUMENTS` and report the one line it prints.
+Run `~/.config/tezgah/bin/tezgah-adhd $ARGUMENTS` and report the one line it prints.
 
 The installed CLI owns the state: it writes or removes
 `~/.config/tezgah/adhd-off`, the kill switch that drops the act-on-it rule from
@@ -6,7 +6,7 @@ the text every host injects. Never create or delete that file by hand, and never
 edit any other rule's switch from here.
 
 ```sh
-adhd=$(command -v tezgah-adhd || echo "$HOME/.config/tezgah/bin/tezgah-adhd")
+adhd="$HOME/.config/tezgah/bin/tezgah-adhd"
 "$adhd" $ARGUMENTS
 ```