@r1z4x/tezgah 1.9.0 → 1.11.0

package/README.de.md

@@ -49,7 +49,7 @@ auf dieselbe Weise.
 - **Forschung kommt mit eigener Bibliothek.** Forschungsaufgaben laufen über
   OpenResearch, mit einer integrierten Bibliothek aus 98 Upstream-Skills, die
   Eintrag für Eintrag geladen wird, damit der Kontext klein bleibt.
-- **Jede Regel hat einen Ausschalter.** Sechzehn Kill-Switches — dazu
+- **Jede Regel hat einen Ausschalter.** Siebzehn Kill-Switches — dazu
   Repo-Markierungen — entfernen den Regeltext aus der Sitzung; die Regel
   stoppt damit wirklich, statt nur als aus zu erscheinen.
 - **Eine feste Antwortform.** Antworten sind türkisch, sofern Sie keine andere Sprache wählen, und

package/README.es.md

@@ -49,7 +49,7 @@ en un lugar llega a todos los hosts de la misma manera.
   dirigen a través de OpenResearch con una biblioteca incorporada de 98
   habilidades upstream, cargada de una en una para que el contexto siga
   siendo pequeño.
-- **Cada regla tiene un interruptor de apagado.** Dieciséis interruptores — más
+- **Cada regla tiene un interruptor de apagado.** Diecisiete interruptores — más
   las marcas por repositorio — eliminan el texto de la regla de la sesión, de
   modo que la regla realmente se detiene en lugar de limitarse a figurar como
   desactivada.

package/README.fr.md

@@ -48,7 +48,7 @@ modifiée à un endroit atteint chaque hôte de la même façon.
 - **La recherche arrive avec sa bibliothèque.** Les tâches de recherche
   passent par OpenResearch avec une bibliothèque intégrée de 98 compétences
   upstream, chargée une entrée à la fois pour que le contexte reste petit.
-- **Chaque règle a un interrupteur.** Seize interrupteurs — plus des
+- **Chaque règle a un interrupteur.** Dix-sept interrupteurs — plus des
   marques par dépôt — retirent le texte de la règle de la session ; la règle
   s'arrête vraiment au lieu de simplement figurer comme désactivée.
 - **Une forme de réponse fixe.** Les réponses sont en turc, sauf si vous choisissez une autre langue, et

package/README.md

@@ -46,7 +46,7 @@ reaches every host the same way.
 - **Research ships with its library.** Research tasks route through
   OpenResearch with a vendored library of 98 upstream skills, loaded one entry
   at a time so the context stays small.
-- **Every rule has an off switch.** Sixteen kill switches — plus per-repo
+- **Every rule has an off switch.** Seventeen kill switches — plus per-repo
   marks — remove a rule's text from the session, so the rule actually stops
   rather than merely showing as off.
 - **A fixed reply shape.** Replies lead with the outcome, in Turkish unless

package/README.tr.md

@@ -48,7 +48,7 @@ değiştirdiğinizde her barındırıcıya aynı şekilde ulaşır.
 - **Araştırma kütüphanesiyle birlikte gelir.** Araştırma görevleri,
   bağlamın küçük kalması için tek tek yüklenen 98 becerilik gömülü
   bir kütüphaneyle OpenResearch üzerinden yürütülür.
-- **Her kuralın bir kapatma anahtarı vardır.** On altı kapatma anahtarı — ve
+- **Her kuralın bir kapatma anahtarı vardır.** On yedi kapatma anahtarı — ve
   depo başına işaretler — kuralın metnini oturumdan kaldırır; böylece kural
   yalnızca kapalı görünmez, gerçekten durur.
 - **Sabit bir yanıt biçimi.** Yanıtlar, başka bir dil seçmediyseniz Türkçedir ve sonuçla

package/bin/codegen

@@ -49,7 +49,7 @@ import urllib.request
 import json
 
 HOOKS = os.path.join(
-    os.path.dirname(os.path.dirname(os.path.abspath(__file__))), "hooks")
+    os.path.dirname(os.path.dirname(os.path.realpath(__file__))), "hooks")
 sys.path.insert(0, HOOKS)
 import tezgah_integrity as ti  # noqa: E402
 import tezgah_paths as tp  # noqa: E402
@@ -220,7 +220,10 @@ def ask(task, files, model, provider, timeout, max_tokens):
 
 def main():
     args = sys.argv[1:]
-    if not args or args[0] in ("-h", "--help"):
+    if args and args[0] in ("-h", "--help"):
+        print(__doc__.strip())
+        return
+    if not args:
         sys.exit(__doc__.strip())
     task, files, model, provider, timeout, out_dir, max_tokens = \
         args[0], [], None, "openrouter", 300, None, 0

package/bin/tezgah-design

@@ -4,12 +4,20 @@ can fail.
 
   tezgah-design derive --repo DIR [--out FILE] [--json]
   tezgah-design check --contract FILE --measured FILE|- [--json]
+  tezgah-design slop --repo DIR [--url URL] [--render] [--measured FILE]
+                        [--out FILE] [--json]
 
 The contract is the floor a UI turn is judged against: the colour roles, the
 type scale, the spacing unit and the state set a repository already uses, plus
 the component inventory it owns. `derive` writes a first `.tezgah/design-contract.md`
 from the repository's own token source (CSS custom properties, a Tailwind config,
 a tokens/theme JSON) and exits 2 rather than invent a palette it did not find.
+`slop` runs Hallmark's own gate list (`skills/hallmark/scripts/sloplint.mjs`)
+over the repository or a running URL, writes the verdict to
+`.tezgah/design/slop.json` and exits 1 on any Floor FAIL. It is the Hallmark half
+of the UI floor; `check` is ours, and a contract's `precedence` says which of the
+two owns each key, so neither can quietly override the other. Exit 3 when Node or
+the vendored skill is missing: that is a check that did not run, never a pass.
 `check` compares a measurement - the per-component computed styles and observed
 states the analyze-app loop produces - against that file, prints every violation
 with its component and its rule, and exits non-zero when there is at least one.
@@ -26,8 +34,11 @@ repository in the artifact.
           more violations; 2 usage, IO, a bad contract or nothing judged
 """
 import json
+import math
 import os
 import re
+import shutil
+import subprocess
 import sys
 
 HERE = os.path.dirname(os.path.dirname(os.path.realpath(__file__)))
@@ -51,6 +62,15 @@ KINDS = ("interactive", "data")
 # The floors that are not this repository's to choose: WCAG 2.2 SC 2.5.8 (the
 # 24x24 CSS px target size) and SC 1.4.3 (4.5:1, or 3:1 for large text, which is
 # 24px and up, or 18.66px bold).
+# The precedence table (plan 133). A key owned by two sources is refused by
+# `check`, so the tie-break cannot drift silently; `verbatim` says how far the
+# user's own words reach, and it stops at style.
+PRECEDENCE = {
+    "ours": ["states", "components", "evidence", "facts"],
+    "theirs": ["material", "motion-character"],
+    "shared": ["contrast", "focus-visible", "reduced-motion", "tap-target"],
+    "verbatim": "style",
+}
 TAP_TARGET = 24
 CONTRAST_NORMAL = 4.5
 CONTRAST_LARGE = 3.0
@@ -506,9 +526,89 @@ def css_tokens(root, files):
     return out, sources
 
 
+DESIGN_MD = ("design.md", "DESIGN.md")
+
+
+def _oklch_to_hex(value):
+    """`oklch(L C H [/ A])` as `#rrggbb`, or None when it is not that shape.
+
+    Hallmark's locked system states its palette in OKLCH; the contract compares
+    measured colours as hex, so one side has to be converted and it is this one.
+    The conversion is Ottosson's OKLab -> linear sRGB with a clamp at the gamut,
+    which is what a browser paints for the same value."""
+    body = value.strip()
+    if not body.lower().startswith("oklch("):
+        return None
+    inner = body[body.index("(") + 1:body.rindex(")")]
+    inner = inner.split("/")[0]
+    parts = [p for p in re.split(r"[\s,]+", inner.strip()) if p]
+    if len(parts) < 3:
+        return None
+    try:
+        light = parts[0]
+        lum = float(light[:-1]) / 100.0 if light.endswith("%") else float(light)
+        c = float(parts[1])
+        hue = parts[2]
+        h = float(hue[:-3]) if hue.endswith("deg") else float(hue)
+    except ValueError:
+        return None
+    rad = math.radians(h)
+    a_, b_ = c * math.cos(rad), c * math.sin(rad)
+    l_ = (lum + 0.3963377774 * a_ + 0.2158037573 * b_) ** 3
+    m_ = (lum - 0.1055613458 * a_ - 0.0638541728 * b_) ** 3
+    s_ = (lum - 0.0894841775 * a_ - 1.2914855480 * b_) ** 3
+    r = 4.0767416621 * l_ - 3.3077115913 * m_ + 0.2309699292 * s_
+    g = -1.2684380046 * l_ + 2.6097574011 * m_ - 0.3413193965 * s_
+    bl = -0.0041960863 * l_ - 0.7034186147 * m_ + 1.7076147010 * s_
+
+    def gamma(x):
+        x = min(1.0, max(0.0, x))
+        return 12.92 * x if x <= 0.0031308 else 1.055 * x ** (1 / 2.4) - 0.055
+    return "#%02x%02x%02x" % tuple(int(round(gamma(v) * 255)) for v in (r, g, bl))
+
+
+def design_md_tokens(root):
+    """(tokens, source) from Hallmark's locked `design.md`, or ({}, "").
+
+    Hallmark's file owns the material: the palette stated in OKLCH, the font
+    roles and the motion character. It owns no state set, no component
+    inventory and no measured evidence, which stay the contract's, so reading it
+    fills the tokens half and leaves the rest to `contract_data`."""
+    for name in DESIGN_MD:
+        path = os.path.join(root, name)
+        if not os.path.isfile(path):
+            continue
+        text = open(path, encoding="utf-8", errors="replace").read()
+        block = re.search(r"```css\s*(.*?)```", text, re.S)
+        if not block:
+            continue
+        colors, fonts = {}, {}
+        for var, value in re.findall(r"--([a-z0-9-]+)\s*:\s*([^;]+);", block.group(1)):
+            value = value.strip()
+            if var.startswith("color-"):
+                role = var[len("color-"):]
+                hexv = _oklch_to_hex(value) if value.lower().startswith("oklch(") else (
+                    value if re.fullmatch(r"#[0-9a-fA-F]{3,8}", value) else None)
+                if hexv:
+                    colors[role] = hexv
+            elif var.startswith("font-"):
+                fonts[var[len("font-"):]] = value
+        if colors:
+            tokens = {"colors": colors}
+            if fonts:
+                tokens["fonts"] = fonts
+            return tokens, "design-md"
+    return {}, ""
+
+
 def derive(root):
     """(tokens, source, read from) from the repository's own token source, or
     (None, reason, []) when it carries none."""
+    locked, locked_source = design_md_tokens(root)
+    if locked.get("colors"):
+        # a locked system wins over a re-derivation: pages share it, and a second
+        # floor derived beside it is the drift plan 133 exists to prevent
+        return locked, locked_source, [os.path.join(root, "design.md")]
     files = walk(root)
     for name, reader in (("css-custom-properties", css_tokens),
                          ("tailwind-config", tailwind_tokens),
@@ -532,10 +632,19 @@ def contract_data(tokens, source):
             "colors": tokens.get("colors") or {},
             "tap_target": TAP_TARGET,
             "contrast": {"normal": CONTRAST_NORMAL, "large": CONTRAST_LARGE},
+            # Hallmark's design.md states the font roles; nothing else does, so
+            # they ride the tokens when it is the source (audit of plan 133)
+            **({"fonts": tokens["fonts"]} if tokens.get("fonts") else {}),
         },
         "states": {"interactive": list(STATES_INTERACTIVE),
                    "data": list(STATES_DATA)},
         "components": [],
+        # plan 133: one machine-read precedence between this contract and
+        # Hallmark's design.md, so the two floors cannot drift. `ours` is what a
+        # Hallmark stamp, waiver or verbatim flag can never relax; `theirs` is
+        # the material we do not judge; `shared` states the same intent on both
+        # sides, our numbers and their shapes.
+        "precedence": dict(PRECEDENCE),
     }
 
 
@@ -614,6 +723,40 @@ def _violation(component, rule, detail):
     return {"component": component, "rule": rule, "detail": detail}
 
 
+def precedence_problem(table):
+    """Why a contract's precedence cannot be read, or "" when it can.
+
+    Plan 133: the table is the only tie-break between this floor and Hallmark's
+    design.md, so an ambiguous one is refused rather than resolved by whoever
+    reads it next. Absent is allowed - a contract written before the table
+    existed keeps working - but a present one must name every key exactly once
+    and must not hand `facts` to the user's own words."""
+    if table is None:
+        return ""
+    if not isinstance(table, dict):
+        return "precedence must be an object of classes to keys"
+    seen = {}
+    for cls in ("ours", "theirs", "shared"):
+        keys = table.get(cls)
+        if keys is None:
+            continue
+        if not isinstance(keys, list) or not all(isinstance(k, str) for k in keys):
+            return "precedence.%s must be a list of key names" % cls
+        for key in keys:
+            if key in seen:
+                return ("precedence names %r twice (%s and %s): one key belongs "
+                        "to one source" % (key, seen[key], cls))
+            seen[key] = cls
+    if "facts" in table.get("theirs", []) or "facts" in table.get("shared", []):
+        return ("precedence cannot share `facts`: an invented metric, quote or "
+                "logo is never licensed by a theme, a waiver or the user's words")
+    verbatim = table.get("verbatim")
+    if verbatim not in (None, "style"):
+        return ("precedence.verbatim may only be `style`: the user's own words "
+                "excuse a style gate, never a fabricated fact")
+    return ""
+
+
 def check(data, measured):
     """(violations, unjudged, judged): every disagreement between a measurement
     and the contract, each naming its component and its rule, the count of
@@ -806,6 +949,8 @@ def parse(argv, names):
         arg = argv[i]
         if arg == "--json":
             out["json"] = True
+        elif arg == "--render":
+            out["render"] = True
         elif arg in names:
             if i + 1 >= len(argv):
                 raise Usage("%s wants a value" % arg)
@@ -881,6 +1026,140 @@ def derive_cli(opts):
     return 0
 
 
+SLOPLINT = os.path.join("skills", "hallmark", "scripts", "sloplint.mjs")
+
+
+def sloplint_path(root):
+    """The vendored linter's path, or "" when it is not installed beside us."""
+    # `HERE` is the realpath of this script's checkout: `abspath(__file__)` is
+    # the symlink in `~/.config/tezgah/bin` under an install, so the linter was
+    # looked for in `~/.config/tezgah/skills/...`, which no install writes
+    # (audit of plan 133). `root`'s own copy comes first for a vendored checkout.
+    candidates = [
+        os.path.join(root, SLOPLINT),
+        os.path.join(os.path.dirname(os.path.dirname(os.path.abspath(root))), SLOPLINT),
+        os.path.join(HERE, SLOPLINT),
+    ]
+    for path in candidates:
+        if os.path.isfile(path):
+            return path
+    return ""
+
+
+def slop_cli(opts):
+    """Hallmark's gate list, run over this repository, into one verdict.
+
+    The Floor is theirs and Ours is the contract's, so this verb is the one place
+    the two are merged: `sloplint --json` gives FAIL/REFLEX, and the contract's
+    `check` runs when a measurement is given. A merge that hides one side would
+    make a page pass here and fail in the Stop rule, so the verdict is the union
+    and it is written down (`.tezgah/design/slop.json`) for that rule to read."""
+    root = project_top(os.path.abspath(opts.get("repo") or ""))
+    if not os.path.isdir(root):
+        raise Usage("--repo must name a directory")
+    linter = sloplint_path(root)
+    if not linter:
+        sys.stderr.write("tezgah-design: hallmark is not installed beside tezgah "
+                         "(%s), so only the contract check can run - no static "
+                         "slop tier this time\n" % SLOPLINT)
+        return 3
+    if not shutil.which("node"):
+        sys.stderr.write("tezgah-design: node is not on PATH, so hallmark's "
+                         "sloplint cannot run - only the contract check can\n")
+        return 3
+    target = opts.get("url") or root
+    argv = [shutil.which("node"), linter, "--json"]
+    if opts.get("url"):
+        argv += ["--url", opts["url"]]   # a URL is an address, never a path
+    else:
+        argv.append(root)
+    if opts.get("render"):
+        argv.append("--render")
+    if opts.get("genre"):
+        argv += ["--genre", opts["genre"]]
+    try:
+        proc = subprocess.run(argv, capture_output=True, text=True, timeout=300)
+    except (OSError, subprocess.SubprocessError) as exc:
+        raise Usage("sloplint could not run: %s" % exc)
+    try:
+        report = json.loads(proc.stdout)
+    except ValueError:
+        raise Usage("sloplint printed no JSON (exit %d): %s"
+                    % (proc.returncode, (proc.stderr or "").strip()[:200]))
+    summary = report.get("summary") or {}
+    fails, reflex = int(summary.get("fails") or 0), int(summary.get("reflex") or 0)
+    # What the render tier actually did, never what the flag asked for: without
+    # puppeteer-core sloplint answers `not run: …` and every Floor/R and M/R gate
+    # stays unjudged, so a `clean` there would excuse a page nobody measured
+    # (review of plan 133 finding 2).
+    rendered = str(summary.get("render") or "off")
+    unjudged = rendered.startswith("not run")
+    verdict = {"version": 1, "tool": "tezgah-design slop",
+               "sloplint_exit": proc.returncode,
+               "target": target if opts.get("url") else os.path.abspath(target),
+               "render": rendered,
+               "render_unjudged": unjudged,
+               "fails": fails, "reflex": reflex,
+               "waived": int(summary.get("waived") or 0),
+               "answered": int(summary.get("answered") or 0),
+               "clean": fails == 0 and reflex == 0 and not unjudged,
+               "findings": [f for f in (report.get("findings") or [])
+                            if f.get("grade") in ("FAIL", "REFLEX")]}
+    ws = linked_main(root) or root
+    # The union, enforced here rather than in the Stop rule (review of plan 133
+    # finding 3): a component's UI floor is Hallmark's gate list AND this
+    # repository's contract, so `slop` reads the contract half too. No contract,
+    # no obligation. A contract with no measurement is unjudged, never clean.
+    contract_path = os.path.join(ws, ".tezgah", "design-contract.md")
+    contract = {"present": os.path.isfile(contract_path), "judged": False,
+                "violations": [], "unjudged": 0}
+    if contract["present"]:
+        data, reason = read_contract(contract_path)
+        if data is None:
+            raise Usage(reason)
+        problem = precedence_problem(data.get("precedence"))
+        if problem:
+            raise Usage(problem)
+        raw = ""
+        measured_path = opts.get("measured") or os.path.join(
+            ws, ".tezgah", "design", "measurement.json")
+        if os.path.isfile(measured_path):
+            with open(measured_path, encoding="utf-8") as fh:
+                raw = fh.read()
+        if raw.strip():
+            try:
+                got = json.loads(raw)
+            except ValueError:
+                raise Usage("the measurement is not JSON: %s" % measured_path)
+            if isinstance(got, list):
+                got = {"components": got}   # the shape check_cli also accepts
+            violations, unjudged, judged = check(data, got)
+            contract.update(judged=judged > 0, unjudged=unjudged,
+                            violations=list(violations))
+    verdict["contract"] = contract
+    if contract["present"] and (not contract["judged"] or contract["violations"]):
+        verdict["clean"] = False
+    out = opts.get("out") or os.path.join(ws, ".tezgah", "design", "slop.json")
+    try:
+        os.makedirs(os.path.dirname(os.path.abspath(out)), exist_ok=True)
+        with open(out, "w", encoding="utf-8") as fh:
+            json.dump(verdict, fh, indent=2, sort_keys=True)
+            fh.write("\n")
+    except OSError as exc:
+        raise Usage("cannot write %s: %s" % (out, exc))
+    if opts.get("json"):
+        _print_json(verdict)
+    else:
+        sys.stdout.write("slop: %d FAIL, %d REFLEX over %s (render %s) -> %s\n"
+                         % (fails, reflex, target, rendered,
+                            "clean" if verdict["clean"] else "not clean"))
+    if contract["present"] and not contract["judged"]:
+        sys.stderr.write("tezgah-design: the contract exists but no measurement "
+                         "judged a component, so the design half is unjudged - "
+                         "run the analyze-app loop and pass --measured\n")
+    return 0 if verdict["clean"] and not contract["violations"] else 1
+
+
 def check_cli(opts):
     contract = opts.get("contract")
     measured = opts.get("measured")
@@ -895,6 +1174,9 @@ def check_cli(opts):
     data, reason = read_contract(contract)
     if data is None:
         raise Usage(reason)
+    problem = precedence_problem(data.get("precedence"))
+    if problem:
+        raise Usage(problem)
     if measured == "-":
         raw = sys.stdin.read()
     else:
@@ -954,12 +1236,17 @@ def main(argv):
         sys.stdout.write(__doc__)
         return 0 if argv else 2
     verb, rest = argv[0], argv[1:]
+    if verb in ("derive", "check") and "--render" in rest:
+        sys.stderr.write("tezgah-design: --render belongs to `slop`, not %s\n" % verb)
+        return 2
     try:
         if verb == "derive":
             return derive_cli(parse(rest, ("--repo", "--out")))
         if verb == "check":
             return check_cli(parse(rest, ("--contract", "--measured")))
-        raise Usage("unknown verb: %s (derive|check)" % verb)
+        if verb == "slop":
+            return slop_cli(parse(rest, ("--repo", "--url", "--out", "--genre", "--measured")))
+        raise Usage("unknown verb: %s (derive|check|slop)" % verb)
     except Usage as exc:
         sys.stderr.write("tezgah-design: %s\n" % exc)
         return 2

package/bin/tezgah-docs

@@ -106,7 +106,7 @@ RUN = re.compile(r"((?:`[A-Za-z_][A-Za-z0-9_]*(?:\(\))?`\s*[/,]?\s*){1,5})$")
 CITE = re.compile(r"`([\w.-]+(?:/[\w.-]+)+|[\w-]+\.\w+):(\d+)(?:-(\d+))?`"
                   r"|`(:(\d+)(?:-(\d+))?)`")
 # The symbol written after the citation instead of before it, the way a table
-# cell reads: `hooks/tezgah_policy.py:787-1105` (`CORE`).
+# cell reads: `hooks/tezgah_policy.py:806-1135` (`CORE`).
 AFTER = re.compile(r"\s*\(`([A-Za-z_][A-Za-z0-9_]*)(?:\(\))?`\)")
 # Any `path:line`, backticked or not: what CITE does not match of these (a
 # bare token, a comma list `x.py:12,40`) is counted as unjudged, so a citation

package/bin/tezgah-doctor

@@ -11,7 +11,9 @@ Two stores grow without bound and neither rotates on its own:
 
 It also reports the hosts' own state (~/.codex, ~/.omp, ~/.claude) and never
 touches it: those stores belong to the hosts, and the number is here so a reader
-can decide, not so this tool can act.
+can decide, not so this tool can act. The current checkout's `.tezgah` shape is
+one row: its own repository, or tracked by the project (folded), whose commits
+are then the project's history.
 
 This tool is read-only by default. With --clean it vacuums the opencode database
 (only when opencode is not running, so it cannot fight a live connection).
@@ -65,7 +67,7 @@ HOME = os.path.expanduser("~")
 REPO_ROOT = os.path.dirname(os.path.dirname(os.path.realpath(__file__)))
 sys.path.insert(0, os.path.join(REPO_ROOT, "hooks"))
 from tezgah_paths import (CACHE, CODEGRAPH, codegraph_bin,  # noqa: E402
-                          fallback_cache, root_for, roots)
+                          fallback_cache, project_top, root_for, roots, workspace)
 
 # the coverage rules, in the bench directory next to the hooks that own the roots
 # and the binary resolver. MANIFEST lists it, so it ships; it is also the one file
@@ -214,6 +216,37 @@ def opencode_running():
         return False
 
 
+def workspace_shape(path):
+    """{repo, shape} for the checkout holding `path`: `own` when its `.tezgah`
+    holds a repository of its own (a linked worktree's link to the main
+    checkout's included), `tracked` when the project tracks it (folded:
+    `tezgah_research.folded`, the project's history carries it), else `none`;
+    repo is None outside a git checkout."""
+    import tezgah_research
+    try:
+        out = subprocess.run(["git", "-C", path, "rev-parse", "--show-toplevel"],
+                             capture_output=True, text=True)
+    except OSError:
+        return {"repo": None, "shape": "none"}
+    if out.returncode or not out.stdout.strip():
+        return {"repo": None, "shape": "none"}
+    repo = project_top(out.stdout.strip())
+    if tezgah_research.folded(repo):
+        shape = "tracked"
+    elif os.path.isdir(os.path.join(os.path.realpath(workspace(repo)), ".git")):
+        shape = "own"
+    else:
+        shape = "none"
+    return {"repo": repo, "shape": shape}
+
+
+WORKSPACE_ROWS = {
+    "own": "own repository (`git -C .tezgah`)",
+    "tracked": "tracked by the project: the project's history carries it",
+    "none": "none yet",
+}
+
+
 def collect(pairs):
     cfg = opencode_cfg()
     repos = []
@@ -230,6 +263,7 @@ def collect(pairs):
         "codegraph_repos": repos,
         "codegraph_bytes": sum(r["bytes"] for r in repos),
         "tezgah_cache_bytes": du(TEZGAH_CACHE) if os.path.isdir(TEZGAH_CACHE) else 0,
+        "workspace": workspace_shape(os.getcwd()),
         **host_bytes(),
     }
 
@@ -571,6 +605,9 @@ def report(rep):
                  len(rows) - indexed))
     print("tezgah")
     print("  cache         %s" % human(rep["tezgah_cache_bytes"]))
+    ws = rep["workspace"]
+    print("  workspace     %s" % ("%s  (%s)" % (WORKSPACE_ROWS[ws["shape"]], ws["repo"])
+                                  if ws["repo"] else "not in a git checkout"))
     print("host state (the hosts' own; this tool never touches it)")
     for label, key in (("codex", "codex_bytes"), ("omp", "omp_bytes"),
                        ("claude", "claude_bytes")):

package/bin/tezgah-import-ai-research

@@ -9,8 +9,12 @@ upstream clone being present.
   bin/tezgah-import-ai-research --source <path-to-AI-research-SKILLs-clone> --rev 773a529
   bin/tezgah-import-ai-research --check
 
-A vendored path is its provenance, so the upstream layout is kept verbatim:
-`<category>/<skill>/SKILL.md` beside its `references/`. What is dropped, and why,
+A vendored path is its provenance, so the upstream layout is kept verbatim, with
+one rename: upstream's `<category>/<skill>/SKILL.md` is written as
+`<category>/<skill>/ENTRY.md` beside its `references/`, bytes unchanged. codex
+and Cursor list every SKILL.md below a skills directory, nested ones included,
+so 98 vendored entries named SKILL.md would each be listed as a host skill and
+push tezgah's own out of the host's skill budget. What is dropped, and why,
 is DROP_FILES and DROP_DIRS; everything that is not markdown is dropped by the
 `*.md` filter, so no PDF, LaTeX class, image or `.gitkeep` reaches the repo. A
 vendored file with no YAML frontmatter gets one attribution comment; upstream's
@@ -41,7 +45,7 @@ LICENCE = "MIT"
 EXPECTED_CATEGORIES, EXPECTED_SKILLS = 23, 98
 
 # Three machine-scraped reference dumps. They are concatenated official docs with
-# `URL:` headers, not guides, and the entry's own SKILL.md already distils them.
+# `URL:` headers, not guides, and the entry's own ENTRY.md already distils them.
 DROP_FILES = (
     "03-fine-tuning/unsloth/references/llms-full.md",
     "03-fine-tuning/unsloth/references/llms-txt.md",
@@ -86,6 +90,8 @@ GENERATED_MARKS = ("automatically generated from official documentation",
 ATTRIBUTION = "<!-- vendored from orchestra-research/%s@%s %s; %s (c) Orchestra Research -->"
 
 CATEGORY_RE = re.compile(r"^(0-|[0-9]{2}-)")
+# Upstream names an entry SKILL.md; the vendored copy is ENTRY.md (module docstring).
+UPSTREAM_ENTRY, ENTRY = "SKILL.md", "ENTRY.md"
 
 
 def sha256(path):
@@ -155,6 +161,12 @@ def rel_of(category, skill):
     return category if skill == category else "%s/%s" % (category, skill)
 
 
+def vendored(relfile):
+    """The path an upstream file is written to: an entry SKILL.md becomes ENTRY.md."""
+    head, name = os.path.split(relfile)
+    return os.path.join(head, ENTRY) if name == UPSTREAM_ENTRY else relfile
+
+
 def kept_files(source, rel):
     """The files this vendoring keeps from one skill dir, as relative paths."""
     base = os.path.join(source, rel)
@@ -235,8 +247,8 @@ def build(source, rev):
             "upstream_path": rel,
         }
         for relfile, body in sorted(body_texts.items()):
-            files[relfile] = body
-            entry["files"].append({"path": relfile, "bytes": len(body.encode()),
+            files[vendored(relfile)] = body
+            entry["files"].append({"path": vendored(relfile), "bytes": len(body.encode()),
                                    "sha256": hashlib.sha256(body.encode()).hexdigest()})
         entry["bytes"] = sum(f["bytes"] for f in entry["files"])
         rows.append(entry)
@@ -270,8 +282,8 @@ def build(source, rev):
                 flags.append("stale-api")
             if entry["dangling_links"]:
                 flags.append("dead-links: %d" % len(entry["dangling_links"]))
-            lines.append("| `%s` | `%s/SKILL.md` | %s | %s |"
-                         % (entry["dir"], entry["upstream_path"], entry["purpose"],
+            lines.append("| `%s` | `%s/%s` | %s | %s |"
+                         % (entry["dir"], entry["upstream_path"], ENTRY, entry["purpose"],
                             ", ".join(flags)))
         generated["index/%s.md" % stage] = "\n".join(lines) + "\n"
 
@@ -314,10 +326,12 @@ def source_text(manifest, rev):
         "## What is vendored\n\n"
         "Every skill's `SKILL.md` and every markdown file beside it, in the upstream\n"
         "layout, because a vendored path is its provenance. %d skills across %d\n"
-        "categories, %d files, %d bytes.\n\n"
+        "categories, %d files, %d bytes. One rename: each entry's `SKILL.md` sits at\n"
+        "the upstream path as `ENTRY.md`, bytes unchanged, so a host that lists every\n"
+        "`SKILL.md` below its skills directory (codex, Cursor) does not list it.\n\n"
         "## What is not, and why\n\n"
         "Files: %s - machine-scraped reference dumps, which the entry's own\n"
-        "`SKILL.md` already distils.\n\n"
+        "`ENTRY.md` already distils.\n\n"
         "Directories: %s - LaTeX class/bst/bib trees and example PDFs,\n"
         "re-downloadable from each venue.\n\n"
         "Everything else that is not markdown (PDFs, images, `.gitkeep`, scripts)\n"
@@ -325,9 +339,9 @@ def source_text(manifest, rev):
         "`packages/`, `video-promo/` are upstream's repo furniture, not content.\n\n"
         "## The only modification\n\n"
         "A markdown file that carries no YAML frontmatter gets one attribution\n"
-        "comment on its first line. `SKILL.md` files are byte-for-byte upstream,\n"
-        "frontmatter included. `skills/ai-research/SKILL.md` is tezgah's own and is\n"
-        "not part of the manifest.\n\n"
+        "comment on its first line. `ENTRY.md` files are byte-for-byte upstream\n"
+        "`SKILL.md`, frontmatter included. `skills/ai-research/SKILL.md` is\n"
+        "tezgah's own and is not part of the manifest.\n\n"
         "## Re-vendoring\n\n"
         "`bin/tezgah-import-ai-research --source <clone> --rev <sha>`, then commit\n"
         "the diff. `--check` verifies the committed tree against `library.json`\n"