@r1z4x/tezgah 1.5.1 → 1.7.0

package/bin/tezgah-research

@@ -2,8 +2,10 @@
 """tezgah-research - the research workspace CLI.
 
   tezgah-research init <slug> --ask "<the user's words>" [--question "..."]
-                       [--method qualitative|measured] [--in "<covered>"]... [--out "<left alone>"]...
-                       [--allow-open "<why>"] [--supersedes <slug>]   scaffold a line
+                       [--method qualitative|measured|exploratory] [--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
@@ -16,11 +18,25 @@
   tezgah-research source <slug> <hypothesis> --run <orxRunId> [--command "<cmd>"]
                            [--scope real|fixture|derived] [--fixture "<what was generated>"]
   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
+  tezgah-research conclude <slug>                  conclude a line whose criteria all carry a verdict
+  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>"
                                                    seal a line concluded before seals existed
   tezgah-research import <checkout> [<slug>] [--allow-open "<why>"]
                                                    bring lines from another checkout, with history
+  tezgah-research next --topic <t> [--flow metric-dashboard|feature] [--json]
+                                                   the product-flow steps of a topic and the next one
+  tezgah-research idea <slug>                      record one idea of an exploratory line from stdin
+  tezgah-research stage <slug> <idea> <stage> [--evidence "<ref or JSON>"] [--reason "<why>"]
+                                                   move an idea to its next stage
+  tezgah-research match <slug>                     record one judged tournament match from stdin
+  tezgah-research board <slug> [--json]            each idea's stage, score and next action
+  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
 
 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
@@ -89,10 +105,18 @@ without it is refused. `compare` appends one cell to
 `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.
 
+`init --method exploratory` (rules 7) opens a campaign instead of a question:
+`--arena` and `--budget` (and, for a measurable arena, `--evaluator` with its
+`--metric`, whose sha256 `init` records) are the lock committed before the
+first idea. `idea`, `stage` and `match` append the campaign's rows under the
+lock, each judged by the one function `check` applies to it; a `prior-art`
+stage whose verdict is `known` takes `--reason` and is killed in the same
+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`, which writes nothing and prints
-one reason per problem, or a new line refused for `init` over unfinished ones - 2
-misuse.
+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.
 """
 import json
 import os
@@ -103,6 +127,7 @@ import time
 HERE = os.path.dirname(os.path.dirname(os.path.realpath(__file__)))
 sys.path.insert(0, os.path.join(HERE, "hooks"))
 import tezgah_paths as tp  # noqa: E402
+import tezgah_product as tp_product  # noqa: E402
 import tezgah_research as tr  # noqa: E402
 
 
@@ -138,6 +163,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 = {}
     rest = args[1:]
     while rest:
         flag = rest.pop(0)
@@ -157,11 +183,34 @@ def cmd_init(args):
             allow = rest.pop(0)
         elif flag == "--supersedes" and rest:
             supersedes = rest.pop(0)
+        elif flag in ("--arena", "--budget", "--evaluator", "--metric") and rest \
+                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] [--in "<covered>"]...'
+                          ' [--method qualitative|measured|exploratory] [--in "<covered>"]...'
                           ' [--out "<left alone>"]... [--question "..."]'
-                          ' [--allow-open "<reason>"] [--supersedes <slug>]')
+                          ' [--allow-open "<reason>"] [--supersedes <slug>]'
+                          ' [--arena "<problem>" --budget "<budget>"'
+                          ' [--evaluator <path> --metric "<metric>"]]')
+    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.
+        if not all(arena.get(f, "").strip() for f in ("--arena", "--budget")):
+            return misuse('--method exploratory needs --arena "<the problem, verbatim>" '
+                          'and --budget "<ideas, pilots, full runs, wall time>"')
+        if bool(arena.get("--evaluator", "").strip()) != bool(
+                arena.get("--metric", "").strip()):
+            return misuse("--evaluator and --metric go together: the file that scores a "
+                          "candidate and the number it returns")
+        evaluator = arena.get("--evaluator", "").strip()
+        if evaluator and (os.path.isabs(evaluator) or ".." in evaluator.split("/")
+                          or not os.path.isfile(os.path.join(repo_root(os.getcwd()),
+                                                             evaluator))):
+            return misuse("--evaluator %r is not a file under the repository" % evaluator)
+    elif arena:
+        return misuse("--arena, --budget, --evaluator and --metric belong to "
+                      "--method exploratory")
     problems = tr.ask_problems(ask, tier)
     if problems:
         for problem in problems:
