@r1z4x/tezgah 1.0.0

package/bin/tezgah-status

@@ -0,0 +1,383 @@
+#!/usr/bin/env python3
+"""tezgah-status [PATH] [SESSION_ID] - the armed/used checklist for any host.
+
+Reads the same core the hooks do. Claude Code and Cursor show the color form in
+their status line; this CLI is how every host (and a human) gets it:
+
+  tezgah-status            plain one line (or ANSI when stdout is a terminal)
+  tezgah-status --color    force ANSI (green in force, yellow on-demand, red off)
+  tezgah-status --no-color force plain, or set NO_COLOR
+  tezgah-status --json     the structured segments (key/state/glyph/text)
+  tezgah-status --counters [SESSION_ID] [PATH]
+                           this session's ledger aggregate; the two may come in
+                           either order (the id is the one that is not a
+                           directory, PATH is accepted and ignored)
+  tezgah-status --counters --all
+                           every ledger on this machine in one aggregate, plus
+                           `ledgers`: the false-completion rate over the corpus,
+                           which no single session can answer
+  tezgah-status --counters --trend [--weeks=N]
+                           the same fold plus the two reports it carries: the
+                           drift series (every ledger bucketed into weeks, each
+                           with `false_completion/claims`, `tool_error_rate` and
+                           its row count, and the direction of the last three
+                           weeks that carry a denominator) and the tool firings
+                           (the top names by count, and the shipped `bin/`
+                           programs no row ran). `--weeks=N` is how many weeks
+                           the series prints, newest last, 8 by default. A
+                           report, not a gate; `--json` carries both.
+                           The MCP half of a retirement decision is manual:
+                           `tezgah-setup --mcp-schemas` measures what a server
+                           costs, this counts what it fires.
+  tezgah-status --skill-fitness
+                           per shipped skill, over the recorded sessions: how
+                           many opened it and which were never opened. A
+                           measurement, not a gate; `--json` carries the fold.
+                           `--all`/`--trend`/`--weeks` are modifiers of the
+                           counters fold and are a misuse here (exit 2), the same
+                           as they are anywhere else without `--counters`.
+  tezgah-status --failure-shapes
+                           the recurring refusal shapes mined from every ledger
+                           on this machine, with the corpus size read: one row
+                           per shape refused in at least RECURRING_SESSIONS (5)
+                           distinct sessions, carrying its fires-per-session
+                           beside the count so a frequency-ranked reading cannot
+                           recommend the rule that fires most - `drift` fires on
+                           long careful turns whether or not anything is
+                           drifting. A report, not a gate: it always exits 0.
+                           `--json` prints the whole fold.
+  tezgah-status --rule-yield
+                           every live gate rule (the labels hooks/tezgah_gate.py
+                           passes to _deny) with its fires over the real ledgers
+                           written since it shipped (its exposure, dated from git
+                           history). 0 fires over >= MIN_EXPOSURE (300) ledgers
+                           marks it retire-candidate, 0 fires over fewer
+                           low-exposure. A report, not a gate: it always exits 0
+                           and prints the corpus it read. `--json` prints it all.
+  tezgah-status --enforcers
+                           every always-on CORE rule with the gate rules and
+                           Stop classes that refuse on it (each with its
+                           guards) and the shape flags that only record it,
+                           read from the code; a status (enforced, partial,
+                           records, prose-only) and the record from
+                           docs/contract.md. A report, not a gate: it always
+                           exits 0. `--json` prints the rows.
+  tezgah-status --legend   explain the marks
+  tezgah-status --observable=consult,research,graph,orch
+                           the measures this surface can see; a measure outside
+                           the set renders as dim "no state" instead of claiming
+                           "armed, not used yet". A host that cannot see a skill
+                           read (dsh) passes the tool-use four.
+
+The session id may be passed as the second argument or via TEZGAH_SESSION;
+without it the "used" marks cannot light up, so a host that knows the id should
+pass it. `--` ends the options: `tezgah-status --json -- PATH SESSION_ID` reads
+both as positionals even when one starts with a dash.
+"""
+import json
+import os
+import sys
+
+HERE = os.path.dirname(os.path.dirname(os.path.realpath(__file__)))
+sys.path.insert(0, os.path.join(HERE, "hooks"))
+from tezgah_context import (  # noqa: E402
+    LEGEND, color_default, health_segments, render_line, skill_fitness)
+
+# How many rows of the tool histogram the plain report prints. The count is on
+# the line and `--json` carries every row, so a reader can always see what was
+# cut.
+TOP = 15
+
+
+def weeks_arg(args):
+    """`args` with the `--weeks` window folded out, and its value (None when the
+    flag was absent).
+
+    The spaced form needs its own reader: the split below sends every non-`--`
+    argument to `pos`, where a bare number would be read as a session id.
+    `--weeks` with nothing after it comes back as "" and fails the same check a
+    word does."""
+    out, value, i = [], None, 0
+    while i < len(args):
+        a = args[i]
+        if a == "--weeks":
+            value = args[i + 1] if i + 1 < len(args) else ""
+            i += 2 if i + 1 < len(args) else 1
+            continue
+        if a.startswith("--weeks="):
+            value, i = a.split("=", 1)[1], i + 1
+            continue
+        out.append(a)
+        i += 1
+    return out, value
+
+
+def rate(value, numerator, denominator):
+    """A ratio on the report's line: `0.5000 (1/2)`, or `n/a` with no
+    denominator - a week that decided nothing has no rate, and 0.0000 there
+    would read as a perfect week."""
+    return "n/a" if value is None else "%.4f (%d/%d)" % (value, numerator,
+                                                         denominator)
+
+
+def print_trend(counts, weeks):
+    """The drift series and the two histograms, for `--counters --trend`."""
+    import tezgah_integrity as ti
+    drift = ti.drift_series(counts, weeks)
+    print("drift: %d weeks, newest last (a week with no row prints 0 rows)"
+          % weeks)
+    for row in drift["rows"]:
+        print("  %s  rows %6d  false_completion/claims %s  tool_error_rate %s"
+              % (row["date"], row["events"],
+                 rate(row["false_completion_rate"], row["false_completion"],
+                      row["claims"]),
+                 rate(row["tool_error_rate"], row["errors"], row["decided"])))
+    print("  direction of the last three weeks with a denominator: "
+          "false_completion/claims %s, tool_error_rate %s"
+          % (drift["false_completion_trend"], drift["tool_error_trend"]))
+    fires = counts.get("tools") or {}
+    ranked = sorted(fires, key=lambda n: (-fires[n], n))
+    print("tool firings: %d names the rows carry, top %d"
+          % (len(ranked), TOP))
+    for name in ranked[:TOP]:
+        print("  %6d  %s" % (fires[name], name))
+    never = ti.unfired_programs(counts)
+    ran = len(counts.get("programs") or {})
+    print("shipped programs: %d of %d ran" % (ran, ran + len(never)))
+    if never:
+        print("  never fired: %s" % ", ".join(never))
+
+
+def print_fitness(fit):
+    """The skill-fitness report, for `--skill-fitness`."""
+    print("sessions read: %d of %d recorded" % (fit["sessions"], fit["recorded"]))
+    print("shipped skills: %d opened of %d"
+          % (len(fit["skills"]), len(fit["skills"]) + len(fit["never"])))
+    for skill in fit["skills"]:
+        print("  %6d  %s" % (skill["sessions"], skill["name"]))
+    if fit["never"]:
+        print("  never opened: %s" % ", ".join(fit["never"]))
+        # The one way to misread the number: a host that cannot see a read (or a
+        # session recorded before `skill:<name>` existed) records nothing, so
+        # "never opened" is a floor over what was recorded and not a census.
+        print("  (a floor: a host that cannot see a read records none, and only "
+              "the two marks predate `skill:<name>` - see docs/evidence.md)")
+
+
+def print_enforcers(as_json):
+    """The enforcement matrix, for `--enforcers`: its readers are
+    bin/tezgah-docs's, loaded by path (the script has no `.py` in its name)."""
+    import importlib.machinery
+    import importlib.util
+    loader = importlib.machinery.SourceFileLoader(
+        "tezgah_docs", os.path.join(HERE, "bin", "tezgah-docs"))
+    docs = importlib.util.module_from_spec(
+        importlib.util.spec_from_loader("tezgah_docs", loader))
+    loader.exec_module(docs)
+    found = docs.enforcement_report()
+    if as_json:
+        print(json.dumps(found, sort_keys=True))
+        return
+    rows = found["rows"]
+    count = {s: sum(1 for r in rows if r["status"] == s)
+             for s in ("enforced", "partial", "records", "prose-only")}
+    print("%d always-on CORE rules: %d enforced, %d partial, %d record only, %d "
+          "prose-only (%d prose-only with a recorded decision)" % (
+              len(rows), count["enforced"], count["partial"], count["records"],
+              count["prose-only"],
+              sum(1 for r in rows if r["status"] == "prose-only" and r["decision"]
+                  and r["decision"] != "no decision")))
+    for r in rows:
+        what = ", ".join("%s [%s]" % (e, ", ".join(r["guards"][e]))
+                         if r["guards"][e] else e for e in r["enforcers"]) or "none"
+        if r["decision"]:
+            what += " - %s" % r["decision"]
+        elif r["status"] in ("records", "prose-only"):
+            what += " - unrecorded"
+        print("  %-12s %-10s %s  %s" % (r["rule"], r["status"], r["label"], what))
+    print("tied to no always-on rule: %s" % (", ".join(found["unattached"]) or "-"))
+    for failure in found["failures"]:
+        print("unrecorded: %s" % failure)
+
+
+def main():
+    # `--` ends the options: what follows is PATH and SESSION_ID even when it
+    # starts with a dash. The dsh route and the MCP tool hand caller-chosen
+    # strings to this argv, and without the separator `sessionId=--failure-shapes`
+    # ran the machine-wide report (audit L-7, SEC-07).
+    argv = sys.argv[1:]
+    rest = argv[argv.index("--") + 1:] if "--" in argv else []
+    argv = argv[:argv.index("--")] if "--" in argv else argv
+    args, weeks = weeks_arg(argv)
+    # A sanity bound, not a policy: ten years of weeks is longer than any ledger
+    # this machine holds, and a number the reader mistyped should say so rather
+    # than print a thousand rows of nothing.
+    if weeks is not None and (not weeks.isdigit() or not 0 < int(weeks) <= 520):
+        sys.stderr.write("tezgah-status: --weeks wants a week count\n")
+        return 2
+    flags = {a for a in args if a.startswith("--")}
+    pos = [a for a in args if not a.startswith("--")] + rest
+    known = {"--legend", "--json", "--color", "--no-color", "--counters",
+             "--all", "--trend", "--skill-fitness", "--failure-shapes",
+             "--rule-yield", "--enforcers", "--help"}
+    unknown = sorted(f for f in flags
+                     if f not in known and not f.startswith("--observable="))
+    if unknown:
+        sys.stderr.write("tezgah-status: unknown option(s): %s (try --help)\n"
+                         % ", ".join(unknown))
+        return 2
+    if "--help" in flags:
+        sys.stdout.write(__doc__.strip() + "\n")
+        return 0
+    if "--legend" in flags:
+        sys.stdout.write(LEGEND)
+        return 0
+    # Placed above the report branches, not below them: `--all` is a modifier of
+    # the counters fold wherever it is written, so `--skill-fitness --all` is the
+    # same misuse `--all` alone is - a report branch that silently swallowed the
+    # flag would answer a question the user did not ask.
+    if "--all" in flags and "--counters" not in flags:
+        sys.stderr.write("tezgah-status: --all only means something with "
+                         "--counters\n")
+        return 2
+    # `--trend` and `--weeks` are modifiers of the counters fold: alone they read
+    # like a report of their own, and a silent no-op would print the status line
+    # instead - the answer to a question that was never asked. The check sits
+    # above every report branch, `--skill-fitness` included, for the same reason
+    # `--all`'s does: a branch that returns first would swallow the flag.
+    modifier = next((name for name, given in (("--trend", "--trend" in flags),
+                                              ("--weeks", weeks is not None))
+                     if given), None)
+    if modifier and "--counters" not in flags:
+        sys.stderr.write("tezgah-status: %s only means something with "
+                         "--counters\n" % modifier)
+        return 2
+    if "--skill-fitness" in flags:
+        fit = skill_fitness()
+        if "--json" in flags:
+            print(json.dumps(fit, sort_keys=True))
+            return 0
+        print_fitness(fit)
+        return 0
+    if "--counters" in flags:
+        import tezgah_integrity as ti
+        trend = "--trend" in flags
+        window = int(weeks) if weeks else ti.DRIFT_WEEKS
+        if "--all" in flags:
+            counts = ti.counters_all(weeks=trend, tools=trend)
+            head = "all %d ledgers (%d fixture ledgers left out)" % (counts["ledgers"], counts["fixtures"])
+        else:
+            # the id is the positional that is not a directory, so
+            # `SESSION_ID PATH` and `PATH SESSION_ID` both read it; PATH is ignored
+            ids = [p for p in pos if not os.path.isdir(p)]
+            session = ids[0] if ids else os.environ.get("TEZGAH_SESSION")
+            counts = ti.counters(session, weeks=trend, tools=trend)
+            head = "session %s" % (session or "(none)")
+        if "--json" in flags:
+            if trend:
+                # the reports are derived views of the same fold, so they ride
+                # beside it rather than recomputing anything
+                counts = dict(counts, never=ti.unfired_programs(counts),
+                              series=ti.drift_series(counts, window))
+            print(json.dumps(counts, sort_keys=True))
+            return 0
+        print("%s: %d events" % (head, counts["events"]))
+        for key in ("steps", "unanswered", "tool_error_rate", "claims", "false_completion",
+                    "shape_blocked", "denies", "nudges", "fanout", "consult",
+                    "codegen", "codegen_failed", "judge", "replies", "shape",
+                    "subagent_results", "subagent_bytes_p50",
+                    "subagent_bytes_max", "compactions", "compact_chars",
+                    "compact_constraint_rate"):
+            value = counts[key]
+            if key == "denies":
+                value = ", ".join("%s=%d" % kv for kv in sorted(value.items())) or "none"
+            print("  %-16s %s" % (key, value))
+            if key == "false_completion":
+                print("  %-16s %s" % ("blocked_claims", ", ".join(
+                    "%s=%d" % kv for kv in sorted(counts["blocked_claims"].items()))
+                    or "none"))
+            if key == "denies":
+                # per rule: re-issued/denied and the rate (decision-quality V3)
+                again = counts["denies_reissued"]
+                print("  %-16s %s" % ("denies_reissued", ", ".join(
+                    "%s=%d/%d %.4f" % (rule, again.get(rule, 0), n,
+                                       again.get(rule, 0) / n)
+                    for rule, n in sorted(counts["denies"].items())) or "none"))
+        print("  %-16s %s" % ("kinds", ", ".join(
+            "%s=%d" % kv for kv in sorted(counts["kinds"].items())) or "none"))
+        if trend:
+            print_trend(counts, window)
+        return 0
+    if "--failure-shapes" in flags:
+        # The fold is the shapes module's (tezgah_shapes.failure_shapes): it
+        # owns the corpus walk and the ranking, and a second copy here is the
+        # fork this CLI exists to avoid.
+        import tezgah_shapes as ts
+        found = ts.failure_shapes()
+        if "--json" in flags:
+            print(json.dumps(found, sort_keys=True))
+            return 0
+        print("%d ledgers: %d shapes recur in >= %d distinct sessions" % (
+            found["ledgers"], len(found["shapes"]),
+            found["recurring_sessions"]))
+        # Only when the corpus mixes contracts: a fold that read one version of
+        # the rows needs no line, and one that read pre-version rows beside
+        # current ones must say so - otherwise a shape that moved because the
+        # row's meaning changed reads as a rule that changed.
+        contracts = found.get("row_versions") or {}
+        if len(contracts) > 1 or "unversioned" in contracts:
+            print("  row contracts read: %s" % ", ".join(
+                "%s x%d" % (label, n) for label, n in sorted(contracts.items())))
+        for shape in found["shapes"]:
+            # fires-per-session rides every row: the count alone would rank the
+            # rule that fires on long turns above the one that recurs
+            print("  %6d sessions %6d fires %6.2f/session  %s" % (
+                shape["sessions"], shape["fires"],
+                shape["fires_per_session"], shape["rule"]))
+            for command in shape["commands"]:
+                print("           %s" % command)
+        return 0
+    if "--rule-yield" in flags:
+        # the fold and the ship dates are the shapes module's, like the flag above
+        import time
+        import tezgah_shapes as ts
+        found = ts.rule_yield()
+        if "--json" in flags:
+            print(json.dumps(found, sort_keys=True))
+            return 0
+        print("%d ledgers read (%d real, %d fixture left out): %d live gate "
+              "rules, %d retire candidates (<= %d fires over >= %d real ledgers)"
+              % (found["ledgers"], found["real"], found["fixtures"],
+                 len(found["rules"]),
+                 sum(r["mark"] == "retire-candidate" for r in found["rules"]),
+                 found["retire_fires"], found["min_exposure"]))
+        for row in found["rules"]:
+            since = (time.strftime("%Y-%m-%d", time.localtime(row["shipped"]))
+                     if row["shipped"] else "unknown")
+            print("  %-12s %6d fires %6s ledgers since %-10s  %s" % (
+                row["rule"], row["fires"],
+                "?" if row["exposure"] is None else row["exposure"],
+                since, row["mark"] or ""))
+        return 0
+    if "--enforcers" in flags:
+        print_enforcers("--json" in flags)
+        return 0
+    cwd = os.path.realpath(pos[0] if pos else os.getcwd())
+    session = pos[1] if len(pos) > 1 else os.environ.get("TEZGAH_SESSION")
+    spec = next((f.split("=", 1)[1] for f in flags
+                 if f.startswith("--observable=")), None)
+    observable = set(spec.split(",")) if spec else None
+    segs = health_segments(cwd, session, observable=observable)
+    if "--json" in flags:
+        print(json.dumps(segs))
+        return 0
+    color = "--color" in flags or (
+        "--no-color" not in flags and sys.stdout.isatty() and color_default())
+    line = render_line(segs, color=color)
+    if line:
+        print(line)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())