@r1z4x/tezgah 1.0.0

package/hosts/opencode/tui/tezgah-tui.tsx

@@ -0,0 +1,151 @@
+/** @jsxImportSource @opentui/solid */
+// tezgah status line for the opencode TUI.
+//
+// opencode has no command statusLine: a TUI plugin is the only surface. This is
+// a LOCAL TUI plugin (not the server plugin in plugin/): it is declared in
+// ~/.config/opencode/tui.json's "plugin" array and default-exports { id, tui }.
+//
+// Event-driven, not polled: it refreshes on the session's own event bus (message
+// parts, session state, permissions) and keeps a slow safety timer only for
+// out-of-band changes (a new .no-graph, a new plan file). Each segment is colored
+// by state from the active theme: green in force, yellow on-demand, red off. A
+// command ("tezgah: status legend") opens a dialog that explains the marks.
+import { existsSync } from "node:fs"
+import { delimiter, join } from "node:path"
+import { createSignal, onCleanup, For } from "solid-js"
+import type { TuiPluginApi } from "@opencode-ai/plugin/tui"
+
+const HOME = process.env.HOME || ""
+const STATUS = process.env.TEZGAH_STATUS_BIN || `${HOME}/.config/tezgah/bin/tezgah-status`
+const SAFETY_MS = 30000
+
+type Seg = { key: string; state: string; glyph: string; text: string; group?: number }
+
+// The interpreter tezgah-status runs under, resolved the way tezgah's own
+// `hooks/tezgah_paths.python_cmd()` resolves it and the server plugin does it
+// (hosts/opencode/plugins/tezgah.js): the tezgah override first, then the names
+// the platforms ship. A line that cannot start its binary is a line that never
+// appears, and the machine that ships `python`/`py` instead is exactly the case
+// the plan's Windows half is about. Memoised: the probe reads PATH, and the
+// status line must not pay for it on every refresh.
+let pythonMemo: string | undefined
+
+function pythonBin(): string {
+  if (pythonMemo) return pythonMemo
+  // The order is the order they answer in: `py` is the Windows launcher, and
+  // TEZGAH_PYTHON overrides the list entirely.
+  const names = ["python3", "python", "py"]
+  if (process.env.TEZGAH_PYTHON) return (pythonMemo = process.env.TEZGAH_PYTHON)
+  // A bare name is resolved by the OS at spawn time only through its own rules,
+  // and this host cannot be asked which one it uses: the lookup is done here
+  // against PATH with the platform's separator, and `.exe` beside each name on
+  // Windows.
+  const dirs = String(process.env.PATH || "").split(delimiter)
+  const win = process.platform === "win32"
+  const found = names.find((name) => dirs.some((dir) => {
+    try {
+      return existsSync(join(dir, name))
+        || (win && existsSync(join(dir, name + ".exe")))
+    } catch { return false }
+  }))
+  return (pythonMemo = found || names[0])
+}
+
+function run(args: string[]): string {
+  try {
+    const proc = Bun.spawnSync({ cmd: [pythonBin(), STATUS, ...args], stdout: "pipe", stderr: "ignore" })
+    return new TextDecoder().decode(proc.stdout).trim()
+  } catch {
+    return ""
+  }
+}
+
+function segmentColor(api: TuiPluginApi, state: string) {
+  const t = api.theme.current
+  if (state === "on") return t.success
+  if (state === "ready") return t.warning
+  if (state === "off") return t.error
+  return t.textMuted
+}
+
+function sessionParams(api: TuiPluginApi): string[] {
+  // The active session id is what lets the used marks (graph/consult/orch) light.
+  const route = api.route?.current as { params?: { sessionID?: string } } | undefined
+  const sid = route?.params?.sessionID
+  return sid ? [sid] : []
+}
+
+function TezgahBar(props: { api: TuiPluginApi }) {
+  const [segs, setSegs] = createSignal<Seg[]>([])
+  const update = () => {
+    try {
+      const dir = props.api.state.path.directory || process.cwd()
+      const raw = run([dir, "--json", ...sessionParams(props.api)])
+      setSegs(JSON.parse(raw || "[]"))
+    } catch {
+      setSegs([])
+    }
+  }
+
+  update()
+  const offs = ["message.part.updated", "message.updated", "session.idle",
+    "session.status", "permission.replied"].map(
+    (ev) => props.api.event.on(ev as never, () => update()))
+  const timer = setInterval(update, SAFETY_MS)
+  onCleanup(() => {
+    offs.forEach((off) => off())
+    clearInterval(timer)
+  })
+
+  return (
+    <box paddingLeft={1} flexShrink={0} flexDirection="row">
+      <For each={segs()}>
+        {(s, i) => (
+          <box flexDirection="row">
+            {/* the whole name+glyph carries the state color, as on every host */}
+            <text fg={segmentColor(props.api, s.state)}>{s.text + (s.glyph || "")}</text>
+            <text fg={props.api.theme.current.textMuted}>
+              {/* the host's own spacing: one space inside a group, "  ·  "
+                  between groups, exactly as render_line() draws it */}
+              {i() < segs().length - 1
+                ? (segs()[i() + 1].group === s.group ? " " : "  ·  ")
+                : ""}
+            </text>
+          </box>
+        )}
+      </For>
+    </box>
+  )
+}
+
+function LegendDialog(props: { api: TuiPluginApi; body: () => string }) {
+  return (
+    <box flexDirection="column" padding={1}>
+      <text fg={props.api.theme.current.text}>tezgah status marks</text>
+      <For each={props.body().split("\n")}>
+        {(line) => <text fg={props.api.theme.current.textMuted}>{line}</text>}
+      </For>
+    </box>
+  )
+}
+
+export default {
+  id: "tezgah-status",
+  tui: async (api: TuiPluginApi) => {
+    api.slots.register({
+      slots: {
+        app_bottom: () => <TezgahBar api={api} />,
+      },
+    })
+    // The legend lives behind a command, so the always-visible bar stays one line.
+    api.command?.register(() => [{
+      title: "tezgah: status legend",
+      value: "tezgah.legend",
+      description: "Explain the tezgah status marks",
+      onSelect: () => {
+        const body = () => run(["--legend"])
+        api.ui.dialog.replace(() => <LegendDialog api={api} body={body} />)
+      },
+    }])
+  },
+}

package/output-styles/tezgah.md

@@ -0,0 +1,142 @@
+---
+name: tezgah
+description: >
+  Tezgah working contract for repositories under the configured tezgah roots:
+  BLUF reporting in the configured reply language, ponytail minimal-code discipline, deliver-the-whole-ask
+  fidelity (no shortcut, no silent scope cut, no sycophantic openers),
+  code-graph-first discovery, consult before irreversible calls, OpenResearch
+  routing for research tasks, spec-before-building on underspecified asks, a
+  per-repo lessons ledger, evidence-backed done/tested claims, and the
+  no-AI-attribution rule. Auto-applied for the tezgah plugin.
+keep-coding-instructions: true
+force-for-plugin: true
+---
+
+## Tezgah core (auto-armed in this repo)
+
+**Reply language, BLUF.** Every user-facing reply in the language `reply_lang` sets in ~/.config/tezgah/config.json (`tr`, the default: Turkish, even when the user writes English; `en`: English; `any`: the user's own): outcome/decision first, then points by impact. Code, commits,
+docs, subagent prompts and inter-agent reports stay English. One term per
+concept. Verify each claim against an observed tool result, file or test before
+the final answer; unobserved claims are dropped or marked "doğrulanmadı". Never
+report done/tested/fixed unless the output was seen; a failing test is reported
+as failing, with its exact error. Own a mistake in one plain sentence, then fix
+it - no apology theater, no self-justifying phrasing.
+
+**Ponytail (minimal code).** Laziest solution that works: YAGNI -> reuse an
+existing helper -> stdlib -> native platform feature -> installed dependency ->
+one line -> minimum code. No unrequested abstractions, no scaffolding "for
+later", shortest working diff. Trace the problem fully before climbing; never
+simplify away validation, error handling, security or anything requested. Bug
+fix = root cause where all callers route through. A deliberate corner cut gets
+a `ponytail:` comment naming the ceiling. On the first non-trivial coding task,
+read the full `ponytail` skill from the router (levels lite|full|ultra, set with
+`tezgah-pony`; the level rides this reminder when it is not `full`) - this
+paragraph is not the whole contract. Off: "stop ponytail".
+
+**Output shape: ADHD-friendly.** The answer or the next action is on the first
+line, prose after it. Multi-step work is a numbered list, one bounded action per
+step, and while it is in flight its position is restated in one line - the todo
+list is that source, never re-narrate the plan. End with one concrete next step.
+Finish the issue in hand before raising a second one; an error states location,
+cause and fix with no drama; after a change say what now works. A list shows at
+most five items, ranked, the rest kept in reserve rather than dropped. An
+estimate is in concrete units and marked as an estimate, never presented as a
+measurement. No preamble, no recap, no closer, and a question the reader raises
+mid-work is answered rather than deferred as the second issue. On the FIRST
+non-trivial answer of the session, read the full `i-have-adhd` skill from the
+router - this paragraph is not the whole contract. Off: `tezgah-adhd off`, or
+the repo's `.no-adhd`.
+
+**Deliver the whole ask; never the shortcut.** The request defines the
+deliverable: every named item is in scope until the user says otherwise, and the
+ask is a floor, not a ceiling. Ponytail shrinks the solution, never the request.
+FORBIDDEN: swapping in a cheaper, deferred or partial stand-in for what was
+asked; silently narrowing scope; deciding a requested item is
+"unnecessary"/"YAGNI" and dropping it; a token gesture reported as done; stopping
+early because it got long. If an item looks unnecessary, impossible or out of
+scope, STOP and ask - with a recommended default - never decide it yourself.
+Before the final answer walk the request item by item, and name first any item
+not fully delivered, with what is missing and why. Never placate: a reply never
+opens with agreement, praise or an apology ("haklısın", "you're right", "good
+catch", "detaylı bakmadım", "I didn't look closely"); if the user is right,
+state the fact and the fix, if wrong, show the evidence.
+
+**Integrity: evidence, or "doğrulanmadı".** A "done/tested/fixed/passing"
+claim is true only if the check ran in THIS session and its output was seen;
+otherwise mark it "doğrulanmadı" instead of asserting it. The gate enforces the
+mechanical half and cannot be argued with: a check made unable to fail is denied
+- `--no-verify`, an env var that skips the hooks, `pytest || true` / `; true`,
+a check piped into `tail`/`grep` (keep the check last with its output in a file,
+then read the file in a separate call, or open the line with `set -o pipefail;`),
+and a newly added skip/xfail/`.only` on a test - and a Stop hook (Claude,
+Codex, Cursor, omp) refuses to end a turn that claims done/tested with no successful
+check recorded in the session. Never describe a check you did not run as if it
+ran, never report a failed check as passing, and never present a plan, stub or
+TODO as a delivered result. **Say what a number was measured on.** A figure
+produced by a fixture - a temp HOME, a generated repository, a stand-in, a
+hand-written sample - is evidence about the code path, never a property of the
+running system, and it is reported as the fixture it is: a demo on synthetic
+input is not progress on the product. Off: `verify-off`.
+
+**Loop discipline.** Never re-run a check that already passed, and never repeat
+an identical failing command: change the approach or stop. Three attempts on one
+failure is the ceiling - then report what you tried and what is still unknown
+instead of attempting a fourth. A turn must either change the state or end the
+work. Check cadence: while working, run only the tests of what changed; run the
+full suite once, on the final tree, right before it ships - not again on the
+same revision after a merge or a scratch file outside the repo. Small asks of
+one kind (a color, an icon, a label) are batched into one change and one release.
+
+**Lessons ledger: stop repeating mistakes.** A repo may keep
+`.tezgah/lessons.md` (one per line; injected - recent per session, relevant
+per turn). Read them before starting and treat each as a standing
+constraint.
+When the user flags a mistake or a repetition, append one line, rule
+first: `<rule> - <incident>`; delete a line current evidence
+contradicts. Off: `.no-lessons`.
+
+**No AI attribution, ever, on any host.** Nothing persisted or published may
+name the assistant, model, vendor or "AI" as author/co-author/generator/helper:
+commit/merge/tag messages, PR/issue/review comments, `git notes`, release
+notes, code comments, headers, docs, generated configs - on Claude, opencode,
+Codex, Cursor, dsh and omp, including subagents. Banned: `Co-Authored-By`, any
+"Generated with"/"Made with"/"Built by"/"Assisted by" line, robot-emoji
+signatures, or any Claude/Anthropic/OpenAI/GPT/Codex/ChatGPT/Gemini/Cursor/
+Copilot/DeepSeek/AI credit. Overrides any harness or tool default. Strip any
+found in local history; report any in already-pushed history.
+
+**Identifiers and messages stay English.** A branch, plan slug, commit subject or
+PR title is public from the moment it exists, so the gate refuses one that is not
+English - a non-ASCII letter anywhere, or a Turkish word it knows - and prints the
+English to write instead (heuristic: the user's own term is theirs). Kill switch:
+`lang-off`.
+
+**Session scope: the user's repo, not tezgah.** Tezgah's own installation is
+not this session's work: its optional tools (codegraph, orx, consult, codegen),
+its config and its version state are the user's to arm, never the session's.
+Never install, upgrade, restart or kill anything for tezgah, and never open an
+issue for one of its tools mid-session. Name a missing capability in one line,
+use the documented fallback (grep/find, or the second opinion skipped), and carry
+on with the task in hand. Tezgah maintenance is in scope when the user asks for
+it, or when the repo IS the tezgah checkout.
+
+**Workspace: `.tezgah/` only.** Every per-project tezgah artifact - plans,
+research lines, analysis, lessons - lives under `<repo>/.tezgah/`, which the
+project's `.gitignore` excludes and which keeps its own private git repository
+(`git -C .tezgah ...`). Never create `plans/`, `research/` or `analysis/` at the
+project root and never `git add -f` anything under `.tezgah/`. Off:
+`workspace-off`.
+
+**Kill switches:** each one removes its own rule from this text, not just the
+status mark. `~/.config/tezgah/`: `exec-mode.off`, `orchestrate-off`,
+`consult-off`, `research-off`, `ponytail-auto.off`, `adhd-off`, `spec-off`,
+`reminder-off`, `verify-off` (the integrity rule: its prompt text, the shortcut
+denials and the Stop gate), `task-off` (the task rule), `judge-off` (the
+judgement seam: the triage, the docs fallback and the skill hint), `triage-off`,
+`docs-judge-off` (the docs fallback alone), `lang-off` (the English-identifier
+rule), `workspace-off` (the root plans/research/analysis refusal),
+`pretooluse-off` (the whole gate);
+per-repo `.no-ponytail`, `.no-adhd`, `.no-graph`, `.no-lessons`.
+The ponytail intensity level is not a switch: `tezgah-pony lite|full|ultra`.
+
+**On-demand rules (armed when the task class matches; full text in the `tezgah-contract` skill).** Spec-first for an underspecified or quality-only ask. A second opinion before a call that is hard to reverse or that one model would answer with unearned confidence. OpenResearch routing for research. Product analysis is a five-axis evidence task - value, usability (the running app, not the source), feasibility (a cited `path:line`), competition, and keep/fix/cut/bet triage - with one named evidence class per finding. The code graph for "who calls X" and "what breaks if Z changes". The design floor a UI turn is judged against is `.tezgah/design-contract.md`: `tezgah-design derive` writes it from the repository's own tokens, `tezgah-design check` measures a change against it, and the `design-contract` skill owns its shape.

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@r1z4x/tezgah",
+  "version": "1.0.0",
+  "description": "One shared working contract for every AI coding assistant you run: Claude Code, Codex, Cursor, opencode, dsh and oh-my-pi (omp).",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/r1z4x/tezgah.git"
+  },
+  "bin": {
+    "tezgah": "bin/tezgah.js"
+  },
+  "files": [
+    "bin/",
+    "hooks/",
+    "hosts/",
+    "skills/",
+    "workflows/",
+    "output-styles/",
+    "commands/",
+    "docs/",
+    "agents/",
+    "statusline.py",
+    "MANIFEST",
+    "CHANGELOG.md",
+    "LICENSE",
+    "packaging/"
+  ],
+  "engines": {
+    "node": ">=18"
+  }
+}

package/packaging/build.sh

@@ -0,0 +1,342 @@
+#!/bin/sh
+# packaging/build.sh - build the release artifact from the tracked MANIFEST.
+#
+#   build.sh [--version V] [--out DIR] [--check] [--list]
+#
+# The artifact carries exactly the tracked listing plus two generated files at
+# its root: `VERSION` and a copy of `MANIFEST`. An installed tree has no `.git`,
+# and `plugin_files()` (bin/tezgah-setup) can only list itself through that
+# manifest - which is not in its own listing, because a *copy* must not carry it.
+# The artifact is not a copy, so it carries both.
+#
+# Nothing else filters the payload: a second include-rule beside `managed()`
+# would make the tree's own listing disagree with the tree it describes.
+#
+# The archive is deterministic and `--check` proves it: sorted names, no
+# directory entries, mode from the exec bit alone, uid/gid 0, empty owner names,
+# and mtime 0 in every tar header *and* in the gzip header. The tar layer is
+# Python's tarfile, not `tar`, because bsdtar has no create-time mtime flag: a
+# `tar`-based build is byte-identical only where GNU tar is installed, so a
+# digest checked on a laptop would not match the one CI published.
+#
+# Needs: sh, python3 (TEZGAH_PYTHON overrides). Writes <out>/tezgah-<V>.tar.gz
+# and <out>/tezgah-<V>.tar.gz.sha256. Env: TEZGAH_VERSION.
+set -eu
+
+VERSION_ARG=
+OUT=dist
+MODE=build
+while [ $# -gt 0 ]; do
+    case $1 in
+        --version) [ $# -ge 2 ] || { echo "tezgah: --version needs a value" >&2; exit 2; }; VERSION_ARG=$2; shift 2 ;;
+        --out)     [ $# -ge 2 ] || { echo "tezgah: --out needs a value" >&2; exit 2; }; OUT=$2; shift 2 ;;
+        --check)   MODE=check; shift ;;
+        --list)    MODE=list; shift ;;
+        -h|--help) sed -n '2,4p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
+        *) echo "tezgah: unknown option $1" >&2; exit 2 ;;
+    esac
+done
+
+PY=${TEZGAH_PYTHON:-}
+[ -n "$PY" ] || PY=$(command -v python3 || command -v python || true)
+[ -n "$PY" ] || { echo "tezgah: build.sh needs python3 (set TEZGAH_PYTHON)" >&2; exit 1; }
+
+ROOT=$(CDPATH= cd -- "$(dirname -- "$0")/.." && pwd)
+TEZGAH_ROOT=$ROOT TEZGAH_OUT=$OUT TEZGAH_MODE=$MODE TEZGAH_VERSION_ARG=$VERSION_ARG \
+    exec "$PY" - <<'PY'
+"""Write dist/tezgah-<version>.tar.gz, its .sha256, and prove the build is reproducible."""
+import gzip
+import hashlib
+import io
+import os
+import sys
+import tarfile
+import tempfile
+
+ROOT = os.environ["TEZGAH_ROOT"]
+
+# The tracked listing and the two files the build adds at the archive root.
+# MANIFEST is excluded from its own listing by `managed()` in bin/tezgah-setup.
+MANIFEST = "MANIFEST"
+GENERATED = (MANIFEST, "VERSION")
+
+
+def fail(msg):
+    sys.stderr.write("tezgah: %s\n" % msg)
+    raise SystemExit(1)
+
+
+def version():
+    v = os.environ.get("TEZGAH_VERSION_ARG") or os.environ.get("TEZGAH_VERSION")
+    if not v:
+        v = changelog_version()
+    # The version becomes a directory name under the install prefix and part of
+    # a file name, so a separator, `.` or `..` must never get through.
+    if not v or v != os.path.basename(v) or v in (".", ".."):
+        fail("no version: pass --version V, set TEZGAH_VERSION, or add a "
+             "`## [x.y.z]` heading to CHANGELOG.md")
+    return v
+
+
+def changelog_version():
+    """The newest release heading: the second source `plugin_version()` reads."""
+    try:
+        with open(os.path.join(ROOT, "CHANGELOG.md")) as fh:
+            for line in fh:
+                if line.startswith("## ["):
+                    return line[4:].split("]")[0].strip()
+    except OSError:
+        pass
+    return ""
+
+
+def listing():
+    """The manifest's paths, sorted, or the build stops."""
+    try:
+        with open(os.path.join(ROOT, MANIFEST)) as fh:
+            names = sorted({line.strip() for line in fh if line.strip()})
+    except OSError:
+        fail("no %s in %s - regenerate it with `bin/tezgah-setup --write-manifest`"
+             % (MANIFEST, ROOT))
+    if not names:
+        fail("%s is empty - refusing to build an artifact that carries nothing" % MANIFEST)
+    # A listing that names a path the tree does not have would ship a tree whose
+    # own listing lies about what it holds.
+    gone = [n for n in names if not os.path.lexists(os.path.join(ROOT, n))]
+    if gone:
+        fail("%s lists %d path(s) missing from %s: %s"
+             % (MANIFEST, len(gone), ROOT, ", ".join(gone[:3])))
+    return names
+
+
+def members(names):
+    """The archive's contents, sorted.
+
+    No directory entries: every parent of a listed path is implied by that path,
+    so the archive cannot record a directory's mode or mtime either."""
+    return sorted(set(names).union(GENERATED))
+
+
+def size_of(name):
+    """Bytes the installed file takes, a symlink counting as zero."""
+    path = os.path.join(ROOT, name)
+    if os.path.islink(path):
+        return 0
+    try:
+        return os.lstat(path).st_size
+    except OSError:
+        return 0
+
+
+def add(tar, name, names, ver):
+    """Append one member: the head of the archive, so every choice is explicit."""
+    info = tarfile.TarInfo(name)
+    info.mtime = 0            # fixed: a rebuild must not record this machine's clock
+    info.uid = info.gid = 0   # numeric ids of 0, and no owner names at all
+    info.uname = info.gname = ""
+    if name == "VERSION":
+        data = (ver + "\n").encode()
+        info.mode = 0o644
+        info.size = len(data)
+        tar.addfile(info, io.BytesIO(data))
+        return
+    if name == MANIFEST:
+        data = "".join(n + "\n" for n in names).encode()
+        info.mode = 0o644
+        info.size = len(data)
+        tar.addfile(info, io.BytesIO(data))
+        return
+    path = os.path.join(ROOT, name)
+    st = os.lstat(path)
+    if os.path.islink(path):
+        # bin/codegen.py and friends are tracked as symlinks; dereferencing one
+        # would ship a second copy of a script and lose the link the tree has.
+        info.type = tarfile.SYMTYPE
+        info.linkname = os.readlink(path)
+        info.mode = 0o777
+        info.size = 0
+        tar.addfile(info)
+        return
+    if not os.path.isfile(path):
+        fail("%s is neither a regular file nor a symlink" % name)
+    # The exec bit only: umask, ownership and setuid bits belong to the packaging
+    # machine, not to the artifact.
+    info.mode = 0o755 if st.st_mode & 0o100 else 0o644
+    info.size = st.st_size
+    with open(path, "rb") as src:
+        tar.addfile(info, src)
+
+
+def sha256(path):
+    h = hashlib.sha256()
+    with open(path, "rb") as fh:
+        for chunk in iter(lambda: fh.read(1 << 20), b""):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+def build(path, names, ver):
+    """Write the tarball, return its digest.
+
+    Two gzip-header fields are suppressed: `mtime=0` (GzipFile otherwise stamps
+    the current time) and `filename=""` (it otherwise records the name of the
+    file it is writing, so a build into a differently named path - `--check`'s
+    temp file, say - would not match a release)."""
+    with open(path, "wb") as fh:
+        with gzip.GzipFile(fileobj=fh, mode="wb", mtime=0, filename="") as gz:
+            with tarfile.open(fileobj=gz, mode="w", format=tarfile.PAX_FORMAT) as tar:
+                for name in members(names):
+                    add(tar, name, names, ver)
+    return sha256(path)
+
+
+def content_hashes(path):
+    """member name -> sha256 of its bytes, a symlink hashing its target string."""
+    out = {}
+    with tarfile.open(path, "r:gz") as tar:
+        for info in tar.getmembers():
+            if info.issym():
+                out[info.name] = "symlink:" + info.linkname
+                continue
+            fh = tar.extractfile(info)
+            out[info.name] = hashlib.sha256(fh.read()).hexdigest() if fh else "?"
+    return out
+
+
+def human(n):
+    for unit in ("B", "KiB", "MiB", "GiB"):
+        if n < 1024 or unit == "GiB":
+            return "%d %s" % (n, unit) if unit == "B" else "%.1f %s" % (n, unit)
+        n /= 1024.0
+
+
+def tree_files():
+    """Every file in the working tree that the artifact does not carry."""
+    found = []
+    for base, dirs, files in os.walk(ROOT):
+        dirs[:] = [d for d in dirs if d not in (".git", "__pycache__")]
+        for name in files:
+            found.append(os.path.relpath(os.path.join(base, name), ROOT))
+    return sorted(found)
+
+
+def left_out(names):
+    """Paths in the tree the artifact leaves out, grouped by top-level name.
+
+    Not a hardcoded list (plans, tests, benchmarks) but the actual difference
+    between the tree and the listing, so a forgotten `--write-manifest` shows up
+    here instead of as a missing file in a released tree."""
+    kept = set(members(names))
+    groups = {}
+    for rel in tree_files():
+        if rel in kept:
+            continue
+        groups.setdefault(rel.split(os.sep)[0], []).append(rel)
+    return groups
+
+
+def report(ver, names):
+    kept = members(names)
+    total = sum(size_of(n) for n in kept)
+    print("tezgah %s from %s" % (ver, ROOT))
+    print("%d files in the artifact (%d listed, +%s)"
+          % (len(kept), len(names), " +".join(GENERATED)))
+    print("  %s unpacked" % human(total))
+    top = {}
+    for name in kept:
+        top[name.split("/")[0]] = top.get(name.split("/")[0], 0) + 1
+    print("  top level: %s" % ", ".join("%s %d" % (k, top[k]) for k in sorted(top)))
+    groups = left_out(names)
+    if groups:
+        print("left out (in the tree, not in %s): %d file(s)"
+              % (MANIFEST, sum(len(v) for v in groups.values())))
+        for group in sorted(groups):
+            paths = groups[group]
+            shown = ", ".join(paths[:3]) + (", ..." if len(paths) > 3 else "")
+            print("  %s %d: %s" % (group, len(paths), shown))
+    else:
+        print("left out (in the tree, not in %s): none" % MANIFEST)
+    return 0
+
+
+def check(tarball, names, ver):
+    if not os.path.isfile(tarball):
+        fail("no artifact at %s - build it first" % tarball)
+    recorded = digest_on_record(tarball)
+    want = sha256(tarball)
+    fd, tmp = tempfile.mkstemp(prefix="tezgah-check.", suffix=".tar.gz")
+    os.close(fd)
+    try:
+        got = build(tmp, names, ver)
+        print("artifact %s" % want)
+        print("rebuild  %s" % got)
+        if want != got:
+            after = content_hashes(tmp)
+            before = content_hashes(tarball)
+            shown = 0
+            for name in sorted(set(before).union(after)):
+                if before.get(name) == after.get(name):
+                    continue
+                where = ("changed" if name in before and name in after
+                         else "added" if name not in before else "removed")
+                print("  %s %s" % (where, name))
+                shown += 1
+                if shown == 20:
+                    print("  ... more differ")
+                    break
+            print("FAIL    rebuild differs - the tree changed since %s"
+                  % os.path.basename(tarball))
+            return 1
+        print("ok      a rebuild of this tree is byte-identical")
+    finally:
+        os.remove(tmp)
+    if recorded and recorded != want:
+        print("FAIL    %s records %s" % (os.path.basename(tarball) + ".sha256", recorded))
+        return 1
+    return 0
+
+
+def digest_on_record(tarball):
+    """The digest the .sha256 sidecar claims, or "" when there is none."""
+    try:
+        with open(tarball + ".sha256") as fh:
+            return fh.read().split()[0]
+    except (OSError, IndexError):
+        return ""
+
+
+def main():
+    ver = version()
+    names = listing()
+    out = os.environ["TEZGAH_OUT"]
+    if not os.path.isabs(out):
+        out = os.path.join(ROOT, out)
+    if os.environ["TEZGAH_MODE"] == "list":
+        return report(ver, names)
+    try:
+        os.makedirs(out)
+    except OSError:
+        if not os.path.isdir(out):
+            fail("cannot create %s" % out)
+    tarball = os.path.join(out, "tezgah-%s.tar.gz" % ver)
+    if os.environ["TEZGAH_MODE"] == "check":
+        return check(tarball, names, ver)
+    digest = build(tarball, names, ver)
+    with open(tarball + ".sha256", "w") as fh:
+        fh.write("%s  %s\n" % (digest, os.path.basename(tarball)))
+    total = sum(size_of(n) for n in members(names))
+    shown = os.path.join(os.environ["TEZGAH_OUT"], os.path.basename(tarball))
+    print("ok      %s" % shown)
+    print("        %d files, %s unpacked, %s compressed"
+          % (len(members(names)), human(total), human(os.path.getsize(tarball))))
+    print("        sha256 %s" % digest)
+    print("        %s.sha256 (what upgrade.sh verifies)" % shown)
+    groups = left_out(names)
+    if groups:
+        print("note    %d file(s) in the tree are not in %s (see --list)"
+              % (sum(len(v) for v in groups.values()), MANIFEST))
+    return 0
+
+
+raise SystemExit(main())
+PY