@@ -204,9 +253,14 @@ def cmd_init(args):
               "init %s --supersedes %s" % (", ".join(twins), slug, twins[0]))
         return 1
     created = time.strftime("%Y-%m-%d")
+    record = None
+    if method == "exploratory":
+        record = tr.arena_record(repo, arena["--arena"], arena["--budget"],
+                                 arena.get("--evaluator", "").strip(),
+                                 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)
+                   scope_in=scope_in, scope_out=scope_out, arena=record)
     if allow is not None:
         problem = tr.note_open(repo, slug, allow, created)
         if problem:
@@ -217,7 +271,14 @@ def cmd_init(args):
         print("  wrote %s" % path)
     for problem in tr.scope_problems(tr.line_state(repo, slug)):
         print("  owed: %s" % problem)
-    if method == "qualitative":
+    if method == "exploratory":
+        print("\nnext: commit the arena now, before any idea - `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 "
+              "naming its operator, generator and kill result), commit them, and "
+              "follow `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 "
               "(`orx discover`, `orx paper`), save each to literature/ as you read "
               "it, and record every claim with a `trace` naming the S<n> it answers "
@@ -245,12 +306,17 @@ 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)
+
+
+def commit_path(repo, path, message):
+    """Stage and commit `path` alone in the private repository of `repo`."""
     ws = tp.ensure_workspace(repo)
     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(tr.line_dir(repo, slug), ws)
+    rel = os.path.relpath(path, ws)
     try:
         done = tp.ws_git(repo, "add", "-A", "--", rel)
         if not done.returncode:
@@ -298,6 +364,7 @@ def cmd_check(args):
                 print("warn %s: %s" % (slug, warn))
     else:
         print("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
         # lines look like - which is also why it is only asked for when --orx says so.
@@ -313,7 +380,7 @@ def cmd_check(args):
         print(json.dumps(report, indent=2))
         return 1 if problems else 0
     if not problems:
-        print("research: %d line(s) ok" % len(report))
+        print("research: %d line(s) ok" % lines)
     if not rest and not all_lines:
         done = [slug for slug in known if tr.sealed(repo, slug)]
         if done:
@@ -576,6 +643,206 @@ def cmd_compare(args):
     return 0
 
 
+def _campaign_slug(args, usage, count=1):
+    """(repo, slug, None) for a campaign command's line, or (None, None, exit code)."""
+    if len(args) < count:
+        return None, None, misuse(usage)
+    repo = repo_root(os.getcwd())
+    known = tr.slugs(repo)
+    if args[0] not in known:
+        return None, None, misuse("no such research line (have: %s)"
+                                  % (", ".join(known) or "none"))
+    return repo, args[0], None
+
+
+def _stdin_row(what):
+    """(row, None) for the one JSON object on stdin, or (None, exit code)."""
+    try:
+        body = sys.stdin.buffer.read().decode("utf-8")
+        row = json.loads(body)
+    except (UnicodeDecodeError, ValueError):
+        return None, misuse("%s needs one JSON object on stdin" % what)
+    if not isinstance(row, dict):
+        return None, misuse("%s needs one JSON object on stdin" % what)
+    return row, None
+
+
+def _refused(slug, problems):
+    for problem in problems:
+        print("FAIL %s: %s" % (slug, problem))
+    return 1 if problems else 0
+
+
+def cmd_idea(args):
+    """Record one idea of an exploratory line from stdin (`append_idea`)."""
+    repo, slug, code = _campaign_slug(args, "idea <slug>")
+    if code is not None or len(args) != 1:
+        return code if code is not None else misuse("idea <slug>")
+    row, code = _stdin_row("idea")
+    if code is not None:
+        return code
+    try:
+        iid, problems = tr.append_idea(repo, slug, row)
+    except OSError as exc:
+        iid, problems = row.get("id"), ["cannot append to ideas.jsonl: %s" % exc]
+    if _refused(slug, problems):
+        return 1
+    print("idea %s recorded" % iid)
+    return 0
+
+
+def cmd_stage(args):
+    """Move one idea to a stage, with the evidence that stage takes (a path or a
+    JSON object) and the reason a kill - or a known prior art - owes."""
+    usage = ('stage <slug> <idea> <stage> [--evidence "<ref or JSON>"] '
+             '[--reason "<why>"]')
+    repo, slug, code = _campaign_slug(args, usage, 3)
+    if code is not None:
+        return code
+    row = {"idea": args[1], "stage": args[2]}
+    reason, rest = None, args[3:]
+    while rest:
+        flag = rest.pop(0)
+        if flag == "--evidence" and rest and "evidence" not in row:
+            text = rest.pop(0)
+            try:
+                row["evidence"] = json.loads(text) if text.lstrip()[:1] in "{[" \
+                    and text.strip() else text
+            except ValueError:
+                return misuse("--evidence starts like JSON and does not parse")
+        elif flag == "--reason" and rest and reason is None:
+            reason = rest.pop(0)
+        else:
+            return misuse(usage)
+    row["date"] = time.strftime("%Y-%m-%d")
+    kill_reason = None
+    if row["stage"] == "killed":
+        row["reason"] = reason
+    else:
+        kill_reason = reason
+    try:
+        problems = tr.append_stage(repo, slug, {k: v for k, v in row.items()
+                                                if v is not None}, kill_reason)
+    except OSError as exc:
+        problems = ["cannot append to stages.jsonl: %s" % exc]
+    if _refused(slug, problems):
+        return 1
+    killed = row["stage"] == "prior-art" and kill_reason \
+        and isinstance(row.get("evidence"), dict) \
+        and row["evidence"].get("verdict") == "known"
+    print("%s: %s recorded%s" % (row["idea"], row["stage"],
+                                 " and killed (%s)" % kill_reason if killed else ""))
+    return 0
+
+
+def cmd_match(args):
+    """Record one judged tournament match from stdin (`append_match`)."""
+    repo, slug, code = _campaign_slug(args, "match <slug>")
+    if code is not None or len(args) != 1:
+        return code if code is not None else misuse("match <slug>")
+    row, code = _stdin_row("match")
+    if code is not None:
+        return code
+    try:
+        problems = tr.append_match(repo, slug, row)
+    except OSError as exc:
+        problems = ["cannot append to tournament.jsonl: %s" % exc]
+    if _refused(slug, problems):
+        return 1
+    print("match %s v %s recorded" % (row.get("a"), row.get("b")))
+    return 0
+
+
+def cmd_board(args):
+    """The campaign's board: a report a fresh session resumes from, exit 0."""
+    flags = [a for a in args if a != "--json"]
+    repo, slug, code = _campaign_slug(flags, "board <slug> [--json]")
+    if code is not None or len(flags) != 1:
+        return code if code is not None else misuse("board <slug> [--json]")
+    report = tr.board(repo, slug)
+    if "--json" in args:
+        print(json.dumps(report, indent=2))
+        return 0
+    for line in tr.board_text(report):
+        print(line)
+    return 0
+
+
+def cmd_dedup(args):
+    """Cluster the proposed ideas by statement; writes nothing, exit 0."""
+    usage = "dedup <slug> [--threshold <(0,1]>] [--json]"
+    rest, threshold, as_json = list(args), None, False
+    if "--json" in rest:
+        rest.remove("--json")
+        as_json = True
+    if "--threshold" in rest:
+        i = rest.index("--threshold")
+        try:
+            threshold = float(rest[i + 1])
+        except (IndexError, ValueError):
+            return misuse(usage)
+        if not 0 < threshold <= 1:
+            return misuse("--threshold is a similarity in (0, 1]")
+        rest = rest[:i] + rest[i + 2:]
+    repo, slug, code = _campaign_slug(rest, usage)
+    if code is not None or len(rest) != 1:
+        return code if code is not None else misuse(usage)
+    report = tr.dedup(repo, slug, threshold)
+    if as_json:
+        print(json.dumps(report, indent=2))
+        return 0
+    for line in tr.dedup_text(report, slug):
+        print(line)
+    return 0
+
+
+def cmd_yield(args):
+    """Per operator and generator family, how far the ideas got; exit 0."""
+    if [a for a in args if a not in ("--json", "--all-lines")]:
+        return misuse("yield [--json] [--all-lines]")
+    report = tr.yield_report(repo_root(os.getcwd()), all_lines="--all-lines" in args)
+    if "--json" in args:
+        print(json.dumps(report, indent=2))
+        return 0
+    for line in tr.yield_text(report):
+        print(line)
+    return 0
+
+
+def cmd_next(args):
+    """The product-flow steps of one topic with their status, then the first
+    missing or due step's skill and command; a report, so exit 0."""
+    usage = "next --topic <t> [--flow %s] [--json]" % "|".join(tp_product.FLOWS)
+    opts, as_json, rest = {}, False, list(args)
+    while rest:
+        arg = rest.pop(0)
+        if arg == "--json":
+            as_json = True
+        elif arg in ("--topic", "--flow") and rest and arg not in opts:
+            opts[arg] = rest.pop(0)
+        else:
+            return misuse(usage)
+    flow = opts.get("--flow", "metric-dashboard")
+    if "--topic" not in opts:
+        return misuse(usage)
+    if flow not in tp_product.FLOWS:
+        return misuse("unknown flow %r (%s)" % (flow, ", ".join(tp_product.FLOWS)))
+    topic = opts["--topic"]
+    steps = tp_product.next_steps(repo_root(os.getcwd()), topic, flow)
+    if as_json:
+        # the step list next_steps returns; the next step is its first
+        # missing or due entry
+        print(json.dumps(steps, indent=2))
+        return 0
+    first = next((s for s in steps if s["status"] in ("missing", "due")), None)
+    for n, step in enumerate(steps, 1):
+        print("%d. %s [%s] %s - %s" % (n, step["id"], step["status"], step["skill"],
+                                       step["detail"]))
+    print("next: %s - %s" % (first["skill"], first["command"]) if first
+          else "next: nothing left")
+    return 0
+
+
 def cmd_verdict(args):
     """Record one success criterion's verdict, with the evidence it rests on."""
     if len(args) < 3:
@@ -769,6 +1036,8 @@ def main(argv):
         return cmd_source(rest)
     if cmd == "compare":
         return cmd_compare(rest)
+    if cmd == "next":
+        return cmd_next(rest)
     if cmd == "verdict":
         return cmd_verdict(rest)
     if cmd == "conclude":
@@ -781,8 +1050,13 @@ def main(argv):
         return cmd_seal(rest)
     if cmd == "import":
         return cmd_import(rest)
+    campaign = {"idea": cmd_idea, "stage": cmd_stage, "match": cmd_match,
+                "board": cmd_board, "dedup": cmd_dedup, "yield": cmd_yield}
+    if cmd in campaign:
+        return campaign[cmd](rest)
     return misuse("unknown command %r (init, commit, check, status, --all, claim, predict, "
-                  "components, migrate, source, compare, close, seal, import)" % cmd)
+                  "components, migrate, source, compare, verdict, conclude, migrate-layout, "
+                  "close, seal, import, next, idea, stage, match, board, dedup, yield)" % cmd)
 
 
 if __name__ == "__main__":

package/bin/tezgah-route

@@ -6,6 +6,11 @@
   tezgah-route --refresh                        re-read prices/ids (OpenRouter),
                                                 resolve opencode selectors
   tezgah-route --mode auto|anthropic|any        omp's family, then re-apply omp
+  tezgah-route --health                         probe the other funded families;
+                                                one at a limit leaves the chain
+                                                until its reset; re-apply omp
+  tezgah-route --fallback vendor|any|none       what a chain falls back to, then
+                                                re-apply omp
   tezgah-route --report                         each route's first check, by tier
 
 A brief naming stored data, a migration, credentials, the gate or security goes to
@@ -39,12 +44,14 @@ import argparse
 import json
 import os
 import sys
+import time
 
 HERE = os.path.dirname(os.path.dirname(os.path.realpath(__file__)))
 sys.path.insert(0, os.path.join(HERE, "hooks"))
 import tezgah_integrity as ti  # noqa: E402
 import tezgah_judge  # noqa: E402
 import tezgah_models as tm  # noqa: E402
+import tezgah_paths as tp  # noqa: E402
 
 
 def main(argv):
@@ -62,6 +69,12 @@ def main(argv):
     parser.add_argument("--refresh", action="store_true",
                         help="re-read prices and ids, resolve opencode selectors")
     parser.add_argument("--mode", choices=tm.MODES, help="omp's family, then re-apply")
+    parser.add_argument("--health", action="store_true",
+                        help="probe the other funded families, record the ones at a "
+                             "limit until their reset, then re-apply omp's chain")
+    parser.add_argument("--fallback", choices=tp.FALLBACKS,
+                        help="which families a chain falls back to (config.json "
+                             "`fallback`), then re-apply")
     parser.add_argument("--report", action="store_true",
                         help="every ledger's routes joined to the first check after each")
     args = parser.parse_args(argv[1:])
