@r1z4x/tezgah 1.11.0 → 1.14.0

package/bin/tezgah-docs

@@ -99,22 +99,48 @@ def matches(query):
 # captured output) is data, not a citation, and is not read.
 
 CODE_FILES = ("hooks/*.py", "bin/*", "statusline.py", "hosts/*/*.py",
-              "hosts/*/*.ts.in", "hosts/*/plugins/*.js", "tests/*.py")
+              "hosts/*/*.ts.in", "hosts/*/plugins/*.js", "hosts/*/tui/*.tsx",
+              "hosts/*/statusline/lib/*.js", "tests/*.py")
 STRING = re.compile(r'"""(?:.|\n)*?"""|\'\'\'(?:.|\n)*?\'\'\'')
 TOP = re.compile(r"^(?:def|class)\s+(\w+)|^([A-Za-z_][A-Za-z0-9_]*)\s*(?::[^=]+)?=")
+# A JS/TS file's top-level `const`/`let`/`function`/`class`, exported or not.
+JS_FILES = (".js", ".mjs", ".ts", ".tsx", ".ts.in")
+JS_TOP = re.compile(r"^(?:export\s+(?:default\s+)?)?(?:async\s+)?"
+                    r"(?:function\*?|const|let|class)\s+([A-Za-z_$][\w$]*)")
 RUN = re.compile(r"((?:`[A-Za-z_][A-Za-z0-9_]*(?:\(\))?`\s*[/,]?\s*){1,5})$")
-CITE = re.compile(r"`([\w.-]+(?:/[\w.-]+)+|[\w-]+\.\w+):(\d+)(?:-(\d+))?`"
-                  r"|`(:(\d+)(?:-(\d+))?)`")
+# A cited path: one with a `/`, a `name.ext`, or a dot file (`.gitignore`); its
+# lines a range or a comma list of them (x.py:12,40-41). The path is optional:
+# a backticked colon and lines alone is a bare range of the path before it.
+PATH = r"[\w.-]+(?:/[\w.-]+)+|\.?[\w-]+\.\w+|\.[\w-]+"
+SPEC = r"\d+(?:-\d+)?(?:,\d+(?:-\d+)?)*"
+CITE = re.compile(r"`(%s)?:(%s)`" % (PATH, SPEC))
+SCRIPTS = (".sh", ".ps1", ".py", ".js", ".mjs", ".ts", ".tsx", ".in")
 # The symbol written after the citation instead of before it, the way a table
-# cell reads: `hooks/tezgah_policy.py:806-1135` (`CORE`).
+# cell reads: `hooks/tezgah_policy.py:819-1158` (`CORE`).
 AFTER = re.compile(r"\s*\(`([A-Za-z_][A-Za-z0-9_]*)(?:\(\))?`\)")
 # Any `path:line`, backticked or not: what CITE does not match of these (a
-# bare token, a comma list `x.py:12,40`) is counted as unjudged, so a citation
+# bare token such as x.py:12) is counted as unjudged, so a citation
 # written in a shape the audit cannot read is still a number someone sees.
 # Scanned as one token run and then shape-checked: the shape alternation as
 # the scanner (nested `+` under a look-behind) cost a third of a second a pass.
 LOOSE = re.compile(r"(?<![\w./:-])([\w./-]*\w):(\d+)(?:-(\d+))?(?!\w)")
 LOOSE_SHAPE = re.compile(r"(?:[\w.-]+/)+[\w.-]*\w|[\w-]+\.\w+")
+# A path a bare range can follow: backticked, with or without its line or
+# symbol (a loose `path:line` counts too). The bare ranges themselves:
+# `(8-9)` or `(14,34-38)` - a lone `(300)` is a value, not a line - and an
+# unquoted :8-9; the backticked one is CITE's second half. Each one is read
+# against the path before it in the same sentence or table row, never further.
+MARK = re.compile(r"`(%s)(?::%s|::[\w.]+)?`" % (PATH, SPEC))
+BARE = re.compile(r"(?<![\w(])\((\d+-\d+|\d+(?:-\d+)?(?:,\d+(?:-\d+)?)+)\)"
+                  r"|(?<=[\s(,]):(\d+(?:-\d+)?)(?![\w:-])")
+# A comment source masks its code as NUL: the code between two comments ends
+# the sentence too.
+SENTENCE_END = re.compile(r"[.!?](?:\s|$)|\n\s*\n|\n\s*[|*-]|\0")
+
+
+def spec_parts(spec):
+    """[(lo, hi)] of a SPEC such as `12,40-41`."""
+    return [(int(a), int(b or a)) for a, _, b in (p.partition("-") for p in spec.split(","))]
 
 
 def loose(text):
