@r1z4x/tezgah 1.0.0

package/bin/tezgah-adhd

@@ -0,0 +1,50 @@
+#!/usr/bin/env python3
+"""tezgah-adhd [on|off] - arm or disarm the act-on-it output shape.
+
+The rule is armed by default. `off` writes the kill switch
+(~/.config/tezgah/adhd-off), which removes its paragraph from the injected text
+and turns its status mark red on every host; `on` removes the file again. A repo
+can opt out on its own with a `.no-adhd` mark, which this CLI does not touch:
+that decision belongs to the repo, not to a one-off command.
+
+The bare call is the query. Exit codes: 0 set or shown, 2 usage.
+"""
+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_paths import CONFIG_DIR, OFF_DIRS, off  # noqa: E402
+
+SWITCH = "adhd-off"
+USAGE = "usage: tezgah-adhd [on|off]"
+
+
+def main(argv):
+    if "-h" in argv or "--help" in argv:
+        print(__doc__.strip())
+        return 0
+    args = [a for a in argv if not a.startswith("-")]
+    if not args:
+        print("off" if off(SWITCH) else "on")
+        return 0
+    if len(args) != 1 or args[0].lower() not in ("on", "off"):
+        print("%s\narguments: on, off" % USAGE, file=sys.stderr)
+        return 2
+    if args[0].lower() == "off":
+        os.makedirs(CONFIG_DIR, exist_ok=True)
+        open(os.path.join(CONFIG_DIR, SWITCH), "w", encoding="utf-8").close()
+    else:
+        # every switch channel, so `on` really answers off() rather than leaving
+        # a legacy copy in ~/.claude that keeps the rule disarmed
+        for directory in OFF_DIRS:
+            try:
+                os.remove(os.path.join(directory, SWITCH))
+            except OSError:
+                pass
+    print("adhd rule: %s" % ("off" if off(SWITCH) else "on"))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

package/bin/tezgah-agents

@@ -0,0 +1,45 @@
+#!/usr/bin/env python3
+"""tezgah-agents [PATH]      generate/refresh this repo's tezgah subagent set.
+tezgah-agents --json [PATH] print the opencode `config.agent` entries as JSON.
+
+The hook hosts run the plain form from SessionStart via the shared context
+(tezgah_context calls tezgah_agents.sync_root). opencode has no such hook, so
+its plugin calls `--json` at config load (to arm the agents in the same session)
+and spawns the plain form on the first message (to write the files as a
+fallback). Same single Python source everywhere.
+"""
+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_agents import opencode_agents_json, sync_root  # noqa: E402
+from tezgah_context import repo_root, under  # noqa: E402
+
+
+def main():
+    args = sys.argv[1:]
+    # Without this, `--help` is taken as PATH: it resolves under the root and
+    # the run prints nothing at all instead of the usage in the docstring.
+    if "-h" in args or "--help" in args:
+        print(__doc__.strip())
+        return 0
+    as_json = "--json" in args
+    args = [a for a in args if a != "--json"]
+    cwd = os.path.realpath(args[0] if args else os.getcwd())
+    if not under(cwd):
+        print("{}" if as_json else "", end="")
+        return 0
+    repo = repo_root(cwd)
+    if as_json:
+        print(json.dumps(opencode_agents_json(repo)))
+        return 0
+    note = sync_root(repo)
+    if note:
+        print(note)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/bin/tezgah-capture

@@ -0,0 +1,66 @@
+#!/usr/bin/env python3
+"""tezgah-capture '<json>' - take a pre-write snapshot from outside Python.
+
+The one argument is the payload the gate hands tezgah_snapshot.capture, as a
+single JSON object:
+
+  tezgah-capture '{"tool": "Edit", "input": {"file_path": "a.py"},
+                   "cwd": "/repo/sub", "session_id": "abc"}'
+
+It prints the snapshot id, or nothing when there was nothing to capture (a new
+file, a tool that is not a write tool, a path that is not a readable regular
+file). Exit codes: 0 captured or nothing to capture, 2 misuse - no argument,
+unparseable or non-object JSON, or no session_id, which is required because a
+capture with no session writes no ledger row and the id could not be found
+again.
+
+This exists for opencode, whose plugin is JavaScript and can only reach the
+gate's Python through a process; every other host calls capture() in-process.
+It is not called by any hook, and it never restores anything: rollback is
+`bin/tezgah-rollback`, run by the user.
+"""
+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_guard import import_failed  # noqa: E402
+try:
+    from tezgah_snapshot import capture  # noqa: E402
+except Exception as exc:
+    import_failed(exc)
+
+USAGE = ('usage: tezgah-capture \'{"tool": "Edit", "input": {"file_path": "a.py"},'
+         ' "cwd": "/repo", "session_id": "abc"}\'')
+
+
+def main(argv):
+    if len(argv) != 1 or not argv[0].strip():
+        print(USAGE, file=sys.stderr)
+        return 2
+    try:
+        payload = json.loads(argv[0])
+    except ValueError as exc:
+        print("tezgah-capture: the argument is not JSON (%s)\n%s" % (exc, USAGE),
+              file=sys.stderr)
+        return 2
+    if not isinstance(payload, dict):
+        print("tezgah-capture: the argument is not a JSON object\n%s" % USAGE,
+              file=sys.stderr)
+        return 2
+    session = str(payload.get("session_id") or "")
+    if not session:
+        print("tezgah-capture: no session_id; without one the snapshot would be "
+              "written to no ledger and its id could not be looked up\n%s" % USAGE,
+              file=sys.stderr)
+        return 2
+    sid = capture(str(payload.get("tool") or ""), payload.get("input") or {},
+                  str(payload.get("cwd") or os.getcwd()), session)
+    if sid:
+        print(sid)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