@@ -89,6 +102,40 @@ def main(argv):
             print(line("%s %s" % (via, tier), counts))
         print(line("jev-below-static", below))
         return 0
+    if args.fallback:
+        # config.json `fallback` has one other writer: none. A config that does not
+        # parse is refused, not replaced (like tezgah-setup --jev).
+        try:
+            with open(tp.CONFIG, encoding="utf-8") as fh:
+                cfg = json.load(fh)
+        except FileNotFoundError:
+            cfg = {}
+        except (OSError, ValueError):
+            print("%s is not valid JSON; fallback not set" % tp.CONFIG, file=sys.stderr)
+            return 1
+        if cfg.get("fallback") != args.fallback:
+            cfg["fallback"] = args.fallback
+            os.makedirs(os.path.dirname(tp.CONFIG), exist_ok=True)
+            tmp = tp.CONFIG + ".tmp"
+            with open(tmp, "w", encoding="utf-8") as fh:
+                json.dump(cfg, fh, indent=2, sort_keys=True)
+                fh.write("\n")
+            os.replace(tmp, tp.CONFIG)
+        print("fallback: %s (%s)" % (args.fallback, tp.CONFIG))
+        print(tm.apply_omp() or "omp not answering; the chain applies at the next setup")
+        return 0
+    if args.health:
+        mode = tm.omp_mode()
+        data = tm.refresh_health(mode)
+        for family in tm.funded_families(live=False):
+            row = data["down"].get(family)
+            state = ("the mode's own family, not probed" if family == mode else
+                     "down until %s - %s" % (time.strftime("%Y-%m-%d %H:%M",
+                                                         time.localtime(row["until"])),
+                                             row.get("reason", "")) if row else "up")
+            print("%s: %s" % (family, state))
+        print(tm.apply_omp() or "omp not answering; the chain applies at the next setup")
+        return 0
     if args.mode:
         data = tm.overlay()
         data.pop("mode", None)
@@ -102,7 +149,7 @@ def main(argv):
         return 0
     if not brief:
         print("usage: tezgah-route \"<brief>\" [--phase P] [--json] | --check | --refresh "
-              "| --mode M | --report", file=sys.stderr)
+              "| --mode M | --health | --fallback F | --report", file=sys.stderr)
         return 2
     ask = tezgah_judge.ask if tezgah_judge.available() else None
     out = tm.route(brief, args.phase, ask)

package/bin/tezgah-setup

@@ -187,7 +187,7 @@ OMP_LESSONS = ("Read `.tezgah/lessons.md` in the repository if it exists and tre
 LOCAL_BIN = os.path.join(HOME, ".local", "bin")
 SKILLS = ["harness", "tezgah-contract", "ponytail", "i-have-adhd", "no-ai-slop",
           "analyze-app", "plan-add", "plan-status", "plan-sync", "research",
-          "product-analysis", "feature-audit", "design-contract",
+          "product-analysis", "product-flow", "feature-audit", "design-contract",
           "design-library", "pm-frameworks", "ai-research", "rl-env"]
 
 
@@ -233,8 +233,9 @@ MATERIALISED = os.path.join(tp.CONFIG_DIR, "materialised")
 # name too - a switch left behind is a rule that stays silent with no file saying why.
 OFF_SWITCH_NAMES = ("adhd-off", "agents-off", "consult-off", "docs-judge-off", "exec-mode.off",
                     "judge-off", "lang-off", "orchestrate-off", "ponytail-auto.off",
-                    "pretooluse-off", "reminder-off", "research-off", "spec-off", "task-off",
-                    "triage-off", "update-check-off", "verify-off", "workspace-off")
+                    "pretooluse-off", "reminder-off", "research-off", "slices-off",
+                    "spec-off", "task-off", "triage-off", "update-check-off", "verify-off",
+                    "workspace-off")
 # The ~/.config/tezgah entries this installer generates. A full uninstall
 # removes exactly these (plus any `*.off` switch and the `.tezgah-bak` of one of
 # these names) and keeps anything else: a file the user put there is not
