@r1z4x/tezgah 1.5.1 → 1.6.0

package/CHANGELOG.md

@@ -6,6 +6,51 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [1.6.0] - 2026-10-10
+
+### Added
+
+- **A data, metric or dashboard ask reaches the product rule.** "Bu veriye uygun bir metric dashboard tasarla" armed no rule before. A dashboard, chart or metric-choice ask now arms `product`, judged per clause. A code marker in the same clause, such as a metrics endpoint, keeps it out.
+- **product-analysis chooses metrics.** It names a North Star and its input metrics. Each metric gets one record: goal, signal, definition, window, baseline and more.
+- **Dashboard rules in design-contract.** The new `data-views.md` picks the chart for the question. It also sets the context, the window and the widget states.
+- **feature-audit forward mode.** A feature not built yet gets its five matrices in `spec.md`. The audit after the build compares against it.
+- **analyze-app writes the design measurement.** Nothing produced `measurement.json` before. The skill now gives its shape and the snippet that reads it.
+- **The local skill search reaches design-library's entries.** The search now reads the entries a skill's `INDEX.md` lists, one row each.
+- **The product-flow skill and `tezgah-research next`.** A new product capability now runs in a fixed order, from research to re-measure. Each step leaves a file under `.tezgah/analysis/<topic>/`: a `## <step>` note in `flow.md`, or `spec.md` for the forward spec. `tezgah-research next --topic <t>` prints each step's status from those files, and a re-measure is due once the decision's `observe after:` date has passed. It then names the first missing or due step's skill and command. The skill lists the steps, and `FLOWS` in `hooks/tezgah_product.py` holds their done rules.
+
+### Removed
+
+- **The product ledger is cut before release (ADR 025).** Plan 075's measured run did not show the ledger beating the playbook alone. Gone: writing and reading `.tezgah/product/ledger.jsonl`, `tezgah-research record`, `due` and `commit --product`, the ledger part of `check`, `product:` citations and the session-start note on due decisions. An existing `ledger.jsonl` is left in place, and nothing reads it.
+
+### Changed
+
+- **The session runs the plan lifecycle itself.** The gate refused a session's
+  own `tezgah-task start|phase|allow|stop`. It told the session to ask the user,
+  so every plan ended with a command handed back. That refusal is gone. A phase
+  or scope refusal now names the move (`tezgah-task phase implementation`,
+  `tezgah-task allow`). The CLI still checks Acceptance, the spike, the
+  checkpoint and the review on each move. The gate still refuses a write to the
+  plan file itself. `tezgah-task allow` now needs `--why`, and `status` prints
+  the reason next to the widened scope.
+- **`close` cleans up.** `tezgah-task close` on the active task clears its
+  phase instead of refusing. It then removes each linked worktree whose branch
+  has landed and which holds nothing else, through Orca when Orca tracks it. A
+  squash merge counts as landed. A branch whose commits cancel out does not. It
+  prints every worktree it keeps, with the reason. Uncommitted files, unknown
+  ignored files and `.tezgah` data keep a worktree. So do an unmerged branch, a
+  branch nobody committed on, an agent at work and an Orca that does not answer.
+- **No process questions.** The contract says the orchestrator picks a process
+  parameter the user did not set, such as a spend ceiling, and states it.
+  `consult` on exit 4/5 records the first member of another model family
+  itself instead of asking the user to choose. After two review rounds the
+  session fixes what is left and closes with `close NNN done --resolved`. A
+  missing credential sends it to a route that needs none first. A silent gate
+  has it run `tezgah-setup --report` itself.
+
+### Fixed
+
+- **product-analysis no longer says `check` demands three compared solutions.** An analysis answers once. A choice between solutions goes under `decisions/`.
+
 ## [1.5.1] - 2026-10-09
 
 ### Fixed
@@ -981,7 +1026,8 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
   the copy could not find `hooks/` and died on import. It now links into the
   installed tree, and also installs the command as `tezgah`.
 
-[Unreleased]: https://github.com/r1z4x/tezgah/compare/v1.5.1...HEAD
+[Unreleased]: https://github.com/r1z4x/tezgah/compare/v1.6.0...HEAD
+[1.6.0]: https://github.com/r1z4x/tezgah/releases/tag/v1.6.0
 [1.5.1]: https://github.com/r1z4x/tezgah/releases/tag/v1.5.1
 [1.5.0]: https://github.com/r1z4x/tezgah/releases/tag/v1.5.0
 [1.4.0]: https://github.com/r1z4x/tezgah/releases/tag/v1.4.0

package/MANIFEST

@@ -133,6 +133,7 @@ hooks/tezgah_models.py
 hooks/tezgah_orca.py
 hooks/tezgah_paths.py
 hooks/tezgah_policy.py
+hooks/tezgah_product.py
 hooks/tezgah_rank.py
 hooks/tezgah_replay.py
 hooks/tezgah_research.py
@@ -545,6 +546,7 @@ skills/analyze-app/EVALS.md
 skills/analyze-app/SKILL.md
 skills/design-contract/EVALS.md
 skills/design-contract/SKILL.md
+skills/design-contract/data-views.md
 skills/design-library/EVALS.md
 skills/design-library/INDEX.md
 skills/design-library/SKILL.md
@@ -612,6 +614,8 @@ skills/ponytail/EVALS.md
 skills/ponytail/SKILL.md
 skills/product-analysis/EVALS.md
 skills/product-analysis/SKILL.md
+skills/product-flow/EVALS.md
+skills/product-flow/SKILL.md
 skills/research/EVALS.md
 skills/research/SKILL.md
 skills/rl-env/SKILL.md
@@ -733,6 +737,8 @@ tests/test_packaging_scripts.py
 tests/test_paths.py
 tests/test_paths_worktree.py
 tests/test_platform.py
+tests/test_product_flow_e2e.py
+tests/test_product_next.py
 tests/test_providers.py
 tests/test_rank.py
 tests/test_replay.py

package/bin/consult

@@ -56,7 +56,8 @@ suffix); 2 no key for the chosen provider, or no member available at all; 3 the
 --provider/--models run got no answer; 4 no recorded choice - one "offer:" line
 per available member, nothing was asked; 5 every recorded member (and the
 fallback) failed - one "reoffer:" line per member still available that did not
-fail. On 4 or 5, ask the user which to use and record it with --use.
+fail. On 4 or 5, the agent records the first listed member of another model
+family with --use itself and asks again; the user is not asked to choose.
 """
 import concurrent.futures
 import json
@@ -504,11 +505,11 @@ def retry_hint(classes):
         return "the referee answered outside its five headings; re-run, or judge the panel yourself"
     if c == "credit":
         return ("the provider account has no credit (HTTP 402) - the key is fine; "
-                "top it up, or ask the user for another member and record it with --use")
+                "top it up, or record another member with --use")
     if c == "key":
-        return "set the provider's key, or ask the user for another member and record it with --use"
+        return "set the provider's key, or record another member with --use"
     if c == "missing":
-        return "the agent CLI is not installed; ask the user for another member and record it with --use"
+        return "the agent CLI is not installed; record another member with --use"
     if c.startswith("cli-exit"):
         return ("the agent CLI failed (not logged in, or a model name it does not "
                 "know); run it once by hand, or record another member with --use")
@@ -645,8 +646,9 @@ def main():
             print("consult: no recorded choice, so nothing was asked.")
             for opt in found:
                 print(offer_line("offer", opt))
-            print("next: ask the user which of these to use (two or more make a "
-                  "panel), then run: consult --use <member>[,<member>] and ask again")
+            print("next: record the first of these from a model family other than "
+                  "yours (two make a panel) with: consult --use <member>[,<member>], "
+                  "then ask again - do not ask the user to choose")
             sys.stdout.flush()
             os._exit(4)
 
@@ -775,14 +777,15 @@ def main():
         print("retry: %s" % hint)
     code = 0 if answers else 3
     if not answers and not explicit:
-        # The recorded choice is the user's, so consult never swaps it on its
-        # own: it names what is left and the agent asks again.
+        # consult never swaps the recorded choice on its own: it names what is
+        # left, and the agent records the next member and asks again.
         lost = {c[1] for c, _cls in failures} | skip_opts
         left = [o for o in options() if o not in lost]
         for opt in left:
             print(offer_line("reoffer", opt))
-        print("next: ask the user which of these to use instead, then run: "
-              "consult --use <member>[,<member>] and ask again" if left else
+        print("next: record the first of these from another model family with: "
+              "consult --use <member>[,<member>], then ask again - do not ask the "
+              "user to choose" if left else
               "next: nothing else can answer here; tell the user the second "
               "opinion was skipped (install an agent CLI or add a provider key)")
         code = 5

package/bin/tezgah-docs

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

package/bin/tezgah-research

@@ -16,11 +16,17 @@
   tezgah-research source <slug> <hypothesis> --run <orxRunId> [--command "<cmd>"]
                            [--scope real|fixture|derived] [--fixture "<what was generated>"]
   tezgah-research compare <slug> <decision>        record one variants x criteria cell from stdin
+  tezgah-research verdict <slug> <id> met|not-met|unanswerable --evidence "<ref>"
+                                                   record one success criterion's verdict
+  tezgah-research conclude <slug>                  conclude a line whose criteria all carry a verdict
+  tezgah-research migrate-layout                   move flat research/<slug> into open/ or done/
   tezgah-research close <slug> --limit "<reason>"  conclude a line as a deliberate limit
   tezgah-research seal <slug> [--history-lost] --ack "<owner decision>"
                                                    seal a line concluded before seals existed
   tezgah-research import <checkout> [<slug>] [--allow-open "<why>"]
                                                    bring lines from another checkout, with history
+  tezgah-research next --topic <t> [--flow metric-dashboard|feature] [--json]
+                                                   the product-flow steps of a topic and the next one
 
 A research line lives at <repo>/.tezgah/research/<slug>/ and holds the state an
 auditable investigation needs: the question, the decision log, the findings, the
@@ -103,6 +109,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_paths as tp  # noqa: E402
+import tezgah_product as tp_product  # noqa: E402
 import tezgah_research as tr  # noqa: E402
 
 
@@ -245,12 +252,17 @@ def cmd_commit(args):
     known = tr.slugs(repo)
     if slug not in known:
         return misuse("no such research line (have: %s)" % (", ".join(known) or "none"))
+    return commit_path(repo, tr.line_dir(repo, slug), message)
+
+
+def commit_path(repo, path, message):
+    """Stage and commit `path` alone in the private repository of `repo`."""
     ws = tp.ensure_workspace(repo)
     if ws is None:
         print("commit refused: %s is not a git work tree (or .tezgah could not be "
               "set up), so there is no private repository to commit into" % repo)
         return 1
-    rel = os.path.relpath(tr.line_dir(repo, slug), ws)
+    rel = os.path.relpath(path, ws)
     try:
         done = tp.ws_git(repo, "add", "-A", "--", rel)
         if not done.returncode:
@@ -298,6 +310,7 @@ def cmd_check(args):
                 print("warn %s: %s" % (slug, warn))
     else:
         print("no research line under %s" % tr.root(repo))
+    lines = len(report)
     if ask_orx:
         # The registry is the repository's, not a line's, so this runs whatever the
         # lines look like - which is also why it is only asked for when --orx says so.
@@ -313,7 +326,7 @@ def cmd_check(args):
         print(json.dumps(report, indent=2))
         return 1 if problems else 0
     if not problems:
-        print("research: %d line(s) ok" % len(report))
+        print("research: %d line(s) ok" % lines)
     if not rest and not all_lines:
         done = [slug for slug in known if tr.sealed(repo, slug)]
         if done:
@@ -576,6 +589,40 @@ def cmd_compare(args):
     return 0
 
 
+def cmd_next(args):
+    """The product-flow steps of one topic with their status, then the first
+    missing or due step's skill and command; a report, so exit 0."""
+    usage = "next --topic <t> [--flow %s] [--json]" % "|".join(tp_product.FLOWS)
+    opts, as_json, rest = {}, False, list(args)
+    while rest:
+        arg = rest.pop(0)
+        if arg == "--json":
+            as_json = True
+        elif arg in ("--topic", "--flow") and rest and arg not in opts:
+            opts[arg] = rest.pop(0)
+        else:
+            return misuse(usage)
+    flow = opts.get("--flow", "metric-dashboard")
+    if "--topic" not in opts:
+        return misuse(usage)
+    if flow not in tp_product.FLOWS:
+        return misuse("unknown flow %r (%s)" % (flow, ", ".join(tp_product.FLOWS)))
+    topic = opts["--topic"]
+    steps = tp_product.next_steps(repo_root(os.getcwd()), topic, flow)
+    if as_json:
+        # the step list next_steps returns; the next step is its first
+        # missing or due entry
+        print(json.dumps(steps, indent=2))
+        return 0
+    first = next((s for s in steps if s["status"] in ("missing", "due")), None)
+    for n, step in enumerate(steps, 1):
+        print("%d. %s [%s] %s - %s" % (n, step["id"], step["status"], step["skill"],
+                                       step["detail"]))
+    print("next: %s - %s" % (first["skill"], first["command"]) if first
+          else "next: nothing left")
+    return 0
+
+
 def cmd_verdict(args):
     """Record one success criterion's verdict, with the evidence it rests on."""
     if len(args) < 3:
@@ -769,6 +816,8 @@ def main(argv):
         return cmd_source(rest)
     if cmd == "compare":
         return cmd_compare(rest)
+    if cmd == "next":
+        return cmd_next(rest)
     if cmd == "verdict":
         return cmd_verdict(rest)
     if cmd == "conclude":
@@ -782,7 +831,8 @@ def main(argv):
     if cmd == "import":
         return cmd_import(rest)
     return misuse("unknown command %r (init, commit, check, status, --all, claim, predict, "
-                  "components, migrate, source, compare, close, seal, import)" % cmd)
+                  "components, migrate, source, compare, verdict, conclude, migrate-layout, "
+                  "close, seal, import, next)" % cmd)
 
 
 if __name__ == "__main__":

package/bin/tezgah-setup

@@ -187,7 +187,7 @@ OMP_LESSONS = ("Read `.tezgah/lessons.md` in the repository if it exists and tre
 LOCAL_BIN = os.path.join(HOME, ".local", "bin")
 SKILLS = ["harness", "tezgah-contract", "ponytail", "i-have-adhd", "no-ai-slop",
           "analyze-app", "plan-add", "plan-status", "plan-sync", "research",
-          "product-analysis", "feature-audit", "design-contract",
+          "product-analysis", "product-flow", "feature-audit", "design-contract",
           "design-library", "pm-frameworks", "ai-research", "rl-env"]
 
 

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)
@@ -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"]