@r1z4x/tezgah 1.8.3 → 1.9.0

package/bin/tezgah-task

@@ -1,7 +1,7 @@
 #!/usr/bin/env python3
 """tezgah-task - the active task: one plan's phase and its path allowlist.
 
-  tezgah-task start <NNN|path> --phase P [--allow GLOB ... | --any-path]   activate a plan
+  tezgah-task start <NNN|path> --phase P [--allow GLOB ... | --any-path] [--branch B]   activate a plan; --branch binds the worktree on B to it
   tezgah-task phase P [--any-path]                            change the active task's phase
   tezgah-task allow GLOB ... | --any-path --why REASON         replace the allowlist, recording why
   tezgah-task stop                                            deactivate (clear phase)
@@ -11,6 +11,7 @@
   tezgah-task tick <NNN|path> <n> [--undo]                   tick (or untick) Acceptance item n, counted from 1
   tezgah-task note <NNN|path> state|next "<text>"            replace the body of `## State` (the newest one) or `## Next`
   tezgah-task spike <NNN|path> "<answer>"                    record the spike's answer (`spike_recorded:`)
+  tezgah-task unmet <NNN|path> <n> "<reason, who accepted it>"  annotate Acceptance item n with `UNMET:`, the form close accepts
   tezgah-task slice open --id ID [--kind agent|job] [--host H] [--agent A] [--brief TEXT|--brief-file F] [--parent P] [--cwd PATH]
                                                               record a delegated slice (a re-open counts one more attempt)
   tezgah-task slice done ID | slice stop ID [--class C]      close a slice record
@@ -19,6 +20,7 @@
   tezgah-task slice stats [--window DAYS] [--json]            counts per status, failure class and host, and the RSI lever candidates
   tezgah-task slice board [--parent P]                        the open sibling slices: what each owns, its worktree, branch and last commit
   tezgah-task slice merge-plan [--base REF]                   the done slice branches in merge order, with their forecast conflicts
+  tezgah-task sweep                                           the last session's leftovers: pending slices, landed worktrees and branches, an orphan phase
 
 The record is the plan file itself: `phase:` activates it, `allowed_paths:` is
 the scope a write has to stay inside, and `start` clears every other plan's
@@ -37,7 +39,7 @@ and this CLI is the record's only writer: the gate refuses a write to the plan
 file, because the checks below are made here and a retyped frontmatter would
 skip them. `phase implementation` (or `verification`) is what lets a write
 through, so the phase changes when the work reaches that point and not before.
-`tick`, `note` and `spike` are the record's body writers for the same reason:
+`tick`, `note`, `spike` and `unmet` are the record's body writers for the same reason:
 they write an Acceptance box, the State/Next text or the spike's answer on any
 open plan, active or not, keep the rest of the frontmatter but `updated:`, and
 commit nothing.
@@ -134,7 +136,7 @@ import time
 HERE = os.path.dirname(os.path.dirname(os.path.realpath(__file__)))
 sys.path.insert(0, os.path.join(HERE, "hooks"))
 import tezgah_task as tt  # noqa: E402
-from tezgah_paths import project_top, say  # noqa: E402
+from tezgah_paths import project_top, say, work_tree  # noqa: E402
 
 
 def repo_root(path):
@@ -198,6 +200,22 @@ def active_here(root):
     return tt.active(root, root, held=True)
 
 
+def own_task(root):
+    """(task, problem) for a command that writes the active plan's record. In a
+    linked worktree on a branch that binds a plan - `plan/NNN-...` or the plan's
+    declared `branch:` - that is plan NNN or a refusal, never the main
+    checkout's first phased plan: `allow` there replaced another plan's
+    allowlist (plan 102). The gate keeps that fallback, which holds the
+    worktree's writes; only the record write is refused."""
+    task = active_here(root)
+    ident = tt.plan_of_branch(tt.worktree_branch(root), main_root(root))
+    if ident is not None and (not task or task["id"] != ident):
+        return None, ("this worktree is plan %s's and plan %s is not the active task "
+                      "here: start it with `tezgah-task start %s --phase P`; no other "
+                      "plan's record moves from this worktree" % (ident, ident, ident))
+    return task, None
+
+
 def problems(items):
     for problem in items:
         print("FAIL %s" % problem)
@@ -271,7 +289,7 @@ def checkpoint_state(value, path):
         # a plan held by its own worktree waits on that checkout's commit, the
         # one the gate reads (tezgah_gate.checkpoint_reason)
         holder = holder_of(path)
-        root = holder or repo_root(os.path.dirname(path) or ".")
+        root = holder or work_tree(repo_root(os.path.dirname(path) or "."))
         head = git_out(root, "rev-parse", "HEAD")
         listed = git_out(root, "status", "--porcelain")
         if not head or head != sha or not listed:
@@ -451,7 +469,7 @@ def verification_steps(text, path):
         print("     - %s" % item)
     # the deferred tier: never inside a turn, run once here at the merge step
     deferred = [cmd for rel, cmd in MERGE_CHECKS
-                if os.path.isfile(os.path.join(root, rel))]
+                if os.path.isfile(os.path.join(work_tree(where), rel))]
     if deferred:
         print("     the merge step's one run of the deferred checks: %s"
               % ", ".join("`%s`" % c for c in deferred))
@@ -518,6 +536,7 @@ def cmd_start(args):
     root = main_root(repo_root(os.getcwd()))
     path, problem = open_plan(args[0])
     phase = None
+    branch = None
     allow = []
     any_path = False
     rest = args[1:]
@@ -529,6 +548,12 @@ def cmd_start(args):
             phase = rest[i + 1]
             i += 2
             continue
+        if rest[i] == "--branch":
+            if i + 1 >= len(rest) or rest[i + 1].startswith("--"):
+                return misuse("--branch needs the branch name to bind the plan to")
+            branch = rest[i + 1]
+            i += 2
+            continue
         if rest[i] == ANY_PATH:
             any_path = True
             i += 1
@@ -553,6 +578,8 @@ def cmd_start(args):
         return problems([problem])
     text = read(path)
     fields = {"phase": phase, "updated": today()}
+    if branch:
+        fields["branch"] = branch   # binds the worktree on it (plan 105)
     if allow or any_path:
         fields.update(allowed_paths=allow, allowed_from="--allow" if allow else ANY_PATH)
         if tt.frontmatter(text).get("allowed_why"):
@@ -567,9 +594,11 @@ def cmd_start(args):
         return problems(bad)
     holders = tt.plan_holders(root)
     # the plan's own worktree, when one holds it: the gate reads the checkpoint
-    # against that checkout's HEAD and tree, so it is recorded from there
-    here = holders.get(tt._plan_id(tt.frontmatter(text), os.path.basename(path)))
-    fields.update(checkpoint_fields(here or root, phase))
+    # against that checkout's HEAD and tree, so it is recorded from there - the
+    # one on the branch this start binds, before the record names it
+    here = (holders.get(tt._plan_id(tt.frontmatter(text), os.path.basename(path)))
+            or branch and tt._worktree_branches(root).get(branch))
+    fields.update(checkpoint_fields(here or work_tree(root), phase))
     for other in plans(root):
         if other == path:
             continue
@@ -602,9 +631,9 @@ def cmd_phase(args):
     if phase not in tt.TASK_PHASES:
         return problems([bad_phase(phase)])
     root = repo_root(os.getcwd())
-    task = active_here(root)
-    if not task:
-        return problems(["no active task: start one with "
+    task, bad = own_task(root)
+    if bad or not task:
+        return problems([bad or "no active task: start one with "
                          "`tezgah-task start <id> --phase %s`" % phase])
     text = read(task["path"])
     fields = {"phase": phase, "updated": today()}
@@ -614,9 +643,13 @@ def cmd_phase(args):
             fields["allowed_why"] = ""
     granted = (any_path or tt.frontmatter(text).get("allowed_from")
                == ANY_PATH)
-    bad = (scope_problem(phase, task["allowed_paths"], granted)
-           or phase_problems(phase, text, task["path"])
-           or (held_overlap(root, task["id"], []) if any_path else []))
+    # one pre-flight list, not one refusal per attempt: a plan that owes the
+    # scope, the Acceptance and the spike learns all three from one run
+    # (plan 108)
+    bad = list(scope_problem(phase, task["allowed_paths"], granted) or [])
+    bad += phase_problems(phase, text, task["path"])
+    if any_path:
+        bad += held_overlap(root, task["id"], [])
     if bad:
         return problems(bad)
     where = task.get("worktree") or tt.plan_holders(main_root(root)).get(task["id"])
@@ -645,9 +678,9 @@ def cmd_allow(args):
     if not why:
         return misuse("allow takes --why \"<what in the plan reaches these paths>\"")
     root = repo_root(os.getcwd())
-    task = active_here(root)
-    if not task:
-        return problems(["no active task to widen: start one with "
+    task, bad = own_task(root)
+    if bad or not task:
+        return problems([bad or "no active task to widen: start one with "
                          "`tezgah-task start <id> --phase P --allow GLOB`"])
     bad = held_overlap(root, task["id"], args)
     if bad:
@@ -664,12 +697,58 @@ def cmd_allow(args):
     return show(task["path"])
 
 
+def cmd_unmet(args):
+    """Annotate one Acceptance item with `UNMET: <reason, who accepted it>` - the
+    form `close NNN done` accepts in place of a ticked box, and until now the one
+    the CLI could not write: the gate refuses a write to the record, so an item
+    the owner accepted as not met could only be annotated by hand and the plan
+    could not close (plan 110). The record's fifth body writer beside `tick`,
+    `note`, `spike` and `sweep`; it commits nothing."""
+    if len(args) != 3:
+        return misuse('unmet takes <NNN|path> <n> "<reason, who accepted it>"')
+    ref, number, reason = args
+    if not number.isdigit() or int(number) < 1:
+        return misuse("unmet takes the item's number, counted from 1")
+    reason = " ".join(reason.split())
+    if not reason:
+        return misuse("unmet takes the reason, and who accepted it")
+    # the same resolver `tick` and `note` take: `plan_path` accepts any existing
+    # file, which let `unmet README.md 1 x` rewrite a README, and it resolved the
+    # wrong checkout from a linked worktree (review of plan 110, F2)
+    path, problem = open_plan(ref)
+    if problem:
+        return problems([problem])
+    n = int(number)
+    items = tt.acceptance_items(read(path))
+    if n > len(items):
+        return problems(["%s has %d Acceptance item(s), so item %d names none"
+                         % (path, len(items), n)])
+    if items[n - 1]["checked"]:
+        return problems(["%s item %d is ticked already: `UNMET:` is for an item the "
+                         "owner accepted as not met, so untick it first "
+                         "(`tezgah-task tick %s %d --undo`)" % (path, n, ref, n)])
+    if tt._UNMET.search(items[n - 1]["text"]):
+        return problems(["%s item %d carries an `UNMET:` line already (%s)"
+                         % (path, n, items[n - 1]["text"][:64])])
+    try:
+        item = tt.set_unmet(path, n, reason)
+    except OSError as exc:
+        return problems(["cannot write %s: %s" % (path, exc)])
+    if item is None:
+        return problems(["%s has no Acceptance item %d" % (path, n)])
+    bad = write_fields(path, updated=today())
+    if bad:
+        return problems(bad)
+    print("%s: item %d -> UNMET: %s" % (path, n, reason))
+    return 0
+
+
 def cmd_stop(args):
     if args:
         return misuse("stop takes no arguments")
-    task = active_here(repo_root(os.getcwd()))
-    if not task:
-        return problems(["no active task to stop"])
+    task, bad = own_task(repo_root(os.getcwd()))
+    if bad or not task:
+        return problems([bad or "no active task to stop"])
     bad = write_fields(task["path"], phase="", updated=today())
     if bad:
         return problems(bad)
@@ -955,8 +1034,18 @@ def cmd_close(args):
         print(line)
     # the checkout this runs in stays, even when it is a landed plan worktree:
     # removing it would pull the session's own cwd from under it
-    for line in prune_worktrees(root, keep=repo_root(os.getcwd())):
+    pruning = prune_worktrees(root, keep=repo_root(os.getcwd()))
+    for line in pruning:
         print(line)
+    kept = [line for line in pruning
+            if line.startswith(("worktree kept:", "branch kept:"))]
+    if kept:
+        # the reason a checkout stayed goes on the record: printed once, the
+        # next session re-derived the same decision. Written after the move -
+        # the record is in done/ now - and, like the other body writers, this
+        # one commits nothing (plan 108)
+        for line in write_fields(target, worktrees_kept=kept, updated=today()):
+            print(line)
     return 0 if committed else 1
 
 
@@ -1012,7 +1101,41 @@ def commit_close(root, name, message):
 # a test holds a cache.
 REGENERABLE = frozenset(("__pycache__", ".pytest_cache", ".ruff_cache",
                          ".mypy_cache", "node_modules", ".venv", "venv",
-                         ".DS_Store"))
+                         ".DS_Store", ".codegraph"))
+
+
+def _only_copy(path, rel):
+    """The first file under the ignored entry `rel` of worktree `path` that
+    nothing regenerates, or None. tezgah's own agent files (`tezgah-*`, carrying
+    the managed marker) are written again at session start (plan 102); a file
+    beside them is the user's."""
+    from tezgah_agents import MARKER
+    full = os.path.join(path, rel)
+    unread = []  # a directory the walk cannot list holds what it cannot tell
+    walk = ([(os.path.dirname(full), [], [os.path.basename(full)])]
+            if not os.path.isdir(full) or os.path.islink(full)
+            else os.walk(full, onerror=lambda exc: unread.append(exc.filename)))
+    # lazily, stopping at the first file nobody regenerates: an ignored build
+    # tree is walked only as far as its first entry (review of plan 102)
+    for d, dirs, names in walk:
+        dirs.sort()
+        # a link to a directory is a file os.walk does not descend: keep it
+        for name in sorted(names) + [x for x in dirs if os.path.islink(os.path.join(d, x))]:
+            entry = os.path.join(d, name)
+            managed = False
+            # the type before any open: a FIFO blocks open() until a writer comes
+            if name.startswith("tezgah-") and os.path.isfile(entry) \
+                    and not os.path.islink(entry):
+                try:
+                    with open(entry, encoding="utf-8", errors="replace") as fh:
+                        managed = MARKER in fh.read(4096)
+                except OSError:
+                    pass
+            if not managed:
+                return os.path.relpath(entry, path)
+        if unread:
+            return os.path.relpath(unread[0], path)
+    return os.path.relpath(unread[0], path) if unread else None
 
 
 def _landed(root, branch, base):
@@ -1041,10 +1164,16 @@ def _keeps(root, path, branch, bases, agents):
         return "uncommitted changes"
     for line in (git_out(path, "status", "--porcelain", "-unormal", "--ignored") or "").splitlines():
         rel = line[3:].strip('"').rstrip("/")
-        if rel != ".tezgah" and not REGENERABLE & set(rel.split("/")):
-            return "ignored file %s may be the only copy" % rel
+        if rel == ".tezgah" or REGENERABLE & set(rel.split("/")):
+            continue
+        kept = _only_copy(path, rel)
+        if kept:
+            return "ignored file %s may be the only copy" % kept
     ws = os.path.join(path, ".tezgah")
-    if os.path.isdir(ws):
+    # a link to the repository's one workspace (plans 098 and 100) is no data of
+    # the worktree's own: removing the worktree drops only the link
+    if os.path.isdir(ws) and os.path.realpath(ws) != os.path.realpath(
+            os.path.join(root, ".tezgah")):
         if set(os.listdir(ws)) - {".git"}:
             return "its .tezgah holds data"
         if os.path.isdir(os.path.join(ws, ".git")) and git_out(ws, "rev-parse", "-q", "--verify", "HEAD"):
@@ -1081,7 +1210,10 @@ def drop_branch(root, branch):
         return None
     done = subprocess.run(["git", "-C", root, "branch", "-D", branch],
                           capture_output=True, text=True)
-    if done.returncode == 0:
+    # Orca deletes the branch of a checkout it removes: one gone by the time
+    # `-D` ran was deleted, not kept (review of plan 104)
+    if done.returncode == 0 or not git_out(root, "rev-parse", "-q", "--verify",
+                                          "refs/heads/" + branch):
         return None
     return ("branch kept: %s (`git branch -D %s` refused: %s)"
             % (branch, branch, ((done.stderr or "").strip().splitlines() or ["?"])[0]))
@@ -1127,10 +1259,18 @@ def prune_worktrees(root, keep=None):
                 gone = tezgah_orca.run(["worktree", "rm", "--worktree", "path:" + path],
                                        timeout=60) is not None
                 how = "orca worktree rm --worktree path:%s" % path
+                # Orca answers before the directory is gone, and git refuses to
+                # drop a branch a checkout on disk still holds (plan 104)
+                deadline = time.monotonic() + 10
+                while gone and os.path.exists(path) and time.monotonic() < deadline:
+                    time.sleep(0.1)
             else:
                 gone = git_out(root, "worktree", "remove", path) is not None
                 how = "git worktree remove %s" % path
             why = None if gone else "`%s` failed; run it and report its error" % how
+            if gone and os.path.exists(path):
+                why = ("`%s` answered but the checkout is still on disk after 10 s; "
+                       "run close again" % how)
         out.append("worktree %s: %s (%s)" % ("kept" if why else "removed", path,
                                              why or branch))
         if why is None:
@@ -1601,6 +1741,74 @@ def cmd_slice(args):
     return misuse(usage)
 
 
+def orphan_phases(root):
+    """[(path, id, branch)] for phased open plans whose checkout branch is gone.
+    Plan-add declares a branch before creating it, so absence alone is not an
+    orphan: checkpoint, landed or reviewed_sha must show the phase ran in a
+    checkout. A failed git query proves nothing. Query the current refs rather
+    than this sweep's deletions: a checkout may have been removed by hand."""
+    listed = git_out(root, "for-each-ref", "--format=%(refname)", "refs/heads")
+    if listed is None:
+        return []
+    branches = set(listed.splitlines())
+    out = []
+    for path in plans(root):
+        fields = tt.frontmatter(read(path))
+        phase, branch = fields.get("phase") or "", fields.get("branch") or ""
+        if not phase or not branch or not any(fields.get(key) for key in
+                                              ("checkpoint", "landed", "reviewed_sha")):
+            continue
+        if "refs/heads/" + branch not in branches:
+            out.append((path, fields.get("id") or os.path.basename(path).split("-")[0],
+                        branch))
+    return out
+
+
+def cmd_sweep(args):
+    """One idempotent pass over what a session left behind: every pending slice
+    as one line naming its `slice resume` command, the landed worktrees and
+    branches `reconcile --prune` removes, and a `phase:` whose branch is gone. It
+    prints one line per change and closes with the count, so a second run over the
+    same tree reports `0 change(s)`. The pending slices are printed, never
+    touched: resuming one is the session's move, and closing it here would be the
+    forgetting this exists to stop."""
+    if args:
+        return misuse("sweep takes nothing")
+    # the shared checkout: the worktrees and branches this prunes live in the
+    # repository, not in whichever worktree the command ran from
+    root = main_root(repo_root(os.getcwd()))
+    rows = tt.pending(root)
+    for rec in rows:
+        # one line each: the full brief is `slice resume <id>`'s, and a session
+        # coming back to ten dead slices wants the list, not ten briefs
+        print(tt.slice_line(rec))
+    if not rows:
+        print("no open or stopped slice")
+    changed = 0
+    bases = landing_bases(root)
+    for line in prune_worktrees(root, keep=repo_root(os.getcwd())) + prune_branches(root, bases):
+        print(line)
+        # a "kept" line is a report, not a change: a tree holding one long-lived
+        # worktree still has to reach `0 change(s)` on the second run. A slice a
+        # removed worktree closed is one too (review of plan 108).
+        if line.startswith(("worktree removed", "branch deleted", "slice ")):
+            changed += 1
+    for path, ident, branch in orphan_phases(root):
+        # the same empty-value shape `stop` writes, so one parser reads both, and
+        # the same wrapper the other record writers use: a plan that cannot be
+        # written is a problem with the plan, not a traceback (review of plan 108)
+        bad = write_fields(path, phase="", updated=today())
+        if bad:
+            for problem in bad:
+                print("FAIL %s" % problem)
+            continue
+        print("phase cleared: %s (%s no longer exists, so no worktree can move it)"
+              % (ident, branch))
+        changed += 1
+    print("swept: %d change(s)" % changed)
+    return 0
+
+
 def main(argv):
     if len(argv) < 2:
         print(__doc__, file=sys.stderr)
@@ -1626,10 +1834,14 @@ def main(argv):
         return cmd_note(rest)
     if cmd == "spike":
         return cmd_spike(rest)
+    if cmd == "unmet":
+        return cmd_unmet(rest)
     if cmd == "slice":
         return cmd_slice(rest)
+    if cmd == "sweep":
+        return cmd_sweep(rest)
     return misuse("unknown command %r (start, phase, allow, stop, status, review, "
-                  "close, tick, note, spike, slice)" % cmd)
+                  "close, tick, note, spike, unmet, slice, sweep)" % cmd)
 
 
 class ReaderMayLeave:

package/bin/tezgah-taste

@@ -305,7 +305,9 @@ def mine_session(events):
 
 
 def cmd_mine(args):
-    here = (tezgah_paths.linked_main(os.getcwd()) or repo_root(os.getcwd())
+    # sessions run in checkouts, never in a bare repository's git directory
+    main = tezgah_paths.linked_main(os.getcwd())
+    here = ((main and tezgah_paths.work_tree(main)) or repo_root(os.getcwd())
             or os.getcwd())
     root = os.path.abspath(os.path.expanduser(
         args.root or ("~/Projects" if args.all_projects else here)))

package/docs/architecture.md

@@ -187,6 +187,14 @@ the `tezgah-research import` that moves its lines (`hooks/tezgah_context.py::sib
 Session start in a linked worktree makes its `.tezgah` a link to the main one
 (`hooks/tezgah_paths.py::link_workspace`). A relative `.tezgah/...` write lands
 there, and `/.tezgah` goes to the repository's `info/exclude`.
+A bare repository (`app.git`, or `app/.bare` with its worktrees beside it) has no
+main checkout. Its workspace is `<bare git dir>/.tezgah`, a private repository in
+the git directory itself, with no `.gitignore` written there
+(`hooks/tezgah_paths.py::linked_main`, `hooks/tezgah_paths.py::ensure_workspace`).
+Every worktree's `.tezgah` links to it. No `git worktree remove`, detach or
+switch in any worktree takes it, and a plan worktree reads its plan there.
+The git directory holds no project file. A checkpoint, a cited file or an arena
+evaluator is read in the worktree the command runs in (`hooks/tezgah_paths.py::work_tree`).
 A second clone is another repository, with a workspace of its own.
 A path inside `.tezgah` belongs to the repository around it, never to `.tezgah`.
 The workspace keeps its own `.git`, so git's top-level answers `.tezgah` there.

package/docs/clarity-baseline.json

@@ -45,7 +45,7 @@
     "long_sentences": 66,
     "passive": 31,
     "replace_words": 1,
-    "semicolons": 44
+    "semicolons": 43
   },
   "docs/glossary.md": {
     "long_sentences": 51,

package/docs/environment.md

@@ -78,7 +78,7 @@ the kill switches are files, not variables, and live in
 | `TYPESAFE_API_KEY` | `hooks/tezgah_judge.py::key`, `hooks/tezgah_paths.py` | `~/.config/typesafe/key` | The judgement seam's first third-party credential, used as `fallback` in `config.json` allows ([judge](judge.md)); omp also reads it for its own judge. |
 | `OPENROUTER_API_KEY` | `hooks/tezgah_judge.py::openrouter_key`, `bin/consult`, `bin/codegen`, `hooks/tezgah_models.py` | `~/.config/openrouter/key` | The seam's chat fallback, consult's and codegen's `openrouter` provider, and omp's `any` family. |
 | `DEEPSEEK_API_KEY`, `INCEPTION_API_KEY` | `bin/consult`, `bin/codegen`, `hooks/tezgah_replay.py::label_model` | `~/.config/deepseek/key`, `~/.config/inception/key` | The `deepseek` and `inception` providers of consult and codegen; `DEEPSEEK_API_KEY` alone is also the replay sheet's `--provider deepseek` rater. |
-| `ANTHROPIC_OAUTH_TOKEN`, `ANTHROPIC_API_KEY`, `ZAI_API_KEY` | `hooks/tezgah_models.py::OMP_AUTH` | omp's own auth store | Read as presence only: whether omp can run the `anthropic` or `zai` model family, so the model table can pick a row omp will run. |
+| `ANTHROPIC_OAUTH_TOKEN`, `ANTHROPIC_API_KEY`, `ZAI_API_KEY`, `OPENAI_CODEX_OAUTH_TOKEN` | `hooks/tezgah_models.py::OMP_AUTH` | omp's own auth store | Read as presence only: whether omp can run the `anthropic`, `zai` or `openai` model family, so the model table can pick a row omp will run. |
 | `TEZGAH_TYPESAFE_URL` | `hooks/tezgah_judge.py::endpoint` | `https://api.typesafe.ai/v1/systemone` | Repoints the seam's TypeSafe endpoint (tests). Plain `http` is refused unless the host is this machine; a cross-host redirect is refused. |
 | `TEZGAH_OPENROUTER_URL` | `hooks/tezgah_judge.py::openrouter_url` | OpenRouter's chat-completions URL | Repoints the seam's chat fallback (tests). Plain `http` is refused unless the host is this machine. |
 | `TEZGAH_DEEPSEEK_URL` | `hooks/tezgah_replay.py::_deepseek` | `https://api.deepseek.com/chat/completions` | Repoints the replay sheet's `--provider deepseek` rater (tests). Plain `http` is refused unless the host is this machine. |

package/docs/evidence.md

@@ -126,7 +126,7 @@ a write tool is `edit`, a shell call is `verify` when its command matches the ch
 | `refusal` | `stop_reason`, for a blocked reply that claimed nothing - a work-only or a shape refusal - with the same `blocked: <class>` detail (row version 3) | `counters.refusals`, and `shape_blocked` for a shape class; never a claim; `NOT_TOOL_HOOK` lists it |
 | `after_block` | `hooks/tezgah_integrity.py::stop_reason`, on a reply after this rule's own block (a turn holding a `blocked:` claim or refusal row) that is not refused again (`_record_only`) on Claude, Codex, Cursor and omp; `detail` is `would block: <class>`, `ok` or `no claim` | nothing yet: a record for the after-block observation window, not a claim and not a second `shape` row, so `counters` counts it neither as a claim nor as a reply; `NOT_TOOL_HOOK` lists it |
 | `subagent_end` | `stop_reason(..., subagent=True)`, from Claude's SubagentStop (`hooks/hooks.json`) and Cursor's subagentStop `summary`; the evidence half only, never a block (ADR 011); `detail` as `after_block`'s | nothing yet: the rows plan 055 replays before a subagent end may block; `NOT_TOOL_HOOK` lists it. On Claude a subagent's tool rows sit in the parent's ledger, so until the agent key (plan 050) lands the row judges the parent's turn |
-| `stop_spec` | `hooks/tezgah_stopspec.py::shadow`, from `stop_reason`, one per reply that leaves a claim or a refusal row, keyed like the claim row. The `detail` is `agree <where>: <class>`, `disagree <where>: <imperative> -> <spec>` (`ok` for an allow) or `error: <type>`. `<where>` is `fold` when the selector reached the fold and `selector` when it decided alone | `tests/stop_spec_eval.py --shadow-rows`, for plan 063's live agreement bar, read on the `fold` rows. It never feeds the verdict. `NOT_TOOL_HOOK` lists it |
+| `stop_spec` | nothing since plan 101. Plan 063's shadow wrote one per reply that left a claim or a refusal row: `agree`, `disagree` or `error`, and `fold` or `selector`. The fold it compared against is gone | nothing. `NOT_TOOL_HOOK` still lists it and the replay keeps it beside its claim (`hooks/tezgah_replay.py::SIDE_KINDS`), so an old ledger reads as it did |
 | `deny`, `nudge` | the [gate](gate.md)'s `hooks/tezgah_gate.py::_deny`, first-nudge `hooks/tezgah_gate.py::decision` | `hooks/tezgah_integrity.py::counters` |
 | `snapshot`, `rollback` | `hooks/tezgah_snapshot.py::_capture_one`, `hooks/tezgah_snapshot.py::restore` | `hooks/tezgah_integrity.py::_snapshot_hash`; no counter |
 | `compact` | `hooks/tezgah_integrity.py::note_compaction`, from the post-compaction path (`tezgah_context.remember_compaction` `hooks/tezgah_context.py::remember_compaction`) | `hooks/tezgah_integrity.py::_counts` (what `counters` folds with) |
@@ -321,7 +321,7 @@ The first four judge how the reply is written (`_shape_block`, `hooks/tezgah_int
 
 The four shape classes share their switches with the text they enforce: `adhd-off` or a repo's `.no-adhd` lifts 1–3 (`_adhd_armed`, `hooks/tezgah_integrity.py::_adhd_armed`), `exec-mode.off` lifts 4, and a session whose environment carries `TEZGAH_NESTED` (an agent CLI consult started, whose English answer is read by code) is not judged for shape at all. A subagent's reply is never refused: omp's `session_stop` does not fire for task sessions, and a Claude SubagentStop or Cursor subagentStop leaves a record-only `subagent_end` row judged on the evidence half alone (ADR 011). The thresholds were set on the owner's omp transcripts (2026-09-27: 1,495 assistant replies with at least 25 prose words): English prose scored 0.000–0.026, the most English-heavy Turkish reply 0.077 and the bulk 0.3–0.7, and 24 of the 1,495 fall under the cut, all English or Chinese prose. The trade-off is on the Turkish side: a Turkish reply that is mostly quoted English outside backticks can fall under 6%, and the block text tells the model to put the English in backticks or a fence. `tests/test_integrity.py` `ReplyShapeCorpus` pins which realistic replies pass and which block. A lead that announces what follows (`preamble-open`) stays report-only: "Sonuç:" over a list is an answer label and reads like a preamble to any regex.
 
-5. **check failed** — the newest check in the session failed (`hooks/tezgah_integrity.py::_evidence_block`).
+5. **check failed** — the newest check in the session failed (`hooks/tezgah_stopspec.py::verdict`).
 6. **partial failure** — this turn recorded a `verify_fail` and nothing passed since (`hooks/tezgah_integrity.py::_partial_state`).
 7. **no ui_ok** — this turn changed a UI source (`hooks/tezgah_integrity.py::UI_PATH`) and the
    check that passed was not one that sees the screen: a unit run never does. A browser/e2e/visual
@@ -330,7 +330,7 @@ The four shape classes share their switches with the text they enforce: `adhd-of
    CLI capture) is the evidence this class asks for, and it has to be newer than
    the UI write it is about - not than the newest write of anything, so an unrelated file written
    after the screen read does not stale that read (`hooks/tezgah_integrity.py::_ui_evidence`,
-   branch `hooks/tezgah_integrity.py::_evidence_block`). The write kinds are the freshness fold's own (`_change_row`: a write tool's
+   branch `hooks/tezgah_stopspec.py::verdict`). The write kinds are the freshness fold's own (`_change_row`: a write tool's
    `edit` row or a shell call's `run` row the gate saw change the tree), so a UI source written
    through a redirect owes the same proof. The MCP half of that proof is read off the row's own
    tool name (`hooks/tezgah_integrity.py::_screen_read`), which is the only field that
@@ -342,7 +342,7 @@ The four shape classes share their switches with the text they enforce: `adhd-of
    under a component/views/widgets
    directory, or a name that carries the convention on its own), a fresh read of the screen is not
    enough by itself and a `tezgah-design check` row has to be newer than the component write it
-   judges (`hooks/tezgah_integrity.py::_design_evidence`, branch `hooks/tezgah_integrity.py::_evidence_block`) - and it has
+   judges (`hooks/tezgah_integrity.py::_design_evidence`, branch `hooks/tezgah_stopspec.py::verdict`) - and it has
    to be a check whose pass was seen (`passing_check`, `hooks/tezgah_integrity.py::passing_check`), because
    a screenshot says what a component looks like and the contract is the only thing that says whether
    it is on the repository's floor. The refusal names the command to run. Both of the checker's verbs
@@ -351,7 +351,7 @@ The four shape classes share their switches with the text they enforce: `adhd-of
    it. A screen is unchanged: the page a person looks at owes the read, not the contract.
 8. **stale evidence** — the newest check that passed ran before the newest write the gate saw change
    the tree, so it verified an earlier revision of it (`_last_pass`/`_last_change`/`_stale_paths`
-   `hooks/tezgah_integrity.py::_last_pass`, `hooks/tezgah_integrity.py::_last_change`, `hooks/tezgah_integrity.py::_stale_paths`, branch `hooks/tezgah_integrity.py::_evidence_block`). A write counts as a change whether the gate saw it as a
+   `hooks/tezgah_integrity.py::_last_pass`, `hooks/tezgah_integrity.py::_last_change`, `hooks/tezgah_integrity.py::_stale_paths`, branch `hooks/tezgah_stopspec.py::verdict`). A write counts as a change whether the gate saw it as a
    write tool or as a shell command that redirected into the file - `_change_row` (`hooks/tezgah_integrity.py::_change_row`) reads
    an `edit` row, a `run` row whose captured target moved, or a formatter's write mode - while a `verify*` row never does, so
    a check redirecting its own log cannot stale itself. A write *outside* the workspace is not one
@@ -365,10 +365,14 @@ The four shape classes share their switches with the text they enforce: `adhd-of
    change here. A row with no `repo` binds to nothing. That covers an old row and a host that sent
    no cwd. A change with no `target`, such as a shell write, binds to nothing too.
 9. **no verify_ok** — this turn recorded a step (`edit`, `verify`, `verify_fail`, `run`,
-   `interrupted`) and no check passed in the session (`hooks/tezgah_integrity.py::_evidence_block`). A turn with no step at all
+   `interrupted`) and no check passed in the session (`hooks/tezgah_stopspec.py::verdict`). A turn with no step at all
    has only its words as the trigger. There a claim word inside a question or under a negation in
    its own clause is no claim (`asserted_claims`). Examples: "testler geçti mi?", "is it done?",
    "not tested yet", "tamamlandı değil". "Tamamlandı, push edeyim mi?" still claims.
+   A done or tested claim over a check nobody saw pass owes this class too, as a lost call does.
+   That is a `verify_ok` row that is no `passing_check`, such as exit 0 with nothing returned. A
+   work-free turn of one such row used to end on "Tamamlandı, tüm testler geçti" (plan 101,
+   `hooks/tezgah_integrity.py::_stop_block`). A reply with no claim word still ends there.
    A prose edit is no step and no change (`hooks/tezgah_integrity.py::_prose_edit`,
    `hooks/tezgah_integrity.py::_work_row`). Such an `edit` row has a real `target` ending in
    `.md`, `.markdown`, `.rst` or `.adoc`. It owes no check and does not stale a pass. An agent
@@ -379,7 +383,7 @@ The four shape classes share their switches with the text they enforce: `adhd-of
 10. **no external read** — the reply states the state of a system tezgah does not own — a registry,
    a release, a tag, a formula, a CI run — and no read of that system ran in the same turn
    (`hooks/tezgah_integrity.py::_external_claim`, over `EXTERNAL_SYSTEM`/`EXTERNAL_STATE`
-   `hooks/tezgah_integrity.py::EXTERNAL_SYSTEM`, `hooks/tezgah_integrity.py::EXTERNAL_STATE` and the CI pair `EXTERNAL_CI`/`EXTERNAL_CI_STATE` `hooks/tezgah_integrity.py::EXTERNAL_CI`, `hooks/tezgah_integrity.py::EXTERNAL_CI_STATE`; branch `hooks/tezgah_integrity.py::_evidence_block`).
+   `hooks/tezgah_integrity.py::EXTERNAL_SYSTEM`, `hooks/tezgah_integrity.py::EXTERNAL_STATE` and the CI pair `EXTERNAL_CI`/`EXTERNAL_CI_STATE` `hooks/tezgah_integrity.py::EXTERNAL_CI`, `hooks/tezgah_integrity.py::EXTERNAL_CI_STATE`; branch `hooks/tezgah_stopspec.py::verdict`).
    The two halves have to sit within `EXTERNAL_GAP` = 45 characters of each other on one line
    (`hooks/tezgah_integrity.py::_external_pair`), and both are read on the reply's prose with inline code, paths,
    URLs and identifiers blanked: `brew tap` inside a code span, the `.github/workflows/...` in a
@@ -525,27 +529,26 @@ The four shape classes share their switches with the text they enforce: `adhd-of
    transcripts. It refuses once per turn and counts like `residual work`
    (`hooks/tezgah_integrity.py::LIST_BLOCKS`).
 
-Classes 5–10 also exist as a past-time temporal spec (`hooks/tezgah_stopspec.py::FORMULAS`,
+A past-time temporal spec decides classes 5–10 (`hooks/tezgah_stopspec.py::FORMULAS`,
 plan 063). Seven formulas read ten row atoms (`ROW_ATOMS`) and the turn marker. The module compiles
 each formula to a one-pass monitor over the rows (`hooks/tezgah_stopspec.py::compile_table`), and the
-order above is its decision list (`ORDER`). The spec runs in shadow. `stop_reason` asks it after the imperative
-fold, inside its own `try`, when the reply leaves a claim or a refusal row. It writes one `stop_spec` row
-per reply. The row says `agree`, `disagree` or `error`. It also says `fold` when the selector reached
-the fold and `selector` when it decided alone. The verdict stays the imperative one. Both folds share one selector,
-`_stop_block`, through its `fold` argument. It picks the rows, runs the lost-began path and
-refuses "evidence tampered". The admission below and class 11 belong to the selector too. The
-spec's verdict passes through them. `ESCAPES` names the three predicates that read beyond one row: the
+order above is its decision list (`ORDER`, walked by `hooks/tezgah_stopspec.py::verdict`). The spec
+ran in shadow beside the imperative fold until it agreed on every Stop that reached the fold.
+Plan 101 then made it the fold and deleted the imperative one. `_stop_block` calls it as its
+evidence fold (`hooks/tezgah_stopspec.py::fold`), and `hooks/tezgah_integrity.py::_evidence_text`
+words the class it picks with the refusal text. `_stop_block` stays the selector. It picks the
+rows, runs the lost-began path and refuses "evidence tampered". The admission below and class 11
+belong to the selector too. `ESCAPES` names the three predicates that read beyond one row: the
 began-row join, the repository binding and the lost-began set. Plan 063 fixed that list before
-the first shadow row. `TEZGAH_STOPSPEC_STRICT=1` makes a disagreement raise, for the tests.
-`tests/stop_spec_eval.py` measures the bet: agreement on plan 055's replayed Stop events and on
-the live rows, the added latency, and generated mutants of the table.
+the first shadow row. `tests/stop_spec_eval.py --mutants` mutates the table and runs the in-process
+Stop tests against each mutant.
 
 The trigger for 5–9 is the turn's own evidence, not its words: a turn that did work and never saw a
 check pass is refused whatever the reply says (`hooks/tezgah_integrity.py::_stop_block`). Two cases are judged against the
 whole session instead of the turn:
 
 - **A claim in a turn with no work.** A done/tested claim made in a turn that recorded no work row
-  is judged by the same fold as a turn (`_evidence_block`), run over the session rows before
+  is judged by the same fold as a turn (the spec's), run over the session rows before
   this turn (`_before_turn`): every class the turn fold has - `check failed`, `no verify_ok`,
   `stale evidence`, a pending UI or design check, a partial failure - applies to the session too.
   A session that did no work at all still ends, and a turn that ran its own passing check is
@@ -575,7 +578,7 @@ whole session instead of the turn:
 
 What lets the turn end is the absence
 of both — no work row and no claim vocabulary (`hooks/tezgah_integrity.py::_stop_block`), the one shape class 10 is exempt from
-— or a `passing_check` row newer than the newest write seen to change the tree (`hooks/tezgah_integrity.py::_evidence_block`), where
+— or a `passing_check` row newer than the newest write seen to change the tree (`hooks/tezgah_stopspec.py::verdict`), where
 a fresh screen proof stands in the same
 place as a unit pass; when that write was a UI source, the passing row has to be a UI proof — a
 check that renders, or a read of the screen — and when it was a component, the design check has to be