package/bin/tezgah-context

@@ -0,0 +1,96 @@
+#!/usr/bin/env python3
+"""tezgah-context EVENT [DIR] - the shared context text, for a non-Python host.
+
+Prints what hooks/tezgah_context.context_for() builds for one normalized event,
+so a host whose plugin is written in another language (opencode's tezgah.js)
+gets the same text every Python adapter gets instead of a hand-kept paraphrase
+that drifts from it. The host's own hook payload may be piped in on stdin as
+JSON - `user_prompt` reads the submitted prompt from it.
+
+  tezgah-context session_start [DIR]    the session brief
+  tezgah-context user_prompt [DIR]      the per-turn reminder plus whichever
+                                        conditional rule this prompt arms
+                                        (stdin: {"prompt": "<submitted text>"})
+  tezgah-context subagent_start [DIR]   the short brief for a delegated agent
+  tezgah-context post_compact [DIR]     what a host re-injects after compaction
+  tezgah-context kind 'CMD'             which tool a shell command really ran
+                                        (consult / research / judge / nothing):
+                                        a host whose plugin is not Python asks
+                                        here instead of guessing from a
+                                        substring
+  tezgah-context attest HOST SESSION [DIR]
+                                        the session-start attestation for a
+                                        host with no session-start hook
+                                        (opencode): one `attest` row and the
+                                        drift mark, nothing printed
+
+DIR defaults to the current directory. Prints nothing outside a tezgah root, so
+the host injects whatever it gets and a stale path costs nothing.
+"""
+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_guard import attest_session, import_failed  # noqa: E402
+try:
+    from tezgah_context import context_for, shell_kind  # noqa: E402
+except Exception as exc:
+    import_failed(exc)
+
+EVENTS = ("session_start", "user_prompt", "subagent_start", "post_compact")
+
+
+def stdin_payload():
+    """The host payload on stdin, or {} when there is none or it is malformed."""
+    if sys.stdin is None or sys.stdin.isatty():
+        return {}
+    try:
+        data = json.load(sys.stdin)
+    except Exception:
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def main():
+    args = sys.argv[1:]
+    if args and args[0] in ("-h", "--help"):
+        sys.stdout.write(__doc__.strip() + "\n")
+        return 0
+    if not args:
+        sys.stderr.write("tezgah-context: event required (%s, kind)\n"
+                         % ", ".join(EVENTS))
+        return 2
+    event = args[0]
+    if event == "attest":
+        if len(args) < 3:
+            sys.stderr.write("tezgah-context: attest needs HOST SESSION [DIR]\n")
+            return 2
+        cwd = os.path.realpath(args[3]) if len(args) > 3 else os.getcwd()
+        attest_session(args[1], args[2], cwd)
+        return 0
+    if event == "kind":
+        # The used-tool kind of one shell command. A host whose plugin is in
+        # another language asks here rather than guessing: nothing printed means
+        # the command did not run the tool.
+        if len(args) < 2:
+            sys.stderr.write("tezgah-context: kind needs a command\n")
+            return 2
+        kind = shell_kind(args[1])
+        if kind:
+            sys.stdout.write(kind + "\n")
+        return 0
+    if event not in EVENTS:
+        sys.stderr.write("tezgah-context: unknown event %s (%s)\n"
+                         % (event, ", ".join(EVENTS)))
+        return 2
+    cwd = os.path.realpath(args[1]) if len(args) > 1 else os.getcwd()
+    text = context_for(event, cwd, stdin_payload())
+    if text:
+        sys.stdout.write(text + "\n")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/bin/tezgah-decisions