@@ -179,12 +205,17 @@ def anchor_span(names, qual):
 
 
 CITATION_BASELINE = os.path.join("docs", "citations-baseline.json")
+# The gitignored, private workspace: a CI checkout or a worktree has no copy, so
+# a citation into it is unjudged in every checkout, never judged in one alone.
+# ponytail: one fixed prefix, not a .gitignore reader; add another if one lands.
+PRIVATE = (".tezgah/",)
 
 
 def code_symbols(path):
     """{name: [(start, end)]} for this file's top-level defs, classes and
-    assignments. A triple-quoted body is masked first, so a line inside a
-    contract string cannot read as a definition and cut another one short."""
+    assignments (a JS/TS file's `JS_TOP` declarations). A triple-quoted body is
+    masked first, so a line inside a contract string cannot read as a
+    definition and cut another one short."""
     text = open(path, encoding="utf-8", errors="replace").read()
     chars = list(text)
     for m in STRING.finditer(text):
@@ -192,8 +223,9 @@ def code_symbols(path):
             if chars[i] != "\n":
                 chars[i] = " "
     lines = "".join(chars).splitlines()
-    starts = [(i, m.group(1) or m.group(2))
-              for i, line in enumerate(lines, 1) if (m := TOP.match(line))]
+    top = JS_TOP if path.endswith(JS_FILES) else TOP
+    starts = [(i, m.group(1) or m.group(top.groups))
+              for i, line in enumerate(lines, 1) if (m := top.match(line))]
     out = {}
     for k, (start, name) in enumerate(starts):
         end = starts[k + 1][0] - 1 if k + 1 < len(starts) else len(lines)
@@ -264,6 +296,11 @@ def comment_text(path):
     lead = (tokenize.NEWLINE, tokenize.INDENT, tokenize.DEDENT, tokenize.ENCODING)
     real = [t for t in tokens if t.type not in (tokenize.NL, tokenize.COMMENT)]
     kept = [span(t, 1) for t in tokens if t.type == tokenize.COMMENT]
+    # a comment's `#` is a space, not code: two comment lines stay one sentence
+    chars = list(masked)
+    for lo, _ in kept:
+        chars[lo - 1] = " "
+    masked = "".join(chars)
     kept += [span(t) for k, t in enumerate(real)
              if t.type == tokenize.STRING and (k == 0 or real[k - 1].type in lead)
              and k + 1 < len(real)
@@ -298,58 +335,134 @@ def citations(known):
     `note_tool` in `hooks/x.py`, so a same-named symbol elsewhere is not the
     thing being cited and the row is left unjudged rather than misjudged. A bare
     file name (`tezgah_gate.py:12`) is that path when exactly one code file has
-    the name, and unjudged otherwise. A symbol anchor (`SYMCITE`) is always
-    judged: against the qualnames() of the file it names."""
-    names = {}
-    for rel in code_files():
+    the name, else the repository-root file of that name, and unjudged
+    otherwise; a path under `PRIVATE` is unjudged in every checkout. A bare
+    range (`BARE`, or CITE's second
+    half) takes the path written before it in the same sentence (`MARK`); with
+    none, a backticked one is judged against the one code file defining its
+    symbol. A range past the end of its file, or over blank lines only, is
+    flagged as (`file:line`, token, why, -1, -1) whether or not it names a
+    symbol; a bare range naming none is otherwise left alone, a backticked one
+    counted unjudged as before. A symbol anchor (`SYMCITE`) is always judged:
+    against the qualnames() of the file it names, a JS/TS file's
+    code_symbols()."""
+    names, code, local, lines_of = {}, set(code_files()), {}, {}
+    for rel in code:
         names.setdefault(os.path.basename(rel), []).append(rel)
 
     def resolve(path):
+        if path.startswith(PRIVATE):
+            return None
         if "/" in path:
             return path
         found = names.get(path, ())
-        return found[0] if len(found) == 1 else None
+        if found:
+            return found[0] if len(found) == 1 else None
+        return path if os.path.isfile(os.path.join(HERE, path)) else None
+
+    def named_at(text, start, end):
+        # RUN is anchored at the end and five names fit in far fewer than
+        # 600 characters: slicing the whole page per citation was the cost.
+        pre = text[max(0, start - 600):start].rstrip().rstrip("(") \
+            .rstrip().rstrip(",").rstrip()
+        run = RUN.search(pre) if pre.endswith("`") else None
+        if run:
+            return re.findall(r"`([A-Za-z_][A-Za-z0-9_]*)(?:\(\))?`", run.group(1))
+        after = AFTER.match(text, end)
+        return [after.group(1)] if after else []
+
+    def path_before(text, marks, start):
+        k = bisect.bisect_right(marks, (start,)) - 1
+        while k >= 0 and marks[k][1] > start:
+            k -= 1
+        if k < 0 or SENTENCE_END.search(text, marks[k][1], start):
+            return None
+        return marks[k][2]
+
+    def judge(rel, text, m, path, parts, count):
+        """Judge one citation `m` of `parts` [(lo, hi)] into `path` (None: the
+        known symbol's file); `count` it as unjudged when it names no symbol."""
+        nonlocal judged
+
+        def line():
+            return "%s:%d" % (rel, text.count("\n", 0, m.start()) + 1)
+        full = os.path.join(HERE, path) if path else None
+        if full and os.path.isfile(full):
+            if path not in lines_of:
+                with open(full, encoding="utf-8", errors="replace") as fh:
+                    lines_of[path] = fh.read().splitlines()
+            body = lines_of[path]
+            if any(lo < 1 or hi > len(body) for lo, hi in parts):
+                if not count and max(hi for _, hi in parts) > 10 * len(body):
+                    return  # a bare value span such as a year range, not lines
+                flagged.append((line(), m.group(0), "%s has %d lines" % (path, len(body)),
+                                -1, -1))
+                return
+            if not any(body[i].strip() for lo, hi in parts for i in range(lo - 1, hi)):
+                flagged.append((line(), m.group(0), "%s is blank there" % path, -1, -1))
+                return
+            if path not in code:
+                # A file with no symbol table: its range is judged, and in a
+                # script (packaging/build.sh) a name written beside it must be
+                # on those lines; a data or prose file is read for its range.
+                judged += 1
+                said = named_at(text, m.start(), m.end()) if path.endswith(SCRIPTS) else []
+                cut = "\n".join(s for lo, hi in parts for s in body[lo - 1:hi])
+                if said and not any(re.search(r"\b%s\b" % re.escape(n), cut) for n in said):
+                    flagged.append((line(), m.group(0), "`%s` is not on %s there"
+                                    % ("`, `".join(said), path), -1, -1))
+                return
+        spans, where = [], path
+        for name in named_at(text, m.start(), m.end()):
+            if path:
+                if path not in local:
+                    local[path] = code_symbols(full) if path in code else {}
+                spans += local[path].get(name, [])
+            elif name in known:
+                where, spans = known[name][0], spans + known[name][1]
+        if not spans:
+            if count:
+                unjudged[rel] = unjudged.get(rel, 0) + 1
+            return
+        low, high = min(s for s, _ in spans), max(e for _, e in spans)
+        judged += 1
+        if any(lo < low or hi > high for lo, hi in parts):
+            flagged.append((line(), m.group(0), where, low, high))
 
     flagged, judged, unjudged, invisible, tables = [], 0, {}, 0, {}
     for rel, text in sources():
+        marks = [(p.start(), p.end(), resolve(p.group(1)))
+                 for p in list(MARK.finditer(text)) + list(loose(text))]
+        marks = sorted(mk for mk in marks
+                       if mk[2] and os.path.isfile(os.path.join(HERE, mk[2])))
         read = []
         for m in CITE.finditer(text):
             read.append(m.span())
-            # RUN is anchored at the end and five names fit in far fewer than
-            # 600 characters: slicing the whole page per citation was the cost.
-            pre = text[max(0, m.start() - 600):m.start()].rstrip().rstrip("(") \
-                .rstrip().rstrip(",")
-            run = RUN.search(pre.rstrip()) if pre.rstrip().endswith("`") else None
-            named = re.findall(r"`([A-Za-z_][A-Za-z0-9_]*)(?:\(\))?`",
-                               run.group(1)) if run else []
-            after = AFTER.match(text, m.end())
-            if not named and after:
-                named = [after.group(1)]
-            cited = resolve(m.group(1)) if m.group(1) else None
-            spans, where = [], None
-            for name in named:
-                hit = known.get(name)
-                if not hit or (m.group(1) and hit[0] != cited):
+            parts = spec_parts(m.group(2))
+            if m.group(1):
+                path = resolve(m.group(1))
+                if path is None:
+                    unjudged[rel] = unjudged.get(rel, 0) + 1
                     continue
-                where, spans = hit[0], spans + hit[1]
-            if not spans:
-                unjudged[rel] = unjudged.get(rel, 0) + 1
-                continue
-            lo = int(m.group(2) or m.group(5))
-            hi = int(m.group(3) or m.group(6) or lo)
-            low, high = min(s for s, _ in spans), max(e for _, e in spans)
-            judged += 1
-            if lo >= low and hi <= high:
-                continue
-            line = text.count("\n", 0, m.start()) + 1
-            flagged.append(("%s:%d" % (rel, line), m.group(0), where, low, high))
+            else:
+                path = path_before(text, marks, m.start())
+            judge(rel, text, m, path, parts, True)
+        for m in BARE.finditer(text):
+            path = path_before(text, marks, m.start())
+            if path:
+                parts = spec_parts(m.group(1) or m.group(2))
+                if any(lo < 1 or lo > hi for lo, hi in parts):
+                    continue  # a value range such as 0-100, not lines
+                judge(rel, text, m, path, parts, False)
         for m in SYMCITE.finditer(text):
             judged += 1
             path = resolve(m.group(1))
             full = os.path.join(HERE, path) if path else None
             if full and os.path.isfile(full):
                 if path not in tables:
-                    tables[path] = qualnames(full) or {}
+                    tables[path] = {n: (s[0][0], s[-1][1], False) for n, s in
+                                    code_symbols(full).items()} \
+                        if path.endswith(JS_FILES) else qualnames(full) or {}
                 if anchor_span(tables[path], m.group(2)):
                     continue
             line = text.count("\n", 0, m.start()) + 1
@@ -1136,6 +1249,9 @@ def main(argv):
     if "--citations" in flags:
         flagged, judged, unjudged, invisible = citations(symbols())
         for where, token, symbol_in, low, high in flagged:
+            if low < 0:
+                print("%s  %s -> %s" % (where, token, symbol_in))
+                continue
             if not low:
                 print("%s  %s -> %s defines no such symbol" % (where, token, symbol_in))
                 continue

package/bin/tezgah-dsh

@@ -16,7 +16,7 @@
 set -eu
 DSH_HOME="${DSH_HOME:-$HOME/.dsh}"
 BIN="$DSH_HOME/profiles/node_modules/@deepseek-ai/dsh/lib/bin.js"
-INDEX="${TEZGAH_INDEX_BIN:-$HOME/.config/tezgah/bin/tezgah-index}"
+INDEX="${TEZGAH_INDEX_BIN:-${XDG_CONFIG_HOME:-$HOME/.config}/tezgah/bin/tezgah-index}"
 warm_index() {
     if [ -x "$INDEX" ]; then
         "$INDEX" "$PWD" >/dev/null 2>&1 || true

package/bin/tezgah-gate

@@ -10,7 +10,8 @@
                        `--sheet` draws the blind label sample (hooks/tezgah_replay.py)
 
 Reads the host's own call as {"tool":..., "input":{...}, "cwd":...,
-"session_id":...} and prints what hooks/tezgah_gate.decision() returns for it,
+"session_id":..., "parent":...} (`parent`: the session that spawned this one,
+as the host named it) and prints what hooks/tezgah_gate.decision() returns for it,
 or nothing when the call passes. A host whose plugin is written in another
 language (opencode's tezgah.js) asks `decide` instead of mirroring a rule: that
 mirror is documented as incomplete and divergent, so a new rule reaches such a
@@ -49,6 +50,9 @@ def main(argv):
     if len(argv) < 2:
         print(__doc__, file=sys.stderr)
         return 2
+    if argv[1] in ("-h", "--help"):
+        print(__doc__.strip())
+        return 0
     if argv[1] == "replay":
         import tezgah_replay
         return tezgah_replay.main(argv[2:])
@@ -65,7 +69,8 @@ def main(argv):
     inp = payload.get("input")
     reason = decision(payload.get("tool"), inp if isinstance(inp, dict) else {},
                       payload.get("cwd") or os.getcwd(),
-                      payload.get("session_id"), record=argv[1] == "decide")
+                      payload.get("session_id"), record=argv[1] == "decide",
+                      parent=payload.get("parent"))
     if reason:
         sys.stdout.write(reason if reason.endswith("\n") else reason + "\n")
     return 0

package/bin/tezgah-import-ai-research

@@ -23,6 +23,8 @@ the point of keeping it.
 
 `skills/ai-research/SKILL.md` is hand-written and is not in the manifest: it is
 the entry point, not vendored content. `library.json` is the manifest itself.
+`LICENSE` is upstream's root licence, copied verbatim at the vendored revision
+and, like SOURCE, outside the manifest.
 
 Exit codes: 0 ok, 1 drift or an upstream surprise, 2 misuse.
 """
@@ -358,6 +360,14 @@ def cmd_import(source, rev, out):
     texts = dict(files)
     texts.update(generated)
     texts["SOURCE"] = source_text(manifest, rev)
+    # upstream's licence, bytes verbatim at the vendored revision (NOTICE, OQ-21)
+    proc = subprocess.run(("git", "-C", source, "show", "%s:LICENSE" % rev),
+                          capture_output=True)
+    if proc.returncode != 0:
+        raise SystemExit("tezgah-import-ai-research: upstream has no LICENSE at %s: %s"
+                         % (rev, proc.stderr.decode(errors="replace").strip()
+                            or proc.returncode))
+    licence = proc.stdout
     library = json.dumps(manifest, indent=1, sort_keys=True) + "\n"
 
     # SKILL.md is tezgah's own prose, not generated: the import refreshes what it
@@ -376,6 +386,8 @@ def cmd_import(source, rev, out):
             fh.write(text)
     with open(os.path.join(out, "library.json"), "w", encoding="utf-8") as fh:
         fh.write(library)
+    with open(os.path.join(out, "LICENSE"), "wb") as fh:
+        fh.write(licence)
     if kept is not None:
         with open(entry, "w", encoding="utf-8") as fh:
             fh.write(kept)
@@ -411,10 +423,10 @@ def cmd_check(out):
         for name in sorted(names):
             rel = os.path.relpath(os.path.join(root, name), out)
             # library.json is the manifest itself, SKILL.md is tezgah's own entry
-            # point, and SOURCE is prose derived from the manifest (a test pins
-            # that it names the manifest's revision); none is vendored upstream
-            # content, so none carries a digest.
-            if rel in ("library.json", "SKILL.md", "SOURCE") or rel in expected:
+            # point, SOURCE is prose derived from the manifest (a test pins
+            # that it names the manifest's revision), and LICENSE is upstream's
+            # licence file; none is vendored skill content, so none carries a digest.
+            if rel in ("library.json", "SKILL.md", "SOURCE", "LICENSE") or rel in expected:
                 continue
             problems.append("unlisted %s" % rel)
     if problems:

package/bin/tezgah-index

@@ -21,6 +21,9 @@ def main():
     if "-h" in args or "--help" in args:
         print(__doc__.strip())
         return 0
+    if any(a.startswith("-") for a in args):
+        print("usage: tezgah-index [PATH]", file=sys.stderr)
+        return 2
     cwd = os.path.realpath(args[0] if args else os.getcwd())
     if not under(cwd):
         return 0

package/bin/tezgah-lessons

@@ -118,6 +118,18 @@ def main(argv):
     ap.add_argument("--root", default=linked_main(here) or here)
     ap.add_argument("--fixture")
     args = ap.parse_args(argv)
+    prompts = None
+    if args.fixture:
+        # read before any proposal prints: an unreadable fixture is usage (2),
+        # never exit 1, which means the merges would lower recall
+        try:
+            with open(args.fixture, encoding="utf-8") as fh:
+                prompts = [(p["q"], [g - 1 for g in p["gt"]])
+                           for p in json.load(fh)["lessons_prompts"]]
+        except (OSError, ValueError, KeyError, TypeError) as exc:
+            print("tezgah-lessons: cannot read --fixture %s: %s" % (args.fixture, exc),
+                  file=sys.stderr)
+            return 2
     lines = tezgah_lessons.lines(args.root)
     print("Proposals for %s (nothing is written; apply what you agree with by hand):"
           % os.path.join(args.root, ".tezgah", "lessons.md"))
@@ -133,11 +145,8 @@ def main(argv):
         for needle, by in RETIRE:
             if needle in ln:
                 print("retire %d: append `|| enforced_by: %s`" % (n, by))
-    if not args.fixture:
+    if prompts is None:
         return 0
-    with open(args.fixture, encoding="utf-8") as fh:
-        prompts = [(p["q"], [g - 1 for g in p["gt"]])
-                   for p in json.load(fh)["lessons_prompts"]]
     after_lines, where = merged(lines, groups)
     before = recall(lines, prompts)
     after = recall(after_lines, [(q, sorted({where[g] for g in gt if g in where}))

package/bin/tezgah-mcp

@@ -312,6 +312,10 @@ def serve(stdin, stdout):
 
 
 def main():
+    if sys.argv[1:]:
+        print("tezgah-mcp: takes no arguments; it is a stdio MCP server a host "
+              "starts", file=sys.stderr)
+        return 2
     try:
         return serve(sys.stdin, sys.stdout)
     except BrokenPipeError:

package/bin/tezgah-migrate

@@ -299,6 +299,9 @@ def discover():
 def main(argv):
     apply, repos, i = False, [], 0
     while i < len(argv):
+        if argv[i] in ("-h", "--help"):
+            print(__doc__.strip())
+            return 0
         if argv[i] == "--apply":
             apply = True
         elif argv[i] == "--repo" and i + 1 < len(argv):

package/bin/tezgah-ocr-review

@@ -19,7 +19,8 @@ points at ~/.gitconfig, XDG_CONFIG_HOME at the user's config dir, and a
 core.excludesFile resolved with the user's HOME is passed in absolute. The omp
 child keeps the user's env - it needs its own credentials.
 
-Exit 0 ok; 2 when `ocr` or `omp` is missing; 3 when a path OCR could read looks
+Exit 0 ok; 2 on misuse (an unknown flag, --commit beside --from/--to) or a missing
+tool (`ocr` or `omp`); 3 when a path OCR could read looks
 like a secret (its file_read could send it to the model; --allow-secrets skips
 the check) - the working tree with untracked and ignored files, or the tree of
 --to / --commit; 4 when the runner's own setup fails (not a git repository, git

package/bin/tezgah-optimize

@@ -302,7 +302,7 @@ def cmd_push(args):
                          "it out, or push an explicit ref)" % root])
     at = time.time()
     for row in reversed(recorded(root, "pushes")):
-        if row.get("sha") != sha or not isinstance(row.get("at"), (int, float)):
+        if not same_commit(row.get("sha"), sha) or not isinstance(row.get("at"), (int, float)):
             continue
         waited = at - float(row["at"])
         if waited < PUSH_WINDOW:
@@ -324,6 +324,9 @@ def main(argv):
     if len(argv) < 2:
         print(__doc__, file=sys.stderr)
         return 2
+    if argv[1] in ("-h", "--help"):
+        print(__doc__.strip())
+        return 0
     cmd, rest = argv[1], argv[2:]
     if cmd == "next":
         return cmd_next(rest)

package/bin/tezgah-pony

@@ -23,6 +23,9 @@ def main(argv):
         print(__doc__.strip())
         return 0
     args = [a for a in argv if not a.startswith("-")]
+    if len(args) != len(argv):
+        print("%s\nlevels: %s" % (USAGE, ", ".join(PONY_LEVELS)), file=sys.stderr)
+        return 2
     if not args:
         print(pony_level())
         return 0

package/bin/tezgah-research

@@ -25,6 +25,8 @@
   tezgah-research verdict <slug> <id> met|not-met|unanswerable --evidence "<ref>"
                                                    record one success criterion's verdict
   tezgah-research conclude <slug>                  conclude a line whose criteria all carry a verdict
+  tezgah-research choose <slug> <decision> <variant> --ack "<the owner's words>"
+                                                   record the owner's pick of a recommended variant
   tezgah-research migrate-layout                   move flat research/<slug> into open/ or done/
   tezgah-research close <slug> --limit "<reason>"  conclude a line as a deliberate limit
   tezgah-research seal <slug> [--history-lost] --ack "<owner decision>"
@@ -121,14 +123,20 @@ no status, a design/plan/analysis/code deliverable with no decision comparing it
 variants - printing every open slug with its reasons. `--allow-open "<reason>"`
 opens the new line anyway and writes the reason into its `log.md` as the first
 entry; an empty reason is misuse, and the hatch is refused while any open line has
-`check` errors. `close <slug> --limit "<reason>"` concludes a line on purpose,
+`check` errors other than a criterion whose verdict is still `pending` (a line in
+flight). Both refusals say that a line another session is running goes to the
+owner, not to this session. `close <slug> --limit "<reason>"` concludes a line on purpose,
 writing the reasons it was still open into `state.json` `closed` and `log.md`.
 `--supersedes <old>` opens a new version of an existing line, which then carries
 the old deliverable as a variant; a line asking an existing line's exact question
 without it is refused. `compare` appends one cell to
 `decisions/<decision>/comparison.jsonl` under the rule `check` applies to it.
+A rules-9 decision.md writes the line's pick as `recommended:`; `choose` records
+the owner's `chosen:` with an `owner:` line holding their words, and `conclude`
+names each recommendation still waiting for it.
 `check` prints the same list of open lines after the per-line report, and so does
-`status`, so neither state has to be discovered by being refused.
+`status`, so neither state has to be discovered by being refused. Both also fail
+a hidden dir under `research/`, which no line may live in.
 
 `init --method exploratory` (rules 7) opens a campaign instead of a question:
 `--arena` and `--budget` (and, for a measurable arena, `--evaluator` with its
@@ -286,6 +294,7 @@ def cmd_init(args):
             print("  %s: %s" % (name, "; ".join(reasons)))
         print('to open %s anyway, say why: tezgah-research init %s '
               '--allow-open "<reason>"' % (slug, slug))
+        print(tr.OWNER_ASK)
         return 1
     broken = tr.broken_open_lines(repo) if unfinished else []
     if broken:
@@ -297,6 +306,7 @@ def cmd_init(args):
             print("  %s: %d error(s), first: %s" % (name, len(errors), errors[0]))
         print('fix them, or record what is left: tezgah-research close <slug> '
               '--limit "<reason>"')
+        print(tr.OWNER_ASK)
         return 1
     twins = [t for t in tr.serial_twins(repo, slug, {"question": question})
              if t != supersedes]
@@ -486,26 +496,29 @@ def cmd_check(args):
     known = tr.slugs(repo)
     if rest and rest[0] not in known:
         print("FAIL %s: no such research line (have: %s)"
-              % (rest[0], ", ".join(known) or "none"))
+              % (rest[0], ", ".join(known) or "none"),
+              file=sys.stderr if as_json else sys.stdout)
         return 1
     problems = 0
     report = {}
-    if known:
+    # under --json the rows already carry every FAIL/warn: stdout is the payload
+    say = (lambda _text: None) if as_json else print
+    if known or tr.stray_dirs(repo):
         report = tr.check(repo, rest[0] if rest else None, strict=strict,
                           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))
+                say("FAIL %s: %s" % (slug, err))
             for warn in row["warnings"]:
-                print("warn %s: %s" % (slug, warn))
+                say("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))
+        say("no research line under %s" % tr.root(repo))
     lines = len(report)
     if ask_orx:
         # The registry is the repository's, not a line's, so this runs whatever the
@@ -513,9 +526,9 @@ def cmd_check(args):
         report["orx"] = tr.check_orx(repo, tp.orx_bin(), strict=strict)
         for err in report["orx"]["errors"]:
             problems += 1
-            print("FAIL orx: %s" % err)
+            say("FAIL orx: %s" % err)
         for warn in report["orx"]["warnings"]:
-            print("warn orx: %s" % warn)
+            say("warn orx: %s" % warn)
     if as_json:
         # The payload is the whole answer for a machine caller: a sentence after
         # it is not JSON, and one before it is prose the reader never asked for.
@@ -1067,6 +1080,28 @@ def cmd_conclude(args):
             print("FAIL conclude: %s" % problem)
         return 1
     print("concluded %s; it moved to research/done/%s" % (slug, slug))
+    for decision, variant in tr.owner_waits(repo, slug):
+        print("report to the owner: %s is recommended, not chosen; building it waits "
+              "for the owner's answer (tezgah-research choose %s %s %s --ack "
+              "\"<their words>\")" % (variant, slug, decision, variant))
+    return 0
+
+
+def cmd_choose(args):
+    """Record the owner's pick among a decision's produced variants."""
+    usage = 'choose <slug> <decision> <variant> --ack "<the owner\'s words>"'
+    if len(args) != 5 or args[3] != "--ack":
+        return misuse(usage)
+    slug, decision, variant, _flag, ack = args
+    repo = repo_root(os.getcwd())
+    if slug not in tr.slugs(repo):
+        return misuse("no such research line: %s" % slug)
+    problem = tr.choose_line(repo, slug, decision, variant, ack,
+                             time.strftime("%Y-%m-%d"))
+    if problem:
+        print("FAIL choose: %s" % problem)
+        return 1
+    print("decisions/%s: the owner chose %s" % (decision, variant))
     return 0
 
 
@@ -1184,6 +1219,9 @@ def main(argv):
         print(__doc__, file=sys.stderr)
         return 2
     cmd, rest = argv[1], argv[2:]
+    if cmd in ("-h", "--help"):
+        print(__doc__.strip())
+        return 0
     if cmd == "--all":
         return cmd_all(rest)
     if cmd == "init":
@@ -1212,6 +1250,8 @@ def main(argv):
         return cmd_verdict(rest)
     if cmd == "conclude":
         return cmd_conclude(rest)
+    if cmd == "choose":
+        return cmd_choose(rest)
     if cmd == "migrate-layout":
         return cmd_migrate_layout(rest)
     if cmd == "close":
@@ -1237,7 +1277,8 @@ def main(argv):
         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, "
+                  "components, migrate, source, compare, verdict, conclude, choose, "
+                  "migrate-layout, "
                   "close, seal, import, next, idea, stage, match, board, dedup, yield, cite, "
                   "fetch, search, instrument, gold, label, switch, release-check, "
                   "calibration)" % cmd)

package/bin/tezgah-rollback

@@ -55,6 +55,9 @@ def session(sid, force, dry_run):
 
 def main(argv):
     args = list(argv)
+    if "-h" in args or "--help" in args:
+        print(__doc__.strip())
+        return 0
     sid = None
     if "--session" in args:
         at = args.index("--session")

package/bin/tezgah-route

@@ -5,7 +5,7 @@
   tezgah-route --check                          the table's age and refresh flags
   tezgah-route --refresh                        re-read prices/ids (OpenRouter),
                                                 resolve opencode selectors
-  tezgah-route --mode auto|anthropic|zai|any|openai|off
+  tezgah-route --mode auto|anthropic|zai|any|experientiallabs|openai|off
                                                 omp's family, then re-apply omp
   tezgah-route --health                         probe the other funded families;
                                                 one at a limit leaves the chain