@r1z4x/tezgah 1.5.0 → 1.6.0

package/bin/tezgah-task

@@ -3,18 +3,19 @@
 
   tezgah-task start <NNN|path> --phase P [--allow GLOB ... | --any-path]   activate a plan
   tezgah-task phase P [--any-path]                            change the active task's phase
-  tezgah-task allow GLOB ... | --any-path                     replace the allowlist
+  tezgah-task allow GLOB ... | --any-path --why REASON         replace the allowlist, recording why
   tezgah-task stop                                            deactivate (clear phase)
   tezgah-task status [--json]                                 the active task, then every open plan: progress, what it waits on, what can run at once
   tezgah-task review <NNN|path> <reviewer> approve|changes    record a fresh review's verdict
-  tezgah-task close <NNN|path> done|discarded                 move a plan to .tezgah/plans/done
+  tezgah-task close <NNN|path> done|discarded [--resolved TEXT] move a plan to .tezgah/plans/done, deactivate it, remove merged worktrees
 
 The record is the plan file itself: `phase:` activates it, `allowed_paths:` is
 the scope a write has to stay inside, and at most one open plan carries a phase
-because `start` clears the others. That makes the gate's refusal a rule the user
-set in advance, so this CLI is the only writer and the agent never runs its
-first four commands - `stop` and a hand edit are equally valid ways to take the
-requirement away. `phase implementation` (or `verification`) is what lets a write
+because `start` clears the others. The orchestrating session runs every command
+here itself as the work moves - the lifecycle is never handed back to the user -
+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.
 
 The allowlist is the plan's own: plan-add writes `allowed_paths:` when it
@@ -22,16 +23,24 @@ creates the plan, and `start` without `--allow` keeps it. A writing phase with
 no allowlist is refused unless `--any-path` says so explicitly, and the record
 keeps where its scope came from (`allowed_from:`), which `status` prints.
 
-`review` and `close` are the session's: the verification phase asks for one
-review of the plan's whole diff, `review` records its verdict as
+The verification phase asks for one review of the plan's whole diff: `review`
+records its verdict as
 `review: <reviewer> <verdict> <date>` together with `reviewed_sha:` (the
 project's HEAD it read) and `review_round:`, so the next round reads only
 `git diff <reviewed_sha>..HEAD`, and refuses a third round: the budget is two
 rounds per plan; `close NNN done` refuses a plan whose review is missing or not
-`approve`. `close` refuses the active task - that one is the user's to stop first.
+`approve`, unless both rounds are spent and `--resolved` records the fix the
+session made and the test that proves it. `close` on the active task clears its phase in the same write, then
+removes each linked worktree whose branch has landed in HEAD, `main`, `master`
+or the remote's default branch (an ancestor of it, or a squash whose merge
+would change nothing) and which holds nothing else (no uncommitted or unknown
+ignored file, no `.tezgah` data, a branch someone committed on, no Orca agent
+still at work; Orca down keeps them all); every worktree it keeps is printed
+with the reason.
 
 Two things the plan owes are asked here, at the only moment they can still be
-fixed - the phase move - because the record is the user's and the refusal is
+fixed - the phase move - because this CLI is the record's only writer and the
+refusal is
 this CLI's: a writing phase needs every Acceptance item to name the command
 proving it (or say `unverifiable` and why), since the report CI runs afterwards
 refuses an open plan on any one item that does neither, through the same
@@ -161,11 +170,13 @@ def allow_source(text):
     `--allow`/`allow` (`allowed_from:` names which), or an explicit
     `--any-path`. No list and no `--any-path` is what a writing phase refuses."""
     allow = tt.allowed_paths(text)
-    source = tt.frontmatter(text).get("allowed_from") or ""
+    fields = tt.frontmatter(text)
+    source = fields.get("allowed_from") or ""
+    why = (" (why: %s)" % fields["allowed_why"]) if fields.get("allowed_why") else ""
     if allow:
-        return allow, ("from tezgah-task %s" % source) if source else "from the plan"
+        return allow, (("from tezgah-task %s" % source) + why) if source else "from the plan"
     if source == ANY_PATH:
-        return allow, "any path in the repo (--any-path)"
+        return allow, "any path in the repo (--any-path)" + why
     return allow, "any path in the repo (no allowlist)"
 
 
@@ -285,9 +296,9 @@ def phase_problems(phase, text, path):
     Both are read from the plan this CLI is about to move, through the same
     readers the CI report uses, so the phase the gate then holds a write to is a
     phase the plan can actually be checked in. They live here, at the phase move,
-    and not in the gate: the phase has one writer, this command, and the record
-    is the user's to write - a gate rule would have to re-read the same body on
-    every write to ask a question whose answer changes only here."""
+    and not in the gate: the phase has one writer, this command - a gate rule
+    would have to re-read the same body on every write to ask a question whose
+    answer changes only here."""
     out = []
     if phase in tt.WRITE_PHASES:
         items = tt.acceptance_gap(text)
@@ -329,8 +340,8 @@ def verification_steps(text, path):
     the budget `review` enforces."""
     fields = tt.frontmatter(text)
     ident = fields.get("id") or os.path.basename(path).split("-")[0]
-    # every item, not only the ones the command reader recognises: `pnpm test`
-    # carries no option or path and would otherwise vanish from the list
+    # every item, not only the ones the command reader recognises: a bare
+    # `pytest` is a command it does not read as one, and must not vanish here
     items = ["%s%s" % (i["text"], "" if i["state"] == "checkable" else
                        "  [%s]" % ("unverifiable" if i["state"] == "unverifiable"
                                    else "names no command"))
@@ -356,9 +367,10 @@ def verification_steps(text, path):
         return
     if rounds >= REVIEW_ROUNDS:
         print("  2. the %d-round budget is spent: `tezgah-task review` refuses a "
-              "third round. A critical or major finding still confirmed goes to "
-              "the user (block); a minor or suggestion one is recorded fix-later "
-              "under the plan's ## State" % REVIEW_ROUNDS)
+              "third round. Fix a critical or major finding still confirmed "
+              "yourself, prove it with a test and close with `--resolved`; a "
+              "minor or suggestion one is recorded fix-later under the plan's "
+              "## State" % REVIEW_ROUNDS)
         return
     if rounds:
         print("  2. review round 2 (the last): each confirmed critical or major "
@@ -443,10 +455,10 @@ def cmd_start(args):
         return problems([problem])
     text = read(path)
     fields = {"phase": phase, "updated": today()}
-    if allow:
-        fields.update(allowed_paths=allow, allowed_from="--allow")
-    elif any_path:
-        fields.update(allowed_paths=[], allowed_from=ANY_PATH)
+    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"):
+            fields["allowed_why"] = ""  # the reason belonged to the scope replaced
     else:
         # the plan's own scope, as plan-add wrote it (or an earlier --allow)
         allow = tt.allowed_paths(text)
@@ -489,6 +501,8 @@ def cmd_phase(args):
     fields = {"phase": phase, "updated": today()}
     if any_path:
         fields.update(allowed_paths=[], allowed_from=ANY_PATH)
+        if tt.frontmatter(text).get("allowed_why"):
+            fields["allowed_why"] = ""
     granted = (any_path or tt.frontmatter(text).get("allowed_from")
                == ANY_PATH)
     bad = (scope_problem(phase, task["allowed_paths"], granted)
@@ -503,6 +517,13 @@ def cmd_phase(args):
 
 
 def cmd_allow(args):
+    # the scope is the session's to widen, so the reason is the price: a widening
+    # nobody can read back later is the unbounded task this record exists to stop
+    why = ""
+    if "--why" in args:
+        i = args.index("--why")
+        why = " ".join((args[i + 1:i + 2] or [""])[0].split())
+        args = args[:i] + args[i + 2:]
     any_path = ANY_PATH in args
     args = [a for a in args if a != ANY_PATH]
     for arg in args:
@@ -510,6 +531,8 @@ def cmd_allow(args):
             return misuse("allow takes globs, not %r" % arg)
     if bool(args) == any_path:
         return misuse("allow takes globs, or --any-path alone to lift the scope")
+    if not why:
+        return misuse("allow takes --why \"<what in the plan reaches these paths>\"")
     task = active_here(repo_root(os.getcwd()))
     if not task:
         return problems(["no active task to widen: start one with "
@@ -519,7 +542,8 @@ def cmd_allow(args):
     # the way back out of a scope that turned out to be too narrow. A flag and
     # not an empty call, so lifting the scope is always said out loud.
     bad = write_fields(task["path"], allowed_paths=args, updated=today(),
-                       allowed_from=ANY_PATH if any_path else "allow")
+                       allowed_from=ANY_PATH if any_path else "allow",
+                       allowed_why=why)
     if bad:
         return problems(bad)
     return show(task["path"])
@@ -546,13 +570,14 @@ def review_verdict(text):
 
 
 def budget_spent(path, ident):
-    """The refusal once REVIEW_ROUNDS rounds are recorded: what is left belongs
-    to the user, never to a third round."""
-    return ("%s has spent its %d-round review budget: never a third round. A "
-            "critical or major finding still confirmed goes to the user, who "
-            "decides (block); a minor or suggestion one is recorded fix-later "
-            "under the plan's ## State; `tezgah-task close %s discarded` needs no "
-            "review" % (path, REVIEW_ROUNDS, ident))
+    """The refusal once REVIEW_ROUNDS rounds are recorded: never a third round,
+    and never a hand-off - the session settles what is left itself."""
+    return ("%s has spent its %d-round review budget: never a third round. Fix a "
+            "critical or major finding still confirmed yourself and prove it with "
+            "a test, then `tezgah-task close %s done --resolved \"<the fix and the "
+            "test that proves it>\"`; record a minor or suggestion one fix-later "
+            "under the plan's ## State; `close %s discarded` needs no review"
+            % (path, REVIEW_ROUNDS, ident, ident))
 
 
 def cmd_review(args):
@@ -583,8 +608,15 @@ def cmd_review(args):
 
 
 def cmd_close(args):
+    resolved = ""
+    if "--resolved" in args:
+        i = args.index("--resolved")
+        resolved = " ".join((args[i + 1:i + 2] or [""])[0].split())
+        args = args[:i] + args[i + 2:]
+        if not resolved:
+            return misuse("--resolved takes the fix and the test that proves it")
     if len(args) != 2 or args[1] not in ("done", "discarded"):
-        return misuse("close takes <NNN|path> done|discarded")
+        return misuse("close takes <NNN|path> done|discarded [--resolved TEXT]")
     root = repo_root(os.getcwd())
     path, problem = plan_path(root, args[0])
     if problem:
@@ -593,18 +625,26 @@ def cmd_close(args):
         return problems(["%s is not under %s" % (path, open_dir(root))])
     text = read(path)
     ident = os.path.basename(path).split("-")[0]
+    # closing the active task deactivates it in the same write: the plan leaves
+    # open/ anyway, and a separate `stop` first was one more step for nobody
+    fields = {"status": args[1], "updated": today()}
     if tt.frontmatter(text).get("phase"):
-        return problems(["%s is the active task: the user stops it first "
-                         "(`tezgah-task stop`)" % path])
+        fields["phase"] = ""
     if args[1] == "done" and review_verdict(text) != "approve":
         prior = tt.frontmatter(text).get("review_round") or ""
-        if prior.isdigit() and int(prior) >= REVIEW_ROUNDS:
+        spent = prior.isdigit() and int(prior) >= REVIEW_ROUNDS
+        if spent and resolved:
+            # the budget is spent and the session fixed what was left: the fix
+            # and its proof go on the record a later reader rejects it from
+            fields["resolved"] = "%s %s" % (resolved, today())
+        elif spent:
             return problems([budget_spent(path, ident)])
-        return problems(["%s records no approving review: a fresh reviewer reads "
-                         "the diff, then `tezgah-task review %s <reviewer> approve`"
-                         % (path, ident)])
+        else:
+            return problems(["%s records no approving review: a fresh reviewer reads "
+                             "the diff, then `tezgah-task review %s <reviewer> approve`"
+                             % (path, ident)])
     target = os.path.join(root, ".tezgah", "plans", "done", os.path.basename(path))
-    bad = write_fields(path, status=args[1], updated=today())
+    bad = write_fields(path, **fields)
     if bad:
         return problems(bad)
     try:
@@ -613,9 +653,122 @@ def cmd_close(args):
     except OSError as exc:
         return problems(["cannot move %s: %s" % (path, exc)])
     print("moved %s -> %s" % (path, target))
+    for line in prune_worktrees(root):
+        print(line)
     return 0
 
 
+# Ignored output a slice regenerates on its own. Any other ignored path - an
+# `.env`, a local database, a dataset - may be the only copy, so it keeps the
+# worktree; a list rather than `--ignored` alone because every checkout that ran
+# a test holds a cache.
+REGENERABLE = frozenset(("__pycache__", ".pytest_cache", ".ruff_cache",
+                         ".mypy_cache", "node_modules", ".venv", "venv",
+                         ".DS_Store"))
+
+
+def _landed(root, branch, base):
+    """True when `branch`'s work is in `base`: an ancestor of it, or - for a
+    squash or rebase merge, which leaves no ancestry - a branch whose merge into
+    `base` would change nothing. `merge-tree --write-tree` needs git 2.38; an
+    older git answers None, which reads as not landed and keeps the worktree."""
+    if git_out(root, "merge-base", "--is-ancestor", branch, base) is not None:
+        return True
+    # a branch whose commits cancel out (X then revert X) merges to base's tree
+    # too, while its commits are in base nowhere: it needs a net change to count
+    fork = git_out(root, "merge-base", base, branch)
+    if not fork or git_out(root, "diff", "--quiet", fork, branch) is not None:
+        return False
+    merged = (git_out(root, "merge-tree", "--write-tree", base, branch) or "").split("\n")[0]
+    return bool(merged) and merged == git_out(root, "rev-parse", base + "^{tree}")
+
+
+def _keeps(root, path, branch, bases, agents):
+    """Why the linked worktree `path` must stay, or None when its work is all in
+    `bases` and it holds nothing else. Every question git cannot answer keeps it."""
+    if not branch:
+        return "detached HEAD"
+    # -unormal: a `status.showUntrackedFiles=no` config would hide both lists
+    if git_out(path, "status", "--porcelain", "-unormal") != "":
+        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
+    ws = os.path.join(path, ".tezgah")
+    if os.path.isdir(ws):
+        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"):
+            return "its .tezgah has commits"
+    if not any(_landed(root, branch, b) for b in bases):
+        return "%s is not merged into %s" % (branch, " or ".join(bases))
+    log = git_out(root, "reflog", "show", "--format=%gs", "refs/heads/" + branch) or ""
+    if not any(entry.startswith(("commit:", "commit (amend):", "commit (initial):"))
+               for entry in log.splitlines()):
+        # a branch nobody committed on is a slice that has not started - even
+        # one fast-forwarded to main, or one that only cherry-picked or merged
+        # main in - not one whose work landed
+        return "%s has no commit of its own yet" % branch
+    busy = [a.get("state") for a in agents if a.get("state") != "done"]
+    if busy:
+        return "an agent there is %s" % busy[0]
+    return None
+
+
+def prune_worktrees(root):
+    """Remove every linked worktree of the repository whose branch has landed and
+    which holds nothing else, so a closed plan leaves no checkout behind; one line
+    per linked worktree, removed or kept with the reason. The main checkout and
+    the one `close` runs in always stay. Under Orca the removal is Orca's (its
+    card, terminals and merged branch go with it), else `git worktree remove`
+    and a safe `git branch -d`. When Orca is installed but does not answer, its
+    agents cannot be checked, so every worktree stays."""
+    import tezgah_orca
+    from tezgah_paths import worktrees
+    found = worktrees(root)
+    here = os.path.realpath(root)
+    linked = [p for p in found[1:] if p != here]
+    if not linked:
+        return []
+    ps = tezgah_orca.run(["worktree", "ps", "--limit", "1000"])
+    rows = ps.get("worktrees") if isinstance(ps, dict) else None
+    if not isinstance(rows, list) and tezgah_orca.cli():
+        # down, or an answer in a shape this reader does not know: either way
+        # its agents cannot be checked
+        return ["worktree kept: %s (Orca did not answer, so its agents cannot be "
+                "checked; run close again once `orca worktree ps` answers)" % p
+                for p in linked]
+    orca = {os.path.realpath(r.get("path") or ""): r for r in rows or []
+            if isinstance(r, dict)}
+    # the remote's default branch too: a PR merged on the host lands there first
+    bases = [b for b in ("HEAD", "main", "master", "origin/HEAD", "origin/main",
+                         "origin/master")
+             if git_out(root, "rev-parse", "-q", "--verify", b)]
+    out = []
+    for path in linked:
+        branch = git_out(path, "symbolic-ref", "-q", "--short", "HEAD")
+        try:
+            why = _keeps(root, path, branch, bases,
+                         orca.get(path, {}).get("agents") or [])
+        except OSError as exc:
+            why = "cannot read it: %s" % exc
+        if why is None:
+            if path in orca:
+                gone = tezgah_orca.run(["worktree", "rm", "--worktree", "path:" + path],
+                                       timeout=60) is not None
+                how = "orca worktree rm --worktree path:%s" % path
+            else:
+                gone = git_out(root, "worktree", "remove", path) is not None
+                how = "git worktree remove %s" % path
+                if gone:
+                    git_out(root, "branch", "-d", branch)
+            why = None if gone else "`%s` failed; run it and report its error" % how
+        out.append("worktree %s: %s (%s)" % ("kept" if why else "removed", path,
+                                             why or branch))
+    return out
+
+
 def cmd_status(args):
     as_json = "--json" in args
     rest = [a for a in args if a != "--json"]

package/docs/architecture.md

@@ -34,7 +34,7 @@ nothing about a host's event names or output envelope.
 | `tezgah_paths.py` | where tezgah is armed: [roots](glossary.md#root) and the linked worktrees of a repository under one, kill switches, the config dir, and the writable cache dir - the fallback resolved on use rather than at import, so a gated call does not pay for `tempfile`, `shutil` or `sqlite3` | `hooks/tezgah_paths.py:2-14`, `hooks/tezgah_paths.py::cache_dir`, `hooks/tezgah_paths.py::fallback_cache` |
 | `tezgah_snapshot.py` | pre-write bytes of every file a write is about to change, and the one explicit restore | `hooks/tezgah_snapshot.py:2-18`, `hooks/tezgah_snapshot.py::capture` |
 | `tezgah_untrusted.py` | the untrusted-content label on a result from outside the user and workspace, and the taint notice on the next effect | `hooks/tezgah_untrusted.py:2-22`, `hooks/tezgah_untrusted.py::marks` |
-| `tezgah_agents.py` | per-repo subagent definitions generated into each host that has an agent surface | `hooks/tezgah_agents.py:2-22`, `hooks/tezgah_agents.py::sync_root` |
+| `tezgah_agents.py` | subagent definitions generated into each host that has an agent surface: user-level for Claude, Codex and omp (written at install), per repo for Cursor and opencode | `hooks/tezgah_agents.py:2-30`, `hooks/tezgah_agents.py::sync_root`, `hooks/tezgah_agents.py::user_agents` |
 | `tezgah_research.py` | the in-repo research workspace and the check that a protocol predates its results | `hooks/tezgah_research.py:2-85`, `hooks/tezgah_research.py::check` |
 | `tezgah_index.py` | the detached graph auto-index worker (flock-guarded, bounded retry) | `hooks/tezgah_index.py:2-18`, `hooks/tezgah_index.py::main` |
 

package/docs/citations-baseline.json

@@ -21,7 +21,7 @@
     "unjudged": 2
   },
   "docs/gate.md": {
-    "unjudged": 40
+    "unjudged": 39
   },
   "docs/glossary.md": {
     "unjudged": 12

package/docs/clarity-baseline.json

@@ -42,10 +42,10 @@
     "semicolons": 11
   },
   "docs/gate.md": {
-    "long_sentences": 67,
-    "passive": 32,
+    "long_sentences": 66,
+    "passive": 31,
     "replace_words": 1,
-    "semicolons": 45
+    "semicolons": 44
   },
   "docs/glossary.md": {
     "long_sentences": 51,
@@ -72,7 +72,7 @@
     "semicolons": 6
   },
   "docs/models.md": {
-    "long_sentences": 19,
+    "long_sentences": 18,
     "passive": 8,
     "replace_words": 0,
     "semicolons": 9

package/docs/contract.md

@@ -276,7 +276,10 @@ sentence of the rule.
 
 `PROMPT_HINTS` (`hooks/tezgah_context.py::PROMPT_HINTS`) is one compiled pattern per key
 — `spec`, `consult`, `research`, `product`, `graph`, `fanout` — and `classify_prompt()` returns the keys
-a prompt matches (`hooks/tezgah_context.py::classify_prompt`). `fanout` arms on the
+a prompt matches (`hooks/tezgah_context.py::classify_prompt`). It also adds `product`
+for a data ask: a dashboard, a chart or a metric to choose. The check reads each
+clause on its own (`hooks/tezgah_context.py::_data_ask`). A code marker in that
+clause keeps the ask out: a file name, an identifier, SQL or a build word. `fanout` arms on the
 shape of the request, not a word. Two list entries on their own lines arm it.
 An entry starts with `1.`, `1)`, `1 -`, `1:`, `a)` or a bullet. An inline
 `1. ... 2. ...` arms it too. So do three files named as one list, "First, ...

package/docs/feature-audit.md

@@ -1,7 +1,8 @@
 # Feature audit: one feature, every layer
 
 Audience: the agent and the maintainer answering "why does this screen do that"
-or "make this feature better" on an existing product surface.
+or "make this feature better" on an existing product surface. It also serves
+whoever specifies a feature before the build.
 
 A screen review judges what is on the screen. Most of what goes wrong in a real
 feature is not on the screen: it is a disagreement between two layers - the surface
@@ -20,7 +21,7 @@ sourced to WAI-ARIA APG and WCAG 2.2.
 It is reached the same way `product-analysis` is: the `product` task class arms the
 rule (`hooks/tezgah_context.py::PROMPT_HINTS`), whose coherence paragraph
 (`hooks/tezgah_policy.py::CORE`) names the feature unit and the matrices, and
-`skills/product-analysis/SKILL.md:51` runs the coherence pass before its axes.
+`skills/product-analysis/SKILL.md:74` runs the coherence pass before its axes.
 `skills/tezgah-contract/SKILL.md:725-737` carries the long form for a session that
 reads the contract.
 
@@ -38,6 +39,24 @@ step flow, a notification. It is not a form-only method.
 | Interaction dependency | the controls whose change alters another's valid set | dependents, required action on change, state owner, announcement | a stale dependent value; a silent reset; a filter showing a state the view no longer has |
 | Surface pattern | the controls, data views, flows and notifications | the decidable rule, with its source | a combobox with no expanded state; a results count announced nowhere; a destructive confirmation that hides what it destroys |
 
+## Forward mode: the spec before the build
+
+For a feature that does not exist yet, fill the five matrices from the decision
+first. They go into `.tezgah/analysis/<feature>/spec.md` before the build. Mark a
+cell the decision leaves open, and ask it. Never guess it.
+
+After the build, run the normal audit and compare it with `spec.md` row by row.
+Every disagreement is a finding. Examples: a capability no layer delivers, a field
+no view renders, a missing state, an unasked layer. The method lives
+in `skills/feature-audit/SKILL.md`, "Forward mode".
+
+The decision the spec builds from is the one written under `## decision` in
+`.tezgah/analysis/<topic>/flow.md`. `spec.md` names it, and so does the audit
+after the build. The `product-flow` skill orders the steps around the audit:
+`tezgah-research next --topic <t>` reads the forward spec as done once `spec.md`
+exists (`hooks/tezgah_product.py::next_steps`). See "The next step of a product
+flow" in `docs/research.md`.
+
 ## The gate that makes it more than advice
 
 A finding whose fix names a layer that does not exist yet is not a UI finding. It
@@ -128,7 +147,7 @@ rubric, then three passes of the feature-audit skill:
 ## Source of truth
 
 - `skills/feature-audit/SKILL.md` - the method: the five matrices, the proposal
-  gate, the per-surface rule table and the hand-check list
+  gate, the forward-mode spec, the per-surface rule table and the hand-check list
 - `skills/product-analysis/SKILL.md` - the coherence pass and the artifact element
   that carries the matrices
 - `hooks/tezgah_context.py` - `PROMPT_HINTS`, whose `product` alternation carries
@@ -137,3 +156,5 @@ rubric, then three passes of the feature-audit skill:
   `skills/tezgah-contract/SKILL.md` as its long form
 - `tests/test_context.py`, `tests/test_setup.py` - the arming table and the router
   line that pin the wiring
+- `skills/product-flow/SKILL.md` and `hooks/tezgah_product.py::FLOWS` - the step
+  order around the forward spec and the audit, printed by `tezgah-research next`

package/docs/gate.md

@@ -93,7 +93,7 @@ It reads the arguments of `touch`, `rm`, `rmdir`, `unlink`, `mv`, `chmod`, `mkdi
 It reads the value of `cp -t`, `curl -o`, `wget -O`, `tar -C` on extraction and `unzip -d` (`OPTION_TARGETS`). It expands `~`, `$HOME` and the XDG
 variables first. It follows a `cd` within the line and reads past `if`/`then`/`do`/`!`/`{`. It opens `eval` and `bash -c`, and any flag cluster holding
 `c` is `-c`. A path counts as written and with its last link resolved. A quoted word is a word, so a grep or a commit message that names a switch passes. `SHELL_WRITE` stays as it was: it feeds the
-task phase rule and the opencode mirror. The task CLI stays the task rule's (below), so `task-off` still removes all of that rule. Told: what the call would
+task phase rule and the opencode mirror. The task CLI is not a control-plane target: the session runs it itself (see the task rule below). Told: what the call would
 change, and that the user changes it in their own terminal (`CONTROL_DENY` `hooks/tezgah_gate.py::CONTROL_DENY`). The text names no command. Standing. No switch
 but `pretooluse-off` removes the rule, and that switch is a protected file. The rule cannot tell a change the user asked for from one the agent chose. It
 refuses both inside the session, and it never sees the user's own terminal. Plan 050's replay of three weeks of real ledgers found the two evidence-only
@@ -159,22 +159,21 @@ Scratch is skipped: a temp file or a device (`hooks/tezgah_integrity.py::scratch
 Told: re-read the file and re-apply the change to what is on disk now (`RACE_DENY`
 `hooks/tezgah_gate.py::RACE_DENY`). Standing (`RACE_REFUSE = True` `hooks/tezgah_gate.py::RACE_REFUSE`) — a notice would not close a silent overwrite — and it lifts only by time.
 
-### Task — the user's own phase and path allowlist
+### Task — the active plan's phase and path allowlist
 
 Trigger: a write tool, or a shell command that writes a file, while an active task is set — a plan file under `.tezgah/plans/open` whose frontmatter carries a valid
 `phase` (`tezgah_task.active`). The phase refuses a write in a reading phase (`hooks/tezgah_gate.py::TASK_PHASE_DENY`) and a shell command that writes one (`hooks/tezgah_gate.py::TASK_SHELL_DENY`,
-against `hooks/tezgah_gate.py::SHELL_WRITE`); the allowlist refuses a target outside it (`hooks/tezgah_gate.py::TASK_SCOPE_DENY`) — a write tool's path, and a shell command's redirect or `tee` target (`hooks/tezgah_gate.py::write_paths`); and the record itself is refused twice over — a write whose target IS it, by a write tool or a shell redirect/`tee`
-(`hooks/tezgah_gate.py::TASK_RECORD_DENY`) and a shell command that would change it through the CLI, named by its basename with or without `.py` (`hooks/tezgah_gate.py::TASK_UNLOCK_DENY`, matched on the masked text by `hooks/tezgah_gate.py::TASK_CHANGE`). Told:
-none of them names the command that lifts it, on purpose — with the unlock printed, an armed arm removed or disabled the gate in 25 of 25 runs and obeyed it in none
-(`hooks/tezgah_gate.py:882-886`) — so each names the phase or the allowlist as the user's to change. Standing: only the record changing lifts it.
+against `hooks/tezgah_gate.py::SHELL_WRITE`); the allowlist refuses a target outside it (`hooks/tezgah_gate.py::TASK_SCOPE_DENY`) — a write tool's path, and a shell command's redirect or `tee` target (`hooks/tezgah_gate.py::write_paths`); and a write whose target IS the record, by a write tool or a shell redirect/`tee`, is refused
+(`hooks/tezgah_gate.py::TASK_RECORD_DENY`), because only `bin/tezgah-task` writes it and that CLI makes the checks a retyped frontmatter would skip. Told:
+the move that lifts it, made by the session itself — `tezgah-task phase implementation` or `tezgah-task allow <glob> ... --why "<reason>"` — since the orchestrator owns the plan lifecycle and the CLI refuses
+the move until the plan's Acceptance, spike and checkpoint are in order, and records the reason for a widened scope (`allowed_why:`). Standing: only the record changing lifts it.
 Scratch meets no allowlist: a temp file or a device, such as `pytest > /tmp/check.log` (`hooks/tezgah_gate.py::task_reason`). Build output inside the repo stays held. Off: `task-off`
-(`hooks/tezgah_gate.py::decision`). It fails open wherever the question cannot be answered: no active task, no readable record; the record is written by `bin/tezgah-task` and
-never by the agent, so this rule refuses on a decision the user made rather than one the gate inferred.
+(`hooks/tezgah_gate.py::decision`). It fails open wherever the question cannot be answered: no active task, no readable record.
 
-The fifth refusal under the same rule is the checkpoint. Trigger: a write, or a shell command that writes a file (`hooks/tezgah_gate.py::SHELL_WRITE`), while the task is in
+The fourth refusal under the same rule is the checkpoint. Trigger: a write, or a shell command that writes a file (`hooks/tezgah_gate.py::SHELL_WRITE`), while the task is in
 `phase: implementation`, its record reads `checkpoint: pending <sha>`, that sha is still the checkout's HEAD and the tree is dirty (`checkpoint_reason()`
 `hooks/tezgah_gate.py::checkpoint_reason`, `hooks/tezgah_gate.py::CHECKPOINT_DENY`). Told: the task it read, that the record holds a `pending` checkpoint, and the one command
-that makes the boundary real - unlike the refusals above it names that command, because running it *satisfies* the rule rather than taking it off. Standing: the recorded sha is the switch, not the tree - the commit
+that makes the boundary real - it names that command because running it *satisfies* the rule rather than taking it off. Standing: the recorded sha is the switch, not the tree - the commit
 the refusal names moves HEAD off that sha, so the refusal clears itself, where keying on the word `pending` alone left the phase waiting on a record only
 `bin/tezgah-task` rewrites. Off, with the rest of the rule: `task-off`. It fails open wherever the question cannot be answered: no record, no `checkpoint:` key, a
 checkpoint that is a plain sha (the boundary is already real), a `pending` with no sha, a sha this checkout's HEAD does not name, and a repo whose HEAD cannot be read.
@@ -236,7 +235,7 @@ tail still shows that failure, under `verify-off` (`hooks/tezgah_gate.py::decisi
 ### Loop — the identical attempt that already failed twice
 
 Trigger: the same call (same `call_id`) failed `LOOP_ATTEMPTS = 2` times already in the current user turn (`hooks/tezgah_gate.py::LOOP_ATTEMPTS`, `hooks/tezgah_gate.py::loop_reason`). Told: attempt N
-of an identical call, the failure class read from the ledger (`transient`, `user`, `permanent`, `unknown`; the cap is the same for every class, and a `user` failure - a 401/403, a missing credential, a login - says to ask the user), "change the approach or stop" (`hooks/tezgah_gate.py::loop_reason`). Standing while the ledger tail still shows those
+of an identical call, the failure class read from the ledger (`transient`, `user`, `permanent`, `unknown`; the cap is the same for every class, and a `user` failure - a 401/403, a missing credential, a login - says to take a route that needs no credential first and ask the user once only when none is left), "change the approach or stop" (`hooks/tezgah_gate.py::loop_reason`). Standing while the ledger tail still shows those
 failures. Under `verify-off` (`hooks/tezgah_gate.py::decision`).
 
 ### Retry — the session-wide ceiling

package/docs/hosts.md

@@ -71,6 +71,8 @@ shared config, contract hash and the CLI symlinks every host shell can call
   `~/.claude/settings.json` - `statusLine` (`bin/tezgah-setup::wire_claude_statusline`) and the attribution
   off-switch (`bin/tezgah-setup::wire_claude_attribution`) - and the always-on block in
   `~/.claude/CLAUDE.md` (`CLAUDE_RULES`), Claude's own user-level memory file.
+  The subagent roles go to `~/.claude/agents/tezgah-*.md`
+  (`bin/tezgah-setup::write_user_agents`).
   Its hook manifest is the plugin's own
   `hooks/hooks.json`; no `hooks.json` is written into `~/.claude`. Claude runs a
   **copy** of the checkout under `~/.claude/plugins/cache`, refreshed by
@@ -84,6 +86,8 @@ shared config, contract hash and the CLI symlinks every host shell can call
   (one group per event, PreToolUse carrying `CODEX_PRETOOL_MATCHER` at `bin/tezgah-setup::CODEX_PRETOOL_MATCHER`),
   `skills/*` symlinks, `~/.codex/bin/consult`, and `mcp_servers.*` tables in
   `config.toml` (`ensure_toml_mcp`, `bin/tezgah-setup::ensure_toml_mcp`).
+  The subagent roles go to `$CODEX_HOME/agents/tezgah-*.toml`
+  (`bin/tezgah-setup::write_user_agents`).
 - **cursor** - `install_cursor` (`bin/tezgah-setup::install_cursor`): `~/.cursor/hooks.json`
   (tezgah entries replaced, a user's Orca entries merged), `skills/*` symlinks,
   `mcp.json` servers, and `cli-config.json` `statusLine`.
@@ -159,6 +163,11 @@ and drops the later ones.
 | skills | codex | `.agents/skills` from the cwd up to the repo root, `~/.agents/skills`, `$CODEX_HOME/skills`; one name in two dirs is listed twice, not merged | links in `$CODEX_HOME/skills` |
 | skills | cursor | `.agents/skills`, `.cursor/skills`, `~/.agents/skills`, `~/.cursor/skills`, then Claude's and Codex's project and user dirs; no documented winner | links in `~/.cursor/skills` |
 | skills | opencode | its own skill tool is denied; the router lists `~/.config/opencode/skills`, `~/.claude/skills`, `~/.agents/skills`, first wins (`bin/tezgah-setup::skill_groups`) | links and the router |
+| agents | claude | managed, the `claude --agents` flag, `.claude/agents`, `~/.claude/agents`, plugin agents namespaced `plugin:name`; a dir absent at start is not watched | `~/.claude/agents`, written at install |
+| agents | codex | `$CODEX_HOME/agents`, `/etc/codex/agents`, `.codex/agents` (trusted repos only), read at config load | `$CODEX_HOME/agents`, written at install |
+| agents | cursor | `cursor-agent`: `.cursor/agents`, then `.claude/agents`, `.grok/agents`, plugin agents; first name wins; no user dir; read at process start. The editor's docs add `~/.cursor/agents` and `~/.claude/agents` | `.cursor/agents` per repo at session start, in the CLI's line format (`hooks/tezgah_agents.py::render_md_cursor`) |
+| agents | opencode | `~/.config/opencode/agents`, `.opencode/agents`, merged per field | `config` hook injection, `.opencode/agents` as fallback |
+| agents | omp | `.omp/agents`, `~/.omp/agent/agents`, extensions, bundled | `~/.omp/agent/agents`, written at install |
 | hooks | claude | user `settings.json` rows (Orca's), project rows, the plugin's `hooks/hooks.json` (tezgah's); every matching row runs, none is ordered before another | plugin rows |
 | hooks | codex, cursor | `hooks.json` array order, then the repo's `.codex/` or `.cursor/hooks.json`; Codex runs a row only once its hash is trusted | own rows after Orca's |
 | hooks | opencode | every `*.js`/`*.ts` in `plugins/` and `plugin/`; `tezgah.js` is linked into both, and its `globalThis.__tezgahPluginLoaded` guard makes the second load return `{}` | the plugin |