@@ -314,9 +315,11 @@ CURSOR_HOOK_EVENTS = {
 # makes a config written before this existed behave exactly as it used to.
 # --enable/--disable/--devtools and the wizard set it before anything is written.
 FEATURES = None
-# The `reply_lang` this run stores (--reply-lang); None keeps what config.json
-# says, and a config without the key reads as `tr` (tezgah_paths.reply_lang).
-REPLY_LANG = None
+# The `language` this run stores (--language, or its older spelling
+# --reply-lang); None keeps what config.json says. A first install with no flag
+# takes the environment's (`tp.env_language`); a config made before the key
+# existed is pinned to `tr`, the default it ran under (tezgah_paths.language).
+LANGUAGE = None
 OK, NO = "  ok  ", " MISS "
 
 
@@ -1028,6 +1031,10 @@ def install_common(new_roots, hosts):
     cfg = read_config(tp.CONFIG, {})
     own = cfg is not None
     cfg = cfg if own else {}
+    # a first install is a config no install wrote yet: `--jev` alone writes
+    # the file too, so its existence says nothing; an install always writes
+    # `roots` and `prefix`
+    first = not any(key in cfg for key in ("roots", "prefix"))
     cfg["roots"] = [expand(r) for r in new_roots] if new_roots else \
         (tp.roots() or [tp.DEFAULT_ROOT])
     if tp.codegraph_bin():
@@ -1044,8 +1051,13 @@ def install_common(new_roots, hosts):
     # anywhere, so it moves the tree the install actually used instead of the
     # XDG default. An explicit --prefix or TEZGAH_PREFIX still wins over it.
     cfg["prefix"] = INSTALL_PREFIX
-    if REPLY_LANG:
-        cfg["reply_lang"] = REPLY_LANG
+    if LANGUAGE:
+        cfg["language"] = LANGUAGE
+    elif not any(key in cfg for key in ("language", "reply_lang")):
+        # an existing `reply_lang` is never rewritten; only a config with
+        # neither key gets one: the locale's on a first install, `tr` on an
+        # older one, so an upgrade changes no one's reply language
+        cfg["language"] = tp.env_language() if first else "tr"
     if own:
         write_json(tp.CONFIG, cfg)
         print("%s %s  roots=%s" % (OK, tp.CONFIG, cfg["roots"]))
@@ -5520,7 +5532,7 @@ def upgrade(version, dry_run):
     so its farm links would point back into it. The hosts and roots come from
     config.json, so an upgrade does not re-ask the install questions. Nothing
     else calls this: a flag never upgrades tezgah as a side effect of another
-    (hooks/tezgah_policy.py:792). Prints every step before running it, and
+    (hooks/tezgah_policy.py:812). Prints every step before running it, and
     `--dry-run` stops after the printing."""
     cfg = tp.config()
     hosts = cfg.get("hosts") or detected_hosts()
@@ -5713,10 +5725,11 @@ def main(argv):
                     version=tezgah_context.version() or "unknown")
     ap.add_argument("--roots")
     ap.add_argument("--hosts")
-    ap.add_argument("--reply-lang", choices=tp.REPLY_LANGS,
+    ap.add_argument("--language", "--reply-lang", choices=tp.languages(),
                     help="with --install: the language replies are asked for and "
-                         "the Stop rule checks (config.json `reply_lang`; `tr` "
-                         "when unset, `any` checks none)")
+                         "the Stop rule checks (config.json `language`; a first "
+                         "install takes LANGUAGE/LC_ALL/LC_MESSAGES/LANG, `en` "
+                         "when none names a pack; `any` checks none)")
     ap.add_argument("--jev", type=tp.jev_name, choices=tp.JEV_CHOICES,
                     help="the carrier the judgement seam reaches the Jev model "
                          "through (config.json `jev`; `auto` tries every one "
@@ -5736,9 +5749,9 @@ def main(argv):
     # so it is taken off before the flags are parsed (`--dry-run` still reads)
     command = argv[1:2] == ["update"]
     args = ap.parse_args(argv[2:] if command else argv[1:])
-    global FEATURES, INSTALL_PREFIX, HOST_DEPS, REPLY_LANG
+    global FEATURES, INSTALL_PREFIX, HOST_DEPS, LANGUAGE
     HOST_DEPS = args.host_deps
-    REPLY_LANG = args.reply_lang
+    LANGUAGE = args.language
     select_code = 0
     # --devtools is --enable <id> and nothing else: one code path, so the flag
     # cannot reach the selection in a way the explicit command does not.