@@ -0,0 +1,213 @@
+#!/usr/bin/env python3
+"""tezgah-decisions [check] [PATH] [--json] - the ADR record under `.tezgah/decisions/`.
+
+A capability change owes an ADR: `skills/feature-audit/SKILL.md` asks a proposal
+for "the ADR (context, decision, status, consequences) and what it supersedes",
+hands the consult rule the word `adrs?|architecture decision record|design doc`,
+and names "an ADR without a status" as the thing that must fail. Until this CLI
+the repository asked for that record and gave it nowhere to live, no status
+vocabulary and nothing that read it back.
+
+A record is `.tezgah/decisions/NNN-slug.md` in the private `.tezgah` repository
+(beside `plans/` and `research/`), written and committed the way plan-add writes
+a plan: one significant decision per file - hard to reverse, spanning
+components, or explained for a second time:
+
+    ---
+    id: 001
+    title: Decisions are recorded as numbered ADRs
+    status: accepted        # proposed | accepted | deprecated | superseded
+    date: 2026-09-30
+    supersedes:             # the id (a file's NNN) this record replaces, else empty
+    ---
+    ## Context
+    <two to four sentences naming the constraints>
+    ## Decision
+    <the decision, active voice>
+    ## Consequences
+    <what gets easier, what gets harder, what new constraint appears>
+
+  tezgah-decisions            check every record, listing what it read
+  tezgah-decisions check PATH the same for the repository at PATH (default: cwd)
+  tezgah-decisions --json     the records and the problems as JSON
+  tezgah-decisions --help     this text
+
+A record's id is its file name's `NNN`: one record, one address, so a
+`supersedes:` target and the file it names cannot disagree.
+
+The checker refuses three things and only these: a record with no `status:`, a
+status outside the four above, and a `supersedes:` naming no record in the
+directory. A file that is not `NNN-slug.md` is not a record and is not read -
+the count it prints is how a misplaced one shows up.
+
+Exit codes: 0 every record is whole (or there are none), 1 a record was refused
+(one `FAIL <path>: <what>` line each), 2 misuse.
+"""
+import json
+import os
+import re
+import subprocess
+import sys
+
+HERE = os.path.dirname(os.path.dirname(os.path.realpath(__file__)))
+sys.path.insert(0, os.path.join(HERE, "hooks"))
+import tezgah_task as tt  # noqa: E402
+
+# Nygard's four states and the whole vocabulary: a status outside them is refused
+# rather than printed, because "an ADR without a status" is the falsifier the
+# feature-audit skill names and an undefined fifth state is that hole reworded.
+STATUSES = ("proposed", "accepted", "deprecated", "superseded")
+
+# The prose half of a record, in the order it is written.
+SECTIONS = ("Context", "Decision", "Consequences")
+
+# A record's file name: the three-digit id a `supersedes:` points at, then its
+# slug. Anything else in the directory is not a record.
+RECORD = re.compile(r"^(\d{3})-[^/]+\.md$")
+
+
+def repo_root(path):
+    """The repository this run is about: git's own answer, else the directory the
+    CLI was called in - a decision recorded under a tree git does not know is
+    still a decision. Resolved here the way bin/tezgah-task resolves its root,
+    because the two CLIs have to agree on which repository they are talking
+    about."""
+    try:
+        out = subprocess.run(["git", "-C", path, "rev-parse", "--show-toplevel"],
+                             capture_output=True, text=True)
+        if out.returncode == 0 and out.stdout.strip():
+            return out.stdout.strip()
+    except OSError:
+        pass
+    return os.path.realpath(path)
+
+
+def decision_record(text):
+    """One record as a dict: its `key: value` frontmatter (id, title, status,
+    date, supersedes, "" for a key the file does not carry) plus its three prose
+    sections, each flattened to one line the way acceptance_items() flattens an
+    item.
+
+    Read through hooks/tezgah_task.py's frontmatter and section_lines, so a plan
+    and a record cannot disagree about what a `key: value` line or a `## Section`
+    is - the reader a plan is refused by is the reader a record is refused by."""
+    fields = tt.frontmatter(text)
+    record = dict((key, fields.get(key, "")) for key in
+                  ("id", "title", "status", "date", "supersedes"))
+    for name in SECTIONS:
+        record[name.lower()] = " ".join(
+            line.strip() for _, line in tt.section_lines(text, name) if line.strip())
+    return record
+
+
+def problems(record, ids, where):
+    """The problems this one record has, [] when it is whole. `ids` is every id
+    the directory carries, so a `supersedes:` that names nothing is a broken
+    chain and not a typo no reader can see; `where` is its path relative to the
+    repository, so a `FAIL` line can be acted on."""
+    bad = []
+    status = record["status"]
+    if not status:
+        bad.append("%s: no `status:` - an ADR carries one of %s"
+                   % (where, ", ".join(STATUSES)))
+    elif status not in STATUSES:
+        bad.append("%s: status %r is not one of %s"
+                   % (where, status, ", ".join(STATUSES)))
+    # ponytail: supersedes is read as one or more whitespace-separated ids; a
+    # comma-separated list would read `001,` as an id no record carries, and that
+    # failure says which name is wrong, so it is left to the filer.
+    for target in record["supersedes"].split():
+        if target not in ids:
+            bad.append("%s: `supersedes: %s` names no record under .tezgah/decisions/"
+                       % (where, target))
+    # ponytail: the three refusals are the contract the gap row set. A record
+    # whose prose sections are empty is read and printed, not refused - a fourth
+    # rule is one the feature-audit skill never asked for.
+    return bad
+
+
+def records_report(root):
+    """Every record under `<root>/.tezgah/decisions/`:
+    {"records": how many files were read, "entries": [record ...], "problems":
+    ["<path>: <what>" ...]}, each entry carrying decision_record()'s keys plus
+    "id" (its file name's NNN, overriding a frontmatter `id:` that disagrees) and
+    "path".
+
+    Two passes and not one: a `supersedes:` is answered against every id the
+    directory carries, and one the record replaced is usually read before the
+    record that replaces it. Never raises - an absent directory or an unreadable
+    file is skipped, not refused: this feeds a report, not a gate."""
+    directory = os.path.join(root, ".tezgah", "decisions")
+    try:
+        names = sorted(n for n in os.listdir(directory) if RECORD.match(n))
+    except OSError:
+        names = []
+    entries = []
+    for name in names:
+        path = os.path.join(directory, name)
+        try:
+            with open(path, "r", encoding="utf-8") as fh:
+                text = fh.read()
+        except OSError:
+            continue
+        record = decision_record(text)
+        record["id"] = RECORD.match(name).group(1)
+        record["path"] = os.path.relpath(path, root).replace(os.sep, "/")
+        entries.append(record)
+    ids = set(entry["id"] for entry in entries)
+    found = []
+    for record in entries:
+        found += problems(record, ids, record["path"])
+    return {"records": len(entries), "entries": entries, "problems": found}
+
+
+def misuse(message):
+    """Misuse exits 2, so a caller can tell it from a record that refuses."""
+    print("tezgah-decisions: %s" % message, file=sys.stderr)
+    return 2
+
+
+def show(report, root, as_json):
+    if as_json:
+        print(json.dumps({"root": root, "records": report["records"],
+                          "entries": report["entries"],
+                          "problems": report["problems"]},
+                         indent=2, sort_keys=True))
+        return 1 if report["problems"] else 0
+    # the count is half the answer: a run that read nothing must not read as
+    # "every record is whole"
+    print("decisions under %s: %d record(s)"
+          % (os.path.join(root, ".tezgah", "decisions"), report["records"]))
+    for entry in report["entries"]:
+        print("  %s  %-11s %s" % (entry["id"], entry["status"] or "(no status)",
+                                  entry["title"]))
+    for problem in report["problems"]:
+        print("FAIL %s" % problem)
+    return 1 if report["problems"] else 0
+
+
+def main(argv):
+    args = argv[1:]
+    flags = set(a for a in args if a.startswith("--"))
+    pos = [a for a in args if not a.startswith("--")]
+    unknown = sorted(f for f in flags if f not in ("--json", "--help"))
+    if unknown:
+        return misuse("unknown option(s): %s (try --help)" % ", ".join(unknown))
+    if "--help" in flags:
+        sys.stdout.write(__doc__.strip() + "\n")
+        return 0
+    cmd = pos[0] if pos else "check"
+    if cmd != "check":
+        return misuse("unknown command %r (check)" % cmd)
+    if len(pos) > 2:
+        return misuse("check takes one path, not %s" % ", ".join(pos[1:]))
+    root = repo_root(pos[1] if len(pos) > 1 else os.getcwd())
+    if not os.path.isdir(root):
+        return show({"records": 0, "entries": [],
+                     "problems": ["%s: no such directory" % root]},
+                    root, "--json" in flags)
+    return show(records_report(root), root, "--json" in flags)
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv))