@r1z4x/tezgah 1.8.3 → 1.9.0

package/hooks/tezgah_task.py

@@ -471,9 +471,10 @@ def parallel(rows):
 
 
 def active(cwd, base, held=False):
-    """The active task as a dict, or None. A linked worktree on a `plan/NNN-...`
-    branch answers plan NNN when that plan carries a phase (`branch_task`), so
-    two plans can run at once, one per worktree. Anywhere else - the main
+    """The active task as a dict, or None. A linked worktree on a branch that
+    binds a plan - `plan/NNN-...` or the plan's declared `branch:` - answers that
+    plan when it carries a phase (`branch_task`), so two plans can run at once,
+    one per worktree. Anywhere else - the main
     checkout, or a worktree on another branch - it reads the main checkout's
     `.tezgah/plans/open/*.md` sorted by name: the first plan carrying a valid
     `phase` that no linked worktree holds (`plan_holders`). When every phased
@@ -498,8 +499,9 @@ def active(cwd, base, held=False):
     main = linked_main(root) or root
     records = _phased(main)
     branches = _worktree_branches(main) if records else {}
+    declared = declared_branches(main) if branches else {}
     for record in records:
-        if not any(_binds(record["id"], b) for b in branches):
+        if not any(_binds(record["id"], b, declared) for b in branches):
             return record
     if not held or not records:
         return None
@@ -570,19 +572,50 @@ def worktree_branch(top):
     return head[len(prefix):] if head.startswith(prefix) else None
 
 
-def plan_of_branch(branch):
-    """The plan id a `plan/NNN-slug` branch names, else None."""
+def declared_branches(main):
+    """{branch: plan id} for every open plan under the main checkout `main` that
+    declares a `branch:` - Orca names a worktree's branch `<user>/<slug>`, and
+    the plan declaring it is the one that worktree holds (plan 105). Read from
+    the plan files' frontmatter, never from git: the gate asks on every write.
+    Two plans declaring one branch: the lowest id binds it, so the answer never
+    depends on which file a directory listing names first."""
+    out = {}
+    for name, _, text in _plan_files(main, "open"):
+        fields = frontmatter(text)
+        branch, ident = fields.get("branch", ""), _plan_id(fields, name)
+        if branch and (branch not in out or ident < out[branch]):
+            out[branch] = ident
+    return out
+
+
+def plan_of_branch(branch, main=None):
+    """The plan id `branch` binds. Without `main` it is the bare parse: NNN for
+    a `plan/NNN-slug` branch, else None. Given the main checkout `main`, it is
+    an open plan's id only: NNN when plan NNN is open there, else the open plan
+    declaring `branch` (`declared_branches`), else None - so `plan/999-nope`
+    binds nothing (review of plan 105, F3). One pass over the open plans."""
     found = _PLAN_BRANCH.match(branch or "")
-    return found.group(1) if found else None
+    if not main:
+        return found.group(1) if found else None
+    declared = None
+    for name, _, text in _plan_files(main, "open") if branch else ():
+        fields = frontmatter(text)
+        ident = _plan_id(fields, name)
+        if found and ident == found.group(1):
+            return ident
+        if fields.get("branch") == branch and (declared is None or ident < declared):
+            declared = ident    # the lowest id, as `declared_branches` picks
+    return declared
 
 
-def _binds(ident, branch):
-    """Does `branch` hold plan `ident`? It has to name the plan: `plan/NNN-...`.
-    A plan's declared `branch:` is one of those, and the slices it fans out to
-    run on others (`plan/097-records` beside `plan/097-workspace-integrity`):
-    each slice is held to its plan's scope, never to another plan's, which is
-    what a first-unheld-plan reading gave it (plan 097, D6)."""
-    return bool(branch) and plan_of_branch(branch) == ident
+def _binds(ident, branch, declared):
+    """Does `branch` hold plan `ident`? It has to name the plan: `plan/NNN-...`,
+    or be the branch the plan declares (`declared`, `declared_branches`'s map).
+    The slices a plan fans out to run on other `plan/NNN-...` branches
+    (`plan/097-records` beside `plan/097-workspace-integrity`): each slice is
+    held to its plan's scope, never to another plan's, which is what a
+    first-unheld-plan reading gave it (plan 097, D6)."""
+    return bool(branch) and (plan_of_branch(branch) or declared.get(branch)) == ident
 
 
 def _worktree_branches(main):
@@ -606,28 +639,30 @@ def plan_holders(main):
     out = {}
     if not branches:
         return out
+    declared = declared_branches(main)
     for name, _, text in _plan_files(main, "open"):
         fields = frontmatter(text)
         ident = _plan_id(fields, name)
-        held = sorted(b for b in branches if _binds(ident, b))
+        held = sorted(b for b in branches if _binds(ident, b, declared))
         if held:
-            declared = fields.get("branch", "")
-            out[ident] = branches[declared if declared in held else held[0]]
+            own = fields.get("branch", "")
+            out[ident] = branches[own if own in held else held[0]]
     return out
 
 
 def branch_task(top):
     """Plan NNN's record (active()'s dict, plus "worktree": `top`, the checkout
     whose HEAD and tree its checkpoint is read against) when `top` is a linked
-    worktree on a `plan/NNN-...` branch (`_binds`) and plan NNN, open under the
-    main checkout, carries a phase. None otherwise - another branch, a plan with
-    no phase, an unknown mapping - and the caller reads the main checkout's task
+    worktree on a branch that binds plan NNN (`plan_of_branch`: `plan/NNN-...`
+    or the plan's declared `branch:`) and plan NNN, open under the main
+    checkout, carries a phase. None otherwise - another branch, a plan with no
+    phase, an unknown mapping - and the caller reads the main checkout's task
     (plan 093)."""
-    ident = plan_of_branch(worktree_branch(top))
-    if ident is None:
-        return None
     from tezgah_paths import linked_main
     main = linked_main(top)
+    ident = plan_of_branch(worktree_branch(top), main)
+    if ident is None:
+        return None
     for record in _phased(main, ident) if main else ():
         record["worktree"] = top
         return record
@@ -636,7 +671,7 @@ def branch_task(top):
 
 def worktree_task(path, cwd, base):
     """The record a write to `path` is held to when it lands in a sibling linked
-    worktree on a plan branch (`branch_task`), else None. A path under cwd's own
+    worktree on a plan's branch (`branch_task`), else None. A path under cwd's own
     root is active()'s to answer, so it pays one realpath and nothing more."""
     root = repo_root(cwd, base)
     path = os.path.expanduser(path)
@@ -883,6 +918,35 @@ def set_box(path, n, checked):
         return items[n - 1]
 
 
+def set_unmet(path, n, reason):
+    """Append `UNMET: <reason>` to the last line of Acceptance item `n` (1-based,
+    as `tick` counts) and return the item, or None when the plan has no item `n`.
+
+    The marker has to land inside the item's own text - `open_items` reads it
+    there, and it is the predicate `close NNN done` refuses on - and an item
+    wraps onto the lines below its box, up to the next item or a blank line, so
+    the anchor is the item's last line and not its first (plan 110). Raises
+    OSError."""
+    with plans_lock(path):
+        lines = _lines(path)
+        items = acceptance_items("\n".join(lines))
+        if not 1 <= n <= len(items):
+            return None
+        end = items[n - 1]["line"] - 1
+        for i in range(end + 1, len(lines)):
+            # the section ends at the next `## ` heading as well, which is where
+            # `acceptance_items` stops: without it an item that ended straight at
+            # a heading swallowed the line under it into the item's own text
+            # (review of plan 110, F1)
+            if (not lines[i].strip() or _ITEM.match(lines[i])
+                    or lines[i].lstrip().startswith("## ")):
+                break
+            end = i
+        lines[end] = lines[end].rstrip() + " UNMET: " + reason
+        _write(path, "\n".join(lines))
+        return acceptance_items("\n".join(lines))[n - 1]
+
+
 def set_section(path, heading, body):
     """Replace the body of the last `## <heading>` section - the newest, since
     a plan appends a dated `## State (...)` - with `body` and one blank line,
@@ -915,10 +979,8 @@ def set_section(path, heading, body):
 
 SLICE_KINDS = ("agent", "job")
 SLICE_HOSTS = ("omp", "claude", "codex", "cursor", "opencode", "dsh")
-# `stale`: no terminal status was observed within SLICE_IDLE_SECONDS - a host
-# that reports none (Codex `spawn_agent` returns at once and tezgah sees no child
-# event) or a child that died without writing its end. It leaves the pending
-# list without being read as finished or as failed.
+# `stale`: an idle background job whose result stays in its parent transcript.
+# An agent with no observed end stays owed as stopped with no failure class.
 SLICE_STATUSES = ("open", "done", "stopped", "resumed", "stale")
 SLICE_CLOSED = ("done", "stopped", "resumed", "stale")
 SLICE_IDLE_SECONDS = 6 * 3600
@@ -1372,11 +1434,12 @@ def open_slice(root, sid, *, kind="agent", host="", agent="", brief="", parent="
         # prompt and Stop - never globs (40 ms on 1393 project dirs, measured)
         rec["transcript_dir"] = _omp_session_dir(rec["parent"]) or ""
     # the slice's own plan: the review guard reads its own plan's records only.
-    # Its worktree's plan branch, else the plan its task or shared brief names,
-    # else the tag a re-open already carries, else the task the main checkout
-    # reads - with two plans running that is only one of them
+    # Its worktree's plan branch (`plan/NNN-...` or a plan's declared one), else
+    # the plan its task or shared brief names, else the tag a re-open already
+    # carries, else the task the main checkout reads - with two plans running
+    # that is only one of them
     named = _BRIEF_PLAN.search(own) or _BRIEF_PLAN.search(brief or "")
-    rec["plan"] = (plan_of_branch(rec.get("branch")) or (named and named.group(1))
+    rec["plan"] = (plan_of_branch(rec.get("branch"), main) or (named and named.group(1))
                    or rec.get("plan") or (active(main, main) or {}).get("id") or "")
     rec.update(base=_git(main, "rev-parse", "HEAD") or "", status="open",
                failure="", updated=now)
@@ -1649,8 +1712,9 @@ def pending(root):
     omp record still open whose child transcript has ended is closed first:
     stopped with its failure class, or done when it ended normally. An open
     record nothing has moved for SLICE_IDLE_SECONDS (an omp child's transcript
-    included) - or a `job` past SLICE_JOB_SECONDS - closes `stale`. One stat and
-    at most one SLICE_TAIL read per open omp record."""
+    included) closes stopped with no failure class; only a `job` past
+    SLICE_JOB_SECONDS closes stale. One stat and at most one SLICE_TAIL read per
+    open omp record."""
     out = []
     for rec in slices(root):
         if rec.get("status") != "open":
@@ -1680,7 +1744,12 @@ def pending(root):
                 except OSError:
                     pass
         if rec.get("status") == "open" and idle is not None and idle > limit:
-            rec = close_slice(root, rec["id"], "stale") or rec
+            # A job's result stays in its parent transcript; an agent with no
+            # observed end stays stopped and offered for resume. Unknown is not
+            # cut_off: slice_stats skips a class it cannot name, so signature
+            # counts go quiet for hosts whose ends tezgah cannot observe.
+            job = rec.get("kind") == "job"
+            rec = close_slice(root, rec["id"], "stale" if job else "stopped", "") or rec
         if rec.get("status") in ("open", "stopped"):
             out.append(rec)
     return out

package/hosts/opencode/plugins/tezgah.js

@@ -3201,3 +3201,139 @@ export const Tezgah = async ({ directory }) => {
     // (TEZGAH_STATUS_BIN) is the safe path today.
   }
 }
+
+// opencode 2 validates a plugin module's DEFAULT export: an object with a string
+// `id` and a `setup(ctx)` that registers hooks through the v2 context - it calls
+// nothing else, so a module with only the callable above is rejected at load
+// with `PluginModule.LoadError: Plugin must export a default definition with an
+// id and an effect or setup function` (measured on opencode v2.0.30, and the
+// reason the host showed both entrypoints as failed plugins). opencode 1 calls
+// the exported callable and uses the hook map it returns. One file serves both,
+// as the sibling plugin on this machine does
+// (~/.config/opencode/plugins/orca-opencode-status.js).
+//
+// v2 merged the v1 `input` and `output` objects into ONE mutable event
+// (services/www/src/docs/content/build/plugins/migrate-v1.mdx), so the adapter
+// passes the event as the v1 `input` and rebuilds the v1 `output` field the v1
+// callback reads (`args` from `output.args`). The fields below are the ones a
+// probe plugin measured on opencode v2.0.30: `execute.before` carries
+// {tool, sessionID, agent, messageID, id, input}. A refusal is a thrown Error in
+// both generations and the v1 callback already throws it, so the deny path is
+// the same object and no decision is rewritten here.
+//
+// Registered in this piece: the tool envelopes (the enforcement path), the shell
+// env hook, the session prompt and the event subscription. permission/evaluate,
+// the compaction hook and the TUI plugin still need their own probe of the v2
+// event before they are registered - guessing a field there would silently drop a
+// decision.
+export default {
+  id: "tezgah",
+
+  async setup(ctx) {
+    const directory = (ctx.location && ctx.location.directory) || process.cwd()
+    const hooks = await Tezgah({ directory })
+    // The same double-load guard the callable keeps: opencode 1 and 2 both scan
+    // `plugin/` and `plugins/`, and the second instance returns no hook map. A
+    // registration without a hook would raise at load and fail the whole plugin,
+    // which is the one state this file must never reach.
+    if (!hooks || typeof hooks !== "object") return
+
+    const before = hooks["tool.execute.before"]
+    if (typeof before === "function") {
+      await ctx.tool.hook("execute.before", (event) =>
+        before(event, { args: event && event.input }))
+    }
+
+    const after = hooks["tool.execute.after"]
+    if (typeof after === "function") {
+      await ctx.tool.hook("execute.after", (event) => {
+        // On the "error" status the v2 event carries a Tool.Error, not a
+        // result object, so the v1 labels (labelResult) and rows
+        // (recordEvidence) have no carrier for a failed call: skipped, not
+        // faked. On "completed" it translates onto the v1 pair: the callback
+        // reads `tool` and `sessionID` from its input, `args` from
+        // `input.args` and the result from its second argument, which it
+        // labels in place.
+        if (event && event.status === "completed")
+          after({ sessionID: event.sessionID, tool: event.tool,
+                  args: event.input }, event.result)
+      })
+    }
+
+    const chatMessage = hooks["chat.message"]
+    if (typeof chatMessage === "function" && ctx.session && ctx.session.hook) {
+      // v2 hands the plugin `{sessionID, messageID, prompt: {text, files}}` and
+      // gives it no parts array, while the v1 callback reaches the model by
+      // pushing a synthetic text part. So the adapter builds the v1 `parts`
+      // array from the prompt text, runs the same callback, and appends whatever
+      // it pushed to the v2 prompt text: the reminder lands in the message either
+      // way, and the decision (which rule it arms) is the callback's own.
+      await ctx.session.hook("prompt", async (event) => {
+        if (!event) return
+        const prompt = event.prompt || (event.prompt = {})
+        const parts = [{ type: "text", text: String(prompt.text || "") }]
+        await chatMessage({ sessionID: event.sessionID, messageID: event.messageID },
+                          { parts, message: { id: event.messageID, sessionID: event.sessionID } })
+        const extra = parts.slice(1).map((p) => p && p.text).filter(Boolean).join("\n")
+        if (extra) prompt.text = (prompt.text ? prompt.text + "\n" : "") + extra
+      })
+    }
+
+    const shellEnv = hooks["shell.env"]
+    if (typeof shellEnv === "function") {
+      // v2's shell event carries `env` in place, and v1's callback fills
+      // `output.env`, so one object serves both roles. The session id sits under
+      // `metadata` at runtime rather than on the event, and the v1 callback reads
+      // `input.sessionID`, so it is lifted where it exists (review of plan 111,
+      // F3): a shell event with neither skips the session variable, as it did
+      // before.
+      await ctx.shell.hook("create.before", (event) => shellEnv(
+        Object.assign({}, event,
+                      { sessionID: event.sessionID || (event.metadata && event.metadata.sessionID) }),
+        event))
+    }
+
+    // The v1 `event` hook joins a subagent's ledger to its parent's on
+    // `session.created`, and v2 delivers host events through a subscription
+    // rather than a callback, so this block consumes it.
+    if (typeof hooks.event === "function" && ctx.event && ctx.event.subscribe) {
+      // v2's subscription returns an async iterable of {type, data} and never
+      // calls a callback - the sibling plugin consumes it with `for await` - so
+      // this reads it the same way and hands the v1 callback the shape it reads
+      // (`input.event`, with the v1 `properties`). The loop runs for the life of
+      // the plugin; a failed subscription costs the v1 event hook and nothing
+      // else. Review of plan 111, F1.
+      const consume = async () => {
+        // `await` because the subscription may hand back a promise of the
+        // iterable: `for await` takes the iterable itself, and on a promise it
+        // throws where a bare `catch` would hide it (review of plan 111, F1).
+        for await (const input of await ctx.event.subscribe({})) {
+          if (!input || !input.type) continue
+          try {
+            await hooks.event({ event: { type: input.type, properties: input.data } })
+          } catch {}
+        }
+      }
+      consume().catch(() => {})
+    }
+
+    // Not registered on v2, each with its reason rather than a stub:
+    //
+    // `permission.ask` - the v1 callback decides from the call's tool and its
+    // args (`permissionToolArgs`: metadata.tool, metadata.pattern, the pattern
+    // list), and v2's evaluate event carries `action`, `resources`, `metadata`
+    // and `source` instead; whether the host fills `metadata` with the tool and
+    // the pattern is unverified, and a wrong reading there would deny a call the
+    // before-hook allows. The same decisions are already enforced by
+    // `tool.execute.before`, which is registered above and runs on every call,
+    // so nothing is left unenforced - only the redundancy is dropped.
+    // `experimental.session.compacting` - v1 reaches the model by mutating
+    // `output.parts`; v2's compaction event carries `messages` and a
+    // `result = {summary}` to set, so this is a different hook, not a rename.
+    // `config` - v1 mutates one global config object to register the repository's
+    // generated subagents; v2 has no global config and registers them through
+    // `ctx.agent.transform`, which needs the agents' own shape.
+    // The TUI plugin (`hosts/opencode/tui/`) has its own v2 definition to port.
+  },
+}
+

package/output-styles/tezgah.md

@@ -66,7 +66,9 @@ examples. 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.
+ask is a floor, not a ceiling - its kind is one: a research, analysis, review or
+plan ask ends at the written plan, and building it waits for the user's answer.
+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
@@ -110,7 +112,8 @@ lines: item - blocker - evidence - what unblocks it. No blockers: no heading.
 Work and process - the order, "shall I go on", a check, a plan, a consult
 member, a spend within `spend_cap`, a local merge of the session's branch,
 removing its worktree - are taken and stated in one line, never asked; a taste
-or intent fork goes in the batch with a default taken this turn. An outward step
+or intent fork goes in the batch with a default taken this turn, but building a
+plan this turn wrote waits for the answer. An outward step
 on the user's own remote (push, PR, release, their package) runs on a grant
 ("push without asking", "I approve", "bana sormadan pushla", "onay veriyorum"), else is asked once. Never on a
 default - ask and wait for an answer naming action and target: a force push,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@r1z4x/tezgah",
-  "version": "1.8.3",
+  "version": "1.9.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": {

package/skills/plan-add/SKILL.md

@@ -96,14 +96,18 @@ Input: `$ARGUMENTS` (free text describing the work). Run these steps in order.
    the scope with `tezgah-task allow <glob> ... --why "<reason>"`, which records the reason. Never retype the record:
    the gate refuses a write to it, because the CLI's checks would be skipped.
    Tick an Acceptance box with `tezgah-task tick NNN <n>` (`--undo` unticks),
-   rewrite State or Next with `tezgah-task note NNN state|next "<text>"`, and
+   rewrite State or Next with `tezgah-task note NNN state|next "<text>"`,
    record the spike's answer with `tezgah-task spike NNN "<answer>"`, which
-   writes `spike_recorded:` on the plan, active or not. These three work from
-   the main checkout or from any of its worktrees.
+   writes `spike_recorded:` on the plan, active or not, and annotate an item the
+   owner accepted as not met with `tezgah-task unmet NNN <n> "<reason, who
+   accepted it>"`, which writes `UNMET:` and is the form `close done` takes in
+   place of a tick. These four work from the main checkout or from any of its
+   worktrees.
    After the merge, `tezgah-task close NNN done` deactivates the plan,
    moves it to done and removes every merged worktree. It refuses while an
    Acceptance box is open: tick it, or, only when the owner accepted the item
-   as not met, end it with `UNMET: <reason, who accepted it>`.
+   as not met, end it with `tezgah-task unmet NNN <n> "<reason, who accepted
+   it>"`, which writes the `UNMET:` line and leaves the box open.
 
 10. If the work settles a decision that is hard to reverse, spans components, or
     keeps being re-explained, record it as an ADR under `.tezgah/decisions/` with

package/skills/tezgah-contract/SKILL.md

@@ -266,6 +266,20 @@ code-discovery brief names codegraph's tools (`codegraph callers`, `callees`,
 the graph, grep only for literal text"; never a grep-only explorer (observed).
 Subagents never orchestrate: no nested harnesses, no sub-subagents.
 
+### The verification batch: `tezgah-optimize`
+`~/.config/tezgah/bin/tezgah-optimize next [--files PATH ...]` answers, per command
+the active plan's Acceptance names, one of `run now`, `defer` or `already green` -
+the first from no measurement or a median below the in-turn bar, the second from a
+median at or above it, the third from a green row recorded for the same sha. The
+router calls it at a phase move and before it spends a check the same change
+already passed, and calls `push` once at the end of a step instead of pushing
+every iteration: a build or a CI run paid once per attempt is the cost this
+decides. `record <command> --seconds N --exit N` is how a measurement gets in, so
+the session that runs a check hands the number back. The tiers are measured, not
+declared, so a project that never adopted this repository's `AGENTS.md` still gets
+a batch. See `docs/testing.md` and, for the decision behind it, the research line
+`tezgah-optimization`.
+
 ### Tier 2 - codegen (cheap model via OpenRouter)
 `~/.config/tezgah/bin/codegen "task" --files a.py b.py` drafts a bounded edit on a cheap model
 (override with --model or CODEGEN_MODEL) for a fraction of the cost. On Claude