@r1z4x/tezgah 1.9.2 → 1.11.0

package/bin/tezgah-research

@@ -2,13 +2,15 @@
 """tezgah-research - the research workspace CLI.
 
   tezgah-research init <slug> --ask "<the user's words>" [--question "..."]
-                       [--method qualitative|measured|exploratory] [--in "<covered>"]...
-                       [--out "<left alone>"]... [--allow-open "<why>"] [--supersedes <slug>]
+                       [--method qualitative|measured|exploratory] [--class R1..R12]
+                       [--in "<covered>"]... [--out "<left alone>"]... [--allow-open "<why>"]
+                       [--supersedes <slug>]
                        [--arena "<problem>" --budget "<budget>" [--evaluator <path> --metric "<m>"]]
                                                    scaffold a line
   tezgah-research commit <slug> "<message>"       commit the line in .tezgah's own repo
-  tezgah-research check [<slug>] [--json] [--strict] [--orx] [--all-lines] [-- <slug>]
-                                                   the discipline checks
+                                                   (the project's, when it tracks .tezgah)
+  tezgah-research check [<slug>] [--json] [--strict] [--orx] [--online] [--all-lines]
+                        [-- <slug>]                the discipline checks
   tezgah-research status                           one line per research line
   tezgah-research --all                            every checkout's lines (git worktrees)
   tezgah-research claim <slug>                     record one claim from stdin
@@ -16,7 +18,9 @@
   tezgah-research components [--json]              what predicts what, per component
   tezgah-research migrate <slug> [--dry-run]       derive fields the rules require
   tezgah-research source <slug> <hypothesis> --run <orxRunId> [--command "<cmd>"]
+                           [--instrument <name>] [--arm <a>] [--item <i>] [--value <field>=<number>]...
                            [--scope real|fixture|derived] [--fixture "<what was generated>"]
+                           [--ack "<the user's words>"]
   tezgah-research compare <slug> <decision>        record one variants x criteria cell from stdin
   tezgah-research verdict <slug> <id> met|not-met|unanswerable --evidence "<ref>"
                                                    record one success criterion's verdict
@@ -37,6 +41,23 @@
   tezgah-research dedup <slug> [--threshold <(0,1]>] [--json]
                                                    cluster the proposed ideas, write nothing
   tezgah-research yield [--json] [--all-lines]     how far ideas got, per operator and family
+  tezgah-research cite <slug>                      query four registries for each formal INDEX id
+  tezgah-research fetch <slug> <note> [--file <path> --ack "<the user's words>" | --orx]
+                                                   capture a note's source text and its quotes
+  tezgah-research search <slug> --tag primary|snowball|counter|known [--item "<scope.in item>"]
+                         -- <connector> <args...>  capture one search on an allowlisted connector
+  tezgah-research instrument add <slug> <name> --kind measure|verdict --rung R1|R2|R3|R4
+                         --construct "<text>"      register an instrument
+  tezgah-research gold <slug> <instrument> --arm <a> --n N --seed S
+                                                   draw an arm's seeded gold sample
+  tezgah-research label <slug> <instrument> --arm <a> (--human "<name>" --ack "<the user's words>"
+                        | --provider openrouter --model <m>)
+                                                   label an arm's gold sample
+  tezgah-research switch <slug> <instrument> (--to R1|R2|R3|R4|<method> | --narrow "<what the
+                         claims now say>") --reason "<why>"
+                                                   record a switch away from an instrument
+  tezgah-research release-check [--fixtures <dir>] score the known-truth cases, exit 1 past the bounds
+  tezgah-research calibration                      Brier score over resolved hypotheses
 
 A research line lives at <repo>/.tezgah/research/<slug>/ and holds the state an
 auditable investigation needs: the question, the decision log, the findings, the
@@ -47,7 +68,11 @@ and the review a concluded line reports. `check` exits 1 when a line breaks thos
 rules, so a hook or a person can act on it. The project ignores `.tezgah/`; the
 commits the order rule reads are made in `.tezgah`'s own private git repository,
 which `init` creates and `commit` writes to, and a line the project itself
-committed before the move keeps its order proof in the project's history.
+committed before the move keeps its order proof in the project's history. A
+folded `.tezgah` - one the project tracks, with no repository of its own - has
+only the project's history, so `commit` commits the line there, after the
+message passes the gate's own language and attribution readers (exit 2 and
+the gate's refusal when it does not, nothing committed).
 
 `check` with no slug reports the open lines in full; a line under `done/` is
 verified by its order seal's hashes alone and named only when they fail, with
@@ -116,7 +141,8 @@ append. `board`, `dedup` and `yield` are reports: they write nothing and exit 0.
 Exit codes: 0 clean, 1 problems found - a broken line for `check`, a refused
 claim for `claim`, a refused row for `predict`, `idea`, `stage` or `match`, which
 writes nothing and prints one reason per problem, or a new line refused for
-`init` over unfinished ones - 2 misuse.
+`init` over unfinished ones - 2 misuse, or a folded `commit` whose message the
+gate would refuse.
 """
 import json
 import os
@@ -158,9 +184,28 @@ def misuse(message):
     return 2
 
 
+INIT_USAGE = ('init <slug> --ask "<the user\'s words>" [--tier quick|study|program]'
+              ' [--method qualitative|measured|exploratory] [--class R1..R12]'
+              ' [--in "<covered>"]... [--out "<left alone>"]... [--question "..."]'
+              ' [--allow-open "<reason>"] [--supersedes <slug>]'
+              ' [--arena "<problem>" --budget "<budget>"'
+              ' [--evaluator <path> --metric "<metric>"]]')
+INIT_EXAMPLE = ('tezgah-research init cache-latency --ask "does the cache cut p95?" '
+                '--method measured --in "p95 of the read path" --out "write path"')
+
+
 def cmd_init(args):
+    # R0 is refused before any other argument is read (spec 3.3): a factual or
+    # reference question gets its answer in the reply, never a line
+    if any(a == "--class" and b == "R0" for a, b in zip(args, args[1:])):
+        print("FAIL init: R0 gets no line: a factual or reference question is answered "
+              "in the reply with its evidence")
+        return 1
     if not args:
         return misuse("init needs a slug")
+    if args[0] in ("-h", "--help"):
+        print("usage: tezgah-research %s\nexample: %s" % (INIT_USAGE, INIT_EXAMPLE))
+        return 0
     slug = args[0].strip().lower().replace(" ", "-")
     if not tr.valid_slug(slug):
         # A slug is the directory name the other commands list, so anything that
@@ -170,7 +215,7 @@ def cmd_init(args):
                       "and dashes" % args[0])
     question, allow, supersedes = "", None, None
     ask, tier, method, scope_in, scope_out = "", str(tr.DEFAULT_TIER), "", [], []
-    arena = {}
+    arena, question_class = {}, ""
     rest = args[1:]
     while rest:
         flag = rest.pop(0)
@@ -184,6 +229,9 @@ def cmd_init(args):
             method = rest.pop(0)
         elif flag == "--in" and rest:
             scope_in.append(rest.pop(0))
+        elif flag == "--class" and rest and rest[0] in tr.QUESTION_CLASSES[1:] \
+                and not question_class:
+            question_class = rest.pop(0)
         elif flag == "--out" and rest:
             scope_out.append(rest.pop(0))
         elif flag == "--allow-open" and rest:
@@ -194,12 +242,7 @@ def cmd_init(args):
                 and flag not in arena:
             arena[flag] = rest.pop(0)
         else:
-            return misuse('init <slug> --ask "<the user\'s words>" [--tier quick|study|program]'
-                          ' [--method qualitative|measured|exploratory] [--in "<covered>"]...'
-                          ' [--out "<left alone>"]... [--question "..."]'
-                          ' [--allow-open "<reason>"] [--supersedes <slug>]'
-                          ' [--arena "<problem>" --budget "<budget>"'
-                          ' [--evaluator <path> --metric "<metric>"]]')
+            return misuse(INIT_USAGE)
     if method == "exploratory":
         # The arena is the lock an exploratory line commits before its first idea,
         # so a line without one is a call that cannot work, not a line to repair.
@@ -222,6 +265,9 @@ def cmd_init(args):
     if problems:
         for problem in problems:
             print("FAIL init: %s" % problem)
+        if not ask.strip():
+            print("usage: tezgah-research %s\nexample: %s" % (INIT_USAGE, INIT_EXAMPLE),
+                  file=sys.stderr)
         return 1
     if allow is not None and not allow.strip():
         return misuse("--allow-open needs the reason the new line is worth opening "
@@ -267,7 +313,8 @@ def cmd_init(args):
                                  arena.get("--metric", "").strip())
     made = tr.init(repo, slug, question=question, created=created,
                    supersedes=supersedes, ask=ask, tier=tier, method=method,
-                   scope_in=scope_in, scope_out=scope_out, arena=record)
+                   scope_in=scope_in, scope_out=scope_out, arena=record,
+                   question_class=question_class)
     if allow is not None:
         problem = tr.note_open(repo, slug, allow, created)
         if problem:
@@ -278,12 +325,17 @@ def cmd_init(args):
         print("  wrote %s" % path)
     for problem in tr.scope_problems(tr.line_state(repo, slug)):
         print("  owed: %s" % problem)
+    if question_class:
+        print("obligations: %s" % ", ".join(tr.obligations(question_class, method)))
+        print(tr.budget(slug, tr.line_dir(repo, slug), tr.line_state(repo, slug))[0])
+        for line, cid, status, sim in tr.overlaps(repo, question or ask, slug):
+            print("overlap: %s/%s %s %.2f" % (line, cid, status, sim))
     if method == "exploratory":
-        print("\nnext: commit the arena now, before any idea - `tezgah-research commit "
+        print("\nnext: commit the arena now, before any idea - `~/.config/tezgah/bin/tezgah-research commit "
               "%s \"arena\"`; an idea committed with it or before it is refused. Then "
-              "record ideas (`tezgah-research idea %s`, one JSON row on stdin, each "
+              "record ideas (`~/.config/tezgah/bin/tezgah-research idea %s`, one JSON row on stdin, each "
               "naming its operator, generator and kill result), commit them, and "
-              "follow `tezgah-research board %s`: dedup, prior art, matches, pilots, a "
+              "follow `~/.config/tezgah/bin/tezgah-research board %s`: dedup, prior art, matches, pilots, a "
               "full run, a confirmation on unseen data." % (slug, slug, slug))
     elif method == "qualitative":
         print("\nnext: read the primary sources for each state.json scope.in item "
@@ -293,7 +345,7 @@ def cmd_init(args):
     else:
         print("\nnext: write experiments/<hypothesis>/protocol.md - what the change "
               "is, what it predicts, what result would falsify it, why - and COMMIT "
-              "it before the run: `tezgah-research commit %s \"protocol "
+              "it before the run: `~/.config/tezgah/bin/tezgah-research commit %s \"protocol "
               "<hypothesis>\"`. Then record the run in results.jsonl and commit it "
               "the same way, in a later commit. The commits land in `.tezgah`'s own "
               "git repository (the project ignores `.tezgah/`). Then analyse it in "
@@ -304,8 +356,10 @@ def cmd_init(args):
 
 
 def cmd_commit(args):
-    """Commit one line in the private `.tezgah` repository - the commit the order
-    rule reads. Only the line's own path is staged and committed."""
+    """Commit one line in the private `.tezgah` repository, or in the project's
+    when `.tezgah` is folded - the commit the order rule reads. Only the line's
+    own paths are staged and committed: every layout location of the slug, so
+    the move `conclude` makes from `open/` to `done/` lands whole."""
     if len(args) != 2 or not args[1].strip():
         return misuse('commit <slug> "<message>"')
     slug, message = args
@@ -313,21 +367,41 @@ def cmd_commit(args):
     known = tr.slugs(repo)
     if slug not in known:
         return misuse("no such research line (have: %s)" % (", ".join(known) or "none"))
-    return commit_path(repo, tr.line_dir(repo, slug), message)
+    return commit_path(repo, [os.path.join(f, slug) for f in tr.layout_roots(repo)],
+                       message)
+
 
+def present(paths, base, ls_files):
+    """The paths relative to `base` that exist on disk or that git still
+    tracks: a pathspec matching nothing would make `git add` fail."""
+    rels = [os.path.relpath(p, base) for p in paths]
+    tracked = ls_files(*rels).splitlines() if rels else []
+    return [r for r, p in zip(rels, paths) if os.path.lexists(p) or any(
+        t == r or t.startswith(r + "/") for t in tracked)]
 
-def commit_path(repo, path, message):
-    """Stage and commit `path` alone in the private repository of `repo`."""
+
+def commit_path(repo, paths, message):
+    """Stage and commit `paths` alone in the private repository of `repo`, or in
+    the project's own when `.tezgah` is folded - tracked by the project, with no
+    repository of its own (`tr.folded`)."""
     ws = tp.ensure_workspace(repo)
+    if ws is None and tr.folded(repo):
+        return commit_project(repo, paths, message)
     if ws is None:
         print("commit refused: %s is not a git work tree (or .tezgah could not be "
               "set up), so there is no private repository to commit into" % repo)
         return 1
-    rel = os.path.relpath(path, ws)
     try:
-        done = tp.ws_git(repo, "add", "-A", "--", rel)
+        rels = present(paths, ws, lambda *r: tp.ws_git(repo, "ls-files", "--", *r).stdout)
+        done = tp.ws_git(repo, "add", "-A", "--", *rels)
+        if not done.returncode and not tp.ws_git(repo, "diff", "--cached", "--quiet",
+                                                 "--", *rels).returncode:
+            # a writer that commits its own capture (`source`, `cite`) leaves nothing
+            # for the session's commit, which is not a failure (plan 128 K10)
+            print("nothing to commit: %s is already committed in %s" % (" ".join(rels), ws))
+            return 0
         if not done.returncode:
-            done = tp.ws_git(repo, "commit", "-q", "-m", message, "--", rel)
+            done = tp.ws_git(repo, "commit", "-q", "-m", message, "--", *rels)
     except OSError as exc:
         print("commit failed: %s" % exc)
         return 1
@@ -335,7 +409,62 @@ def commit_path(repo, path, message):
         print("commit failed: %s" % (done.stderr or done.stdout).strip())
         return 1
     sha = tp.ws_git(repo, "rev-parse", "HEAD").stdout.strip()
-    print("committed %s in %s at %s" % (rel, ws, sha))
+    print("committed %s in %s at %s" % (" ".join(rels), ws, sha))
+    return 0
+
+
+def message_refusal(message):
+    """The refusal the gate prints for `message` as a `git commit -m` value, or
+    None. A folded `commit` writes the project's own history, which the gate
+    never sees through this command, so the message meets the gate's own
+    readers here: the language reader `lang_reason` hands each subject to
+    (`tezgah_lang.refusal`), then the credit forms `attribution` matches
+    (`ATTRIB`), under the same switches."""
+    if tp.off("pretooluse-off"):
+        return None
+    import tezgah_gate as gate  # deferred: only a folded commit pays the import
+    if gate.tezgah_lang is not None and not tp.off("lang-off"):
+        reason = gate.tezgah_lang.refusal("commit subject", message)
+        if reason:
+            return reason
+    return gate.ATTRIB_DENY if gate.ATTRIB.search(message) else None
+
+
+def commit_project(repo, paths, message):
+    """Stage and commit `paths` alone in the project's repository: the history a
+    folded `.tezgah` lives in. Anything else the owner staged stays staged and
+    out of this commit (`commit -- <paths>`); the project's identity, signing and
+    hooks apply, since this is the project's own history. A message the gate
+    would refuse is refused first, exit 2, and nothing is staged."""
+    refused = message_refusal(message)
+    if refused:
+        print("commit refused: %s" % refused, file=sys.stderr)
+        return 2
+    git = ["git", "-C", repo]
+    try:
+        rels = present(paths, repo, lambda *r: subprocess.run(
+            git + ["ls-files", "--"] + list(r), capture_output=True, text=True).stdout)
+        done = subprocess.run(git + ["add", "-A", "--"] + rels, capture_output=True,
+                              text=True)
+        if not done.returncode and not subprocess.run(
+                git + ["diff", "--cached", "--quiet", "--"] + rels).returncode:
+            print("nothing to commit: %s is already committed in the project repository %s"
+                  % (" ".join(rels), repo))
+            return 0
+        if not done.returncode:
+            done = subprocess.run(git + ["commit", "-q", "-m", message, "--"] + rels,
+                                  capture_output=True, text=True)
+    except OSError as exc:
+        print("commit failed: %s" % exc)
+        return 1
+    if done.returncode:
+        print("commit failed: %s" % (done.stderr or done.stdout).strip())
+        return 1
+    sha = subprocess.run(git + ["rev-parse", "HEAD"], capture_output=True,
+                         text=True).stdout.strip()
+    print("committed %s in the project repository %s at %s (.tezgah is tracked by "
+          "the project, so the project's history carries the line)"
+          % (" ".join(rels), repo, sha))
     return 0
 
 
@@ -346,13 +475,14 @@ def cmd_check(args):
     as_json = "--json" in flags
     strict = "--strict" in flags
     ask_orx = "--orx" in flags
+    online = "--online" in flags
     all_lines = "--all-lines" in flags
     rest = [a for a in flags
-            if a not in ("--json", "--strict", "--orx", "--all-lines")] + after
+            if a not in ("--json", "--strict", "--orx", "--online", "--all-lines")] + after
     repo = repo_root(os.getcwd())
     if len(rest) > 1:
-        return misuse("check [<slug>] [--json] [--strict] [--orx] [--all-lines] "
-                      "[-- <slug>]")
+        return misuse("check [<slug>] [--json] [--strict] [--orx] [--online] "
+                      "[--all-lines] [-- <slug>]")
     known = tr.slugs(repo)
     if rest and rest[0] not in known:
         print("FAIL %s: no such research line (have: %s)"
@@ -362,13 +492,18 @@ def cmd_check(args):
     report = {}
     if known:
         report = tr.check(repo, rest[0] if rest else None, strict=strict,
-                          all_lines=all_lines, code=checkout_root(os.getcwd()))
+                          all_lines=all_lines, code=checkout_root(os.getcwd()),
+                          flags={"online": online, "orx": ask_orx})
         for slug, row in report.items():
             for err in row["errors"]:
                 problems += 1
                 print("FAIL %s: %s" % (slug, err))
             for warn in row["warnings"]:
                 print("warn %s: %s" % (slug, warn))
+            # rules 8's report lines (certainty, stats, effect, budget, ...): never
+            # problems, and inside the JSON row rather than before it
+            for line in [] if as_json else row.get("report", []):
+                print(line)
     else:
         print("no research line under %s" % tr.root(repo))
     lines = len(report)
@@ -559,13 +694,21 @@ def cmd_migrate(args):
 
 def cmd_source(args):
     """File one orx run's log as the receipt of an experiment."""
-    usage = ('source <slug> <hypothesis> --run <orxRunId> [--command "<cmd>"] '
-             '[--scope real|fixture|derived] [--fixture "<what was generated>"]')
+    import re
+    import tezgah_research_capture as cap
+    reserved = ("source", "log", "run", "arm", "item", "instrument", "scope", "fixture",
+                "status", "command", "ack")
+    usage = ('source <slug> <hypothesis> --run <orxRunId> [--instrument <name>] [--arm <a>] '
+             '[--item <i>] [--value <field>=<number>]... [--command "<cmd>"] '
+             '[--scope real|fixture|derived] [--fixture "<what was generated>"] '
+             '[--ack "<the user\'s words>"]')
     if len(args) < 2:
         return misuse(usage)
     slug, hypothesis = args[0], args[1]
-    run = command = scope = ""
+    run = command = scope = arm = item = ack = ""
+    instrument = None
     fixture = None
+    values = []
     rest = args[2:]
     while rest:
         flag = rest.pop(0)
@@ -577,6 +720,22 @@ def cmd_source(args):
             scope = rest.pop(0)
         elif flag == "--fixture" and rest:
             fixture = rest.pop(0)
+        elif flag == "--instrument" and rest:
+            instrument = rest.pop(0)
+        elif flag == "--arm" and rest:
+            arm = rest.pop(0)
+        elif flag == "--item" and rest:
+            item = rest.pop(0)
+        elif flag == "--ack" and rest:
+            ack = rest.pop(0)
+        elif flag == "--value" and rest:
+            field, _eq, number = rest.pop(0).partition("=")
+            if field in reserved:
+                return misuse("--value %s: %s is a reserved row key" % (field, field))
+            if not re.fullmatch(r"[A-Za-z_][\w.-]*", field) or not re.fullmatch(
+                    cap.VALUE_NUMBER, number):
+                return misuse("--value needs <field>=<number>, not %r" % (field + _eq + number))
+            values.append((field, number))
         else:
             return misuse(usage)
     if "/" in hypothesis or "\\" in hypothesis or hypothesis.startswith("."):
@@ -588,6 +747,10 @@ def cmd_source(args):
         return misuse("--scope %r is not one of %s" % (scope, ", ".join(tr.SCOPES)))
     if fixture is not None and not fixture.strip():
         return misuse("--fixture needs the text naming what was generated")
+    if instrument is not None and not instrument.strip():
+        return misuse("--instrument needs the instrument's name")
+    if ack and not ack.strip():
+        return misuse('--ack needs "<the user\'s words>" for a log above the bound')
     repo = repo_root(os.getcwd())
     known = tr.slugs(repo)
     if slug not in known:
@@ -597,16 +760,15 @@ def cmd_source(args):
         return misuse("orx is not installed, so no run log can be read; nothing "
                       "was written (TEZGAH_ORX_BIN overrides the lookup)")
     path, problems = tr.source_run(repo, slug, hypothesis, run, orx, command, scope,
-                                   fixture or "")
+                                   fixture or "", arm, item, values, instrument or "", ack)
     if problems:
         for problem in problems:
             print("FAIL %s: %s" % (slug, problem))
         return 1
     print("receipt %s" % path)
-    print('row {"source": "orx:%s", "log": "raw/%s.log"%s%s%s}'
-          % (run, run, ', "command": %s' % json.dumps(command) if command else "",
-             ', "scope": %s' % json.dumps(scope) if scope else "",
-             ', "fixture": %s' % json.dumps(fixture) if fixture else ""))
+    rows = tr._row_objects(os.path.join(os.path.dirname(os.path.dirname(path)),
+                                        "results.jsonl"))
+    print("row %s" % json.dumps(rows[-1] if rows else {}))
     if not scope:
         print("note: the row declares no scope, so nothing says whether this run "
               "measured the running system or an input you generated; re-file with "
@@ -1062,9 +1224,23 @@ def main(argv):
                 "board": cmd_board, "dedup": cmd_dedup, "yield": cmd_yield}
     if cmd in campaign:
         return campaign[cmd](rest)
+    # rules 8's capture and evidence commands, imported only when asked for so a
+    # missing optional module never breaks another command. Each handler takes
+    # (repo, args), prints its own output and returns its exit code; `release-check`
+    # and `calibration` need no line and run from any directory.
+    import importlib
+    for name in ("tezgah_research_capture", "tezgah_research_evidence"):
+        try:
+            commands = importlib.import_module(name).COMMANDS
+        except (ImportError, AttributeError):
+            continue
+        if cmd in commands:
+            return commands[cmd](repo_root(os.getcwd()), rest)
     return misuse("unknown command %r (init, commit, check, status, --all, claim, predict, "
                   "components, migrate, source, compare, verdict, conclude, migrate-layout, "
-                  "close, seal, import, next, idea, stage, match, board, dedup, yield)" % cmd)
+                  "close, seal, import, next, idea, stage, match, board, dedup, yield, cite, "
+                  "fetch, search, instrument, gold, label, switch, release-check, "
+                  "calibration)" % cmd)
 
 
 if __name__ == "__main__":

package/bin/tezgah-review-quote

@@ -0,0 +1,185 @@
+#!/usr/bin/env python3
+"""tezgah-review-quote - place review findings on the diff by their quoted code.
+
+    tezgah-review-quote [--repo DIR] --from BASE [--to HEAD] FINDINGS_JSON
+
+FINDINGS_JSON is a file (or `-` for stdin) holding a JSON list of objects with
+at least `path` and `quote`. Prints that list with `status` added:
+`located` (the quote is in its own file), `relocated` (it is nowhere in its own
+file but exactly once in another changed file; `path` moves there) or
+`unlocated`; a placed finding gets `start_line`/`end_line`, plus `side: "old"`
+when the lines are pre-change. A quote found several times in its own file is
+placed on the match covering the finding's own `start_line`, else it is
+`unlocated` with `reason: "ambiguous: N matches"`.
+
+A Python port of the deterministic comment positioning in
+alibaba/open-code-review (internal/diff/resolver.go: ResolveComment,
+RelocateAcrossFiles; Apache-2.0): each line is trimmed, one leading `+` then
+`-` marker is stripped, blank quote lines are dropped, and the quote must match
+consecutive lines - the hunks' new side, then their old side, then the whole
+new file (where blank file lines are skipped too). Unlike OCR, which takes the
+first match, every match is collected so a repeated quote is never placed on
+the wrong copy; a cited line only chooses among the quote's matches.
+"""
+import argparse
+import json
+import subprocess
+import sys
+
+
+def norm(line):
+    return line.strip().removeprefix("+").removeprefix("-").strip()
+
+
+def quote_lines(text):
+    return [n for n in map(norm, text.split("\n")) if n]
+
+
+def git(repo, *args):
+    return subprocess.run(["git", "-C", repo, *args], capture_output=True,
+                          text=True, errors="replace")
+
+
+def strip_prefix(path):
+    # ponytail: C-quoted paths (tabs, quotes in names) are not unquoted
+    if path == "/dev/null":
+        return None
+    return path[2:] if path[:2] in ("a/", "b/") else path
+
+
+def parse_diff(text):
+    """One dict per changed file: old/new path and the hunks' two sides as
+    [(line_number, normalised_text, removed)] lists, one pair per hunk."""
+    files, cur, old_no, new_no = [], None, 0, 0
+    for line in text.split("\n"):
+        if line.startswith("diff --git "):
+            cur = {"old": None, "new": None, "hunks": []}
+            files.append(cur)
+        elif cur is None:
+            continue
+        elif line.startswith("--- ") and not cur["hunks"]:
+            cur["old"] = strip_prefix(line[4:].rstrip("\t"))
+        elif line.startswith("+++ ") and not cur["hunks"]:
+            cur["new"] = strip_prefix(line[4:].rstrip("\t"))
+        elif line.startswith("@@"):
+            spans = line.split("@@")[1].split()
+            old_no = int(spans[0][1:].split(",")[0])
+            new_no = int(spans[1][1:].split(",")[0])
+            cur["hunks"].append(([], []))
+        elif cur["hunks"] and not line.startswith("\\"):
+            new_side, old_side = cur["hunks"][-1]
+            mark, body = line[:1], norm(line[1:])
+            if mark in (" ", ""):
+                new_side.append((new_no, body, False))
+                old_side.append((old_no, body, False))
+                new_no += 1
+                old_no += 1
+            elif mark == "+":
+                new_side.append((new_no, body, False))
+                new_no += 1
+            elif mark == "-":
+                old_side.append((old_no, body, True))
+                old_no += 1
+    return files
+
+
+def matches(side, target):
+    """Every consecutive run of `target` in `side`: (start, end, run)."""
+    n = len(target)
+    return [(side[i][0], side[i + n - 1][0], side[i:i + n])
+            for i in range(len(side) - n + 1)
+            if all(side[i + j][1] == target[j] for j in range(n))]
+
+
+def resolve(f, target, content):
+    """Every distinct (start, end, side) of `target` in one changed file: the
+    hunks' new side, their old side, then the whole new file."""
+    hits = [(s, e, "new") for hunk in f["hunks"] for s, e, _ in matches(hunk[0], target)]
+    # an old-side run of context lines only repeats a new-side one
+    hits += [(s, e, "old") for hunk in f["hunks"]
+             for s, e, run in matches(hunk[1], target) if any(p[2] for p in run)]
+    if content is not None:
+        lines = [(i, norm(t.rstrip("\r")))
+                 for i, t in enumerate(content.split("\n"), 1)]
+        hits += [(s, e, "new") for s, e, _ in matches([p for p in lines if p[1]], target)]
+    return list(dict.fromkeys(hits))
+
+
+def cited(finding):
+    try:
+        return int(finding.get("start_line"))
+    except (TypeError, ValueError):
+        return None
+
+
+def place(finding, f, hit):
+    out = dict(finding, path=f["new"] or f["old"],
+               start_line=hit[0], end_line=hit[1])
+    out.pop("side", None)
+    if hit[2] == "old":
+        out["side"] = "old"
+    return out
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(prog="tezgah-review-quote")
+    ap.add_argument("--repo", default=".")
+    ap.add_argument("--from", dest="base", required=True)
+    ap.add_argument("--to", default="HEAD")
+    ap.add_argument("findings")
+    a = ap.parse_args(argv)
+    try:
+        src = sys.stdin if a.findings == "-" else open(a.findings, encoding="utf-8")
+        with src:
+            findings = json.load(src)
+        if not isinstance(findings, list) or not all(
+                isinstance(x, dict) and "path" in x and "quote" in x for x in findings):
+            raise ValueError("expected a JSON list of objects with path and quote")
+    except (OSError, ValueError) as e:
+        print(f"tezgah-review-quote: {a.findings}: {e}", file=sys.stderr)
+        return 2
+    diff = git(a.repo, "diff", "--no-ext-diff", "--no-textconv", "--no-color",
+               "--src-prefix=a/", "--dst-prefix=b/", "-U3", a.base, a.to)
+    if diff.returncode != 0:
+        print(f"tezgah-review-quote: git diff: {diff.stderr.strip()}", file=sys.stderr)
+        return 2
+    files, contents = parse_diff(diff.stdout), {}
+
+    def content(f):
+        if f["new"] and f["new"] not in contents:
+            r = git(a.repo, "show", f"{a.to}:{f['new']}")
+            contents[f["new"]] = r.stdout if r.returncode == 0 else None
+        return contents.get(f["new"])
+
+    out = []
+    for finding in findings:
+        target = quote_lines(str(finding["quote"] or ""))
+        own = [f for f in files if finding["path"] in (f["new"], f["old"])]
+        mine = resolve(own[0], target, content(own[0])) if target and own else []
+        line = cited(finding)
+        covering = [h for h in mine if line is not None and h[0] <= line <= h[1]]
+        # OCR's order: the new side wins over the old one, so a whitespace-only
+        # change matching on both sides is one new-side hit, not an ambiguity
+        new = [h for h in mine if h[2] == "new"]
+        pick = covering or (new if len(new) == 1 else []) or (mine if len(mine) == 1 else [])
+        if pick:
+            out.append(dict(place(finding, own[0], pick[0]), status="located"))
+            continue
+        if mine:
+            out.append(dict(finding, status="unlocated",
+                            reason=f"ambiguous: {len(new) or len(mine)} matches"))
+            continue
+        hits = [] if not target else [
+            (f, h) for f in files if f not in own
+            for h in resolve(f, target, content(f))]
+        if len(hits) == 1:
+            out.append(dict(place(finding, *hits[0]), status="relocated"))
+        else:
+            out.append(dict(finding, status="unlocated"))
+    json.dump(out, sys.stdout, indent=2)
+    sys.stdout.write("\n")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())