@r1z4x/tezgah 1.6.0 → 1.7.0

package/bin/tezgah-task

@@ -8,6 +8,16 @@
   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 [--resolved TEXT] move a plan to .tezgah/plans/done, deactivate it, remove merged worktrees
+  tezgah-task tick <NNN|path> <n> [--undo]                   tick (or untick) Acceptance item n, counted from 1
+  tezgah-task note <NNN|path> state|next "<text>"            replace the body of `## State` (the newest one) or `## Next`
+  tezgah-task slice open --id ID [--kind agent|job] [--host H] [--agent A] [--brief TEXT|--brief-file F] [--parent P] [--cwd PATH]
+                                                              record a delegated slice (a re-open counts one more attempt)
+  tezgah-task slice done ID | slice stop ID [--class C]      close a slice record
+  tezgah-task slice reconcile [--prune]                       every open or stopped slice with its resume brief; --prune also removes landed worktrees and branches
+  tezgah-task slice resume ID                                 the native resume path, else a re-dispatch brief; marks the record resumed
+  tezgah-task slice stats [--window DAYS] [--json]            counts per status, failure class and host, and the RSI lever candidates
+  tezgah-task slice board [--parent P]                        the open sibling slices: what each owns, its worktree, branch and last commit
+  tezgah-task slice merge-plan [--base REF]                   the done slice branches in merge order, with their forecast conflicts
 
 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
@@ -17,6 +27,9 @@ and this CLI is the record's only writer: the gate refuses a write to the plan
 file, because the checks below are made here and a retyped frontmatter would
 skip them. `phase implementation` (or `verification`) is what lets a write
 through, so the phase changes when the work reaches that point and not before.
+`tick` and `note` are the record's body writers for the same reason: they write
+an Acceptance box or the State/Next text on any open plan, active or not, keep
+the frontmatter but `updated:`, and commit nothing.
 
 The allowlist is the plan's own: plan-add writes `allowed_paths:` when it
 creates the plan, and `start` without `--allow` keeps it. A writing phase with
@@ -61,6 +74,30 @@ still HEAD and the tree is still dirty, so committing is the whole way out of it
 and the commit clears the refusal by itself; the per-file snapshots
 (bin/tezgah-rollback) are not one state to return to.
 
+`slice` keeps the slice journal (hooks/tezgah_task.py): one record per delegated
+slice under `.tezgah/slices/` of the main checkout, opened by the post-tool path
+on a spawn call or by `slice open`, so a parent crash, an omp `/clear`, a quota
+stop or a model or host switch loses no slice. `reconcile` reads each open omp
+record's child transcript and closes the ones that ended, then prints one
+resume brief per open or stopped slice; `--prune` first runs the same worktree
+removal `close` does, deletes (`git branch -d`) every local branch that has
+landed and is checked out nowhere - never main, master or the current branch -
+and marks done each record whose branch landed with a commit of its own.
+`resume` prints the host's native path first (omp `write agent://<id>` while
+the parent session lives, Claude `SendMessage`), then a brief any host or model
+can re-dispatch: the original brief plus the last commit, the branch and the
+uncommitted files. `stats` flags a `class+host` signature at 3 events, or at 5%
+of a window holding 20 or more slices, and names its lever from a closed set.
+`board` lists the open slices one parent spawned - the session's own, or for a
+subagent its parent's - with the `Owns:` globs of each brief (the lease the
+gate holds siblings to), worktree, branch and last commit. `merge-plan` forecasts
+each done slice branch against `--base` (HEAD) and against the others with `git
+merge-tree`, leaves out a `merge=union` file such as CHANGELOG.md, and orders
+them with a branch touching MANIFEST or the citation baseline last, then fewest
+conflicts first; a branch merge-tree cannot forecast (git before 2.38, no shared
+history) is printed as `not judged` and the exit is 1. `review ... approve`
+is refused while a record whose id or agent is that reviewer is not done.
+
 Exit codes: 0 ok, 1 a refusal or a problem - one `FAIL <what>` line per problem,
 with nothing written - 2 misuse.
 """
@@ -75,6 +112,7 @@ import time
 HERE = os.path.dirname(os.path.dirname(os.path.realpath(__file__)))
 sys.path.insert(0, os.path.join(HERE, "hooks"))
 import tezgah_task as tt  # noqa: E402
+from tezgah_paths import say  # noqa: E402
 
 
 def repo_root(path):
@@ -331,6 +369,18 @@ def changed_lines(root, base):
     return sum(int(n) for n in re.findall(r"(\d+) (?:insertion|deletion)", stat))
 
 
+# The checks deferred out of the turn to the merge step (AGENTS.md "Checks, by
+# tier"): (the file that marks the repo has it, the command), in run order.
+MERGE_CHECKS = (
+    ("tests/impacted.py", "python3 tests/impacted.py --all"),
+    ("tests/neuter_matrix.py", "TEZGAH_E2E_STRICT=1 python3 tests/neuter_matrix.py"),
+    ("bin/tezgah-docs", "python3 bin/tezgah-docs --citations"),
+    ("bin/tezgah-docs", "python3 bin/tezgah-docs --clarity"),
+    ("skills/plan-add/render_table.py",
+     "python3 skills/plan-add/render_table.py --acceptance --strict"),
+)
+
+
 def verification_steps(text, path):
     """What the verification phase requires before the plan is done: the plan's
     own acceptance commands run once on the final tree, unpiped, and ONE review
@@ -358,8 +408,12 @@ def verification_steps(text, path):
           "no state go out as tool calls in ONE message, one suite run at a time:")
     for item in items or ["(the plan has no Acceptance items)"]:
         print("     - %s" % item)
-    if os.path.isfile(os.path.join(root, "tests", "impacted.py")):
-        print("     the one full run here is `python3 tests/impacted.py --all`")
+    # the deferred tier: never inside a turn, run once here at the merge step
+    deferred = [cmd for rel, cmd in MERGE_CHECKS
+                if os.path.isfile(os.path.join(root, rel))]
+    if deferred:
+        print("     the merge step's one run of the deferred checks: %s"
+              % ", ".join("`%s`" % c for c in deferred))
     if rounds and review_verdict(text) == "approve":
         print("  2. the review approved in round %d at %s: no further round"
               % (rounds, reviewed))
@@ -368,9 +422,10 @@ def verification_steps(text, path):
     if rounds >= REVIEW_ROUNDS:
         print("  2. the %d-round budget is spent: `tezgah-task review` refuses a "
               "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)
+              "yourself, prove it with a test and close with `--resolved`; fix a "
+              "minor or suggestion one now, or record it fix-later under the "
+              "plan's ## State only when it waits on a user decision (%s)"
+              % (REVIEW_ROUNDS, say()["decision"]))
         return
     if rounds:
         print("  2. review round 2 (the last): each confirmed critical or major "
@@ -392,8 +447,10 @@ def verification_steps(text, path):
               "security reviewer" % (REVIEW_ROUNDS, base, SMALL_DIFF,
                                      "unknown" if size is None else size))
         print("     only a confirmed critical or major finding is `changes` and "
-              "opens round 2; a minor or suggestion one is recorded fix-later "
-              "under ## State and the verdict is `approve`")
+              "opens round 2; a minor or suggestion one is fixed in the session "
+              "without a new round, or recorded fix-later under ## State only "
+              "when it waits on a user decision (%s), and the verdict is "
+              "`approve`" % say()["decision"])
     print("  3. record its verdict: `tezgah-task review %s <reviewer> approve|changes`"
           " (records the reviewed sha);"
           " `tezgah-task close %s done` refuses without an approve" % (ident, ident))
@@ -418,7 +475,7 @@ def cmd_start(args):
     if not args:
         return misuse("start needs a plan id or path")
     root = repo_root(os.getcwd())
-    path, problem = plan_path(root, args[0])
+    path, problem = open_plan(args[0])
     phase = None
     allow = []
     any_path = False
@@ -562,6 +619,70 @@ def cmd_stop(args):
     return show(task["path"])
 
 
+def open_plan(ref):
+    """(path, problem) for a plan under `.tezgah/plans/open/`: `tick` and `note`
+    write past the gate, so they take no other file (review of plan 083, F4:
+    `note README.md next ...` rewrote any markdown file with a Next section)."""
+    root = repo_root(os.getcwd())
+    path, problem = plan_path(root, ref)
+    if problem:
+        return None, problem
+    if os.path.dirname(os.path.realpath(path)) != os.path.realpath(open_dir(root)):
+        return None, "%s is not an open plan under %s" % (path, open_dir(root))
+    return path, None
+
+
+def cmd_tick(args):
+    """Tick (or `--undo` untick) one Acceptance box: the plan's progress is the
+    session's to record, and the gate refuses a direct write to the record."""
+    undo = "--undo" in args
+    args = [a for a in args if a != "--undo"]
+    if len(args) != 2 or not args[1].isdigit():
+        return misuse("tick takes <NNN|path> <n> [--undo]")
+    path, problem = open_plan(args[0])
+    if problem:
+        return problems([problem])
+    items = tt.acceptance_items(read(path))
+    n = int(args[1])
+    if not 1 <= n <= len(items):
+        return problems(["%s has %d Acceptance items, not an item %d"
+                         % (path, len(items), n)])
+    item = items[n - 1]
+    try:
+        tt.set_box(path, item["line"], not undo)
+    except OSError as exc:
+        return problems(["cannot write %s: %s" % (path, exc)])
+    bad = write_fields(path, updated=today())
+    if bad:
+        return problems(bad)
+    print("- [%s] %s" % (" " if undo else "x", item["text"]))
+    return 0
+
+
+NOTE_SECTIONS = {"state": "State", "next": "Next"}
+
+
+def cmd_note(args):
+    """Replace the plan's `## State` (the newest one) or `## Next` body."""
+    if len(args) != 3 or args[1] not in NOTE_SECTIONS or not args[2].strip():
+        return misuse('note takes <NNN|path> state|next "<text>"')
+    path, problem = open_plan(args[0])
+    if problem:
+        return problems([problem])
+    heading = NOTE_SECTIONS[args[1]]
+    try:
+        found = tt.set_section(path, heading, args[2])
+    except OSError as exc:
+        return problems(["cannot write %s: %s" % (path, exc)])
+    if not found:
+        return problems(["%s has no `## %s` section" % (path, heading)])
+    bad = write_fields(path, updated=today())
+    if bad:
+        return problems(bad)
+    print("%s: ## %s updated" % (path, heading))
+    return 0
+
+
 def review_verdict(text):
     """The verdict of the plan's `review: <reviewer> <verdict> <date>` line, or
     None when it has none or names a verdict this CLI does not write."""
@@ -575,15 +696,59 @@ def budget_spent(path, ident):
     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))
+            "test that proves it>\"`; fix a minor or suggestion one now, or record "
+            "it fix-later under the plan's ## State only when it waits on a "
+            "user decision (%s); `close %s discarded` needs no review"
+            % (path, REVIEW_ROUNDS, ident, say()["decision"], ident))
+
+
+def unfinished_review(root, reviewer, plan="", since=0):
+    """The refusal of an `approve` while a slice journal record whose id or agent
+    is `reviewer` is open, stopped or stale: a review slice that died on a
+    provider limit had its approve recorded anyway, and a NameError it would have
+    caught reached main (plan 078). A stale review is one whose end nobody saw,
+    which reads no more than a stopped one. The omp records are reconciled with
+    their transcripts first (`tt.pending`), so a review that finished reads as
+    done. A record that names the plan active when it opened counts only for
+    that `plan`; one that names none counts when it changed at or after `since`
+    (epoch seconds; the plan's checkpoint commit). A `resumed` record has handed
+    its work to the re-dispatch, whose own record is the one read. A record
+    spawned as `reviewer` under its own id (`Reviewer-<digest6>`,
+    `tt.open_slice`) counts too. Under TEZGAH_SESSION only this session's
+    records and unowned ones count, by id, agent or name alike: another
+    session's review is not this approve's. The refusal names the exact id,
+    which `slice resume` and `slice done` take from any session."""
+    from tezgah_paths import off
+    if off("slices-off"):
+        return []
+    tt.pending(root)
+    session = os.environ.get("TEZGAH_SESSION")
+
+    def named(rec):
+        return reviewer in (rec.get("id"), rec.get("agent"), rec.get("name")) and (
+            not session or rec.get("parent") in (session, "", None))
+
+    def ours(rec):
+        if rec.get("plan"):
+            return rec["plan"] == plan
+        return (_stamp(rec.get("updated")) or 0) >= since
+
+    return ["review slice %s is %s%s: let it finish, or resume it with `tezgah-task "
+            "slice resume %s` and wait for that run; if the review was finished "
+            "another way, record it with `tezgah-task slice done %s` - an approve "
+            "from a review that did not finish reads nothing"
+            % (rec["id"], rec.get("status"),
+               (" (%s)" % rec["failure"]) if rec.get("failure") else "",
+               rec["id"], rec["id"])
+            for rec in tt.slices(root)
+            if rec.get("status") in ("open", "stopped", "stale")
+            and named(rec) and ours(rec)]
 
 
 def cmd_review(args):
     if len(args) != 3 or args[2] not in VERDICTS:
         return misuse("review takes <NNN|path> <reviewer> %s" % "|".join(VERDICTS))
-    path, problem = plan_path(repo_root(os.getcwd()), args[0])
+    path, problem = open_plan(args[0])
     if problem:
         return problems([problem])
     fields = tt.frontmatter(read(path))
@@ -593,6 +758,17 @@ def cmd_review(args):
     # the project's HEAD, never the private `.tezgah` repository's: the next
     # round's delta is `git diff <this>..HEAD` over the project
     root = os.path.realpath(os.path.join(os.path.dirname(path), "..", "..", ".."))
+    if args[2] == "approve":
+        # the plan's checkpoint commit (a sha, or `pending <sha>`) dates the work
+        # this review is about; with none, every record counts
+        mark = (fields.get("checkpoint") or "").split()
+        since = (git_out(root, "log", "-1", "--format=%ct", mark[-1])
+                 if mark and mark[-1] != tt.CHECKPOINT_PENDING else None)
+        ident = fields.get("id") or os.path.basename(path).split("-")[0]
+        bad = unfinished_review(root, args[1], ident,
+                                int(since) if (since or "").isdigit() else 0)
+        if bad:
+            return problems(bad)
     sha = (git_out(root, "rev-parse", "HEAD") or "")[:12]
     record = {"review": "%s %s %s" % (args[1], args[2], today()),
               "review_round": str(int(prior) + 1 if prior.isdigit() else 1),
@@ -716,6 +892,15 @@ def _keeps(root, path, branch, bases, agents):
     return None
 
 
+def landing_bases(root):
+    """The refs a branch's work counts as landed in, those that exist: HEAD,
+    main, master, and the remote's default branch too - a PR merged on the host
+    lands there first."""
+    return [b for b in ("HEAD", "main", "master", "origin/HEAD", "origin/main",
+                        "origin/master")
+            if git_out(root, "rev-parse", "-q", "--verify", b)]
+
+
 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
@@ -741,10 +926,7 @@ def prune_worktrees(root):
                 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)]
+    bases = landing_bases(root)
     out = []
     for path in linked:
         branch = git_out(path, "symbolic-ref", "-q", "--short", "HEAD")
@@ -826,6 +1008,390 @@ def cmd_status(args):
     return 1 if bad else 0
 
 
+# ------------------------------------------------------------------ slice
+
+# The closed lever set a stats candidate is named from (the research line's
+# RSI loop): one file or mechanism per failure class, never prose.
+LEVERS = {"rate_limit": "hooks/tezgah_models.py fallback chain",
+          "quota": "hooks/tezgah_models.py fallback chain",
+          "cut_off": "per-slice deadline", "timeout": "per-slice deadline",
+          "aborted": "wip: commit cadence", "duplicate": "journal background jobs",
+          "error": "none (read the transcript)"}
+STATS_WINDOW = 14
+# A signature is a candidate at this many events, or at this share of the slices
+# in the window once the window holds STATS_SHARE_FLOOR slices: below that, one
+# event is already 5% and every stop would read as a pattern.
+STATS_EVENTS = 3
+STATS_SHARE = 0.05
+STATS_SHARE_FLOOR = 20
+
+
+def parse_options(args, valued, flags=()):
+    """(options, positionals, problem) for `args`: each `valued` option takes the
+    next argument, each flag stands alone, any other `--x` is a problem."""
+    opts, pos, i = {}, [], 0
+    while i < len(args):
+        arg = args[i]
+        if arg in valued:
+            if i + 1 >= len(args):
+                return None, None, "%s needs a value" % arg
+            opts[arg] = args[i + 1]
+            i += 2
+        elif arg in flags:
+            opts[arg] = True
+            i += 1
+        elif arg.startswith("--"):
+            return None, None, "unknown option %r" % arg
+        else:
+            pos.append(arg)
+            i += 1
+    return opts, pos, None
+
+
+def resume_text(root, rec):
+    """The way back into one record's work: the host's native path first (omp
+    `write agent://<id>` while the parent session lives, Claude `SendMessage`),
+    else a re-dispatch brief that runs on any host or model - the original brief
+    plus where the work stands (last commit, branch, uncommitted files)."""
+    sid = rec["id"]
+    lines = [tt.slice_line(rec)]
+    if rec.get("kind") == "job":
+        lines.append("  command: %s" % (rec.get("brief") or "(none recorded)"))
+        return "\n".join(lines)
+    tree = rec.get("worktree") or ""
+    cwd = rec.get("cwd") or ""
+    where = (tree if tree and os.path.isdir(tree) else
+             cwd if cwd and os.path.isdir(cwd) else root)
+    last = git_out(where, "log", "-1", "--format=%h %s") or "(none)"
+    branch = (rec.get("branch") or git_out(where, "symbolic-ref", "-q", "--short", "HEAD")
+              or "(detached HEAD)")
+    # the journal's own directory is not the slice's work, ignored or not
+    dirty = [line[3:] for line in (git_out(where, "status", "--porcelain") or "").splitlines()
+             if not line[3:].startswith(".tezgah")]
+    resume = ("Resume: last commit %s on %s; uncommitted: %s; continue from there, "
+              "do not redo committed steps" % (last, branch, ", ".join(dirty) or "none"))
+    # a Claude record named by a 12-hex brief digest addresses no agent: no
+    # SendMessage line for it, only the re-dispatch
+    named = not re.fullmatch(r"[0-9a-f]{12}", sid)
+    native = {"omp": "`write agent://%s` (while omp session %s still runs)"
+                     % (sid, rec.get("parent") or "?"),
+              "claude": "`SendMessage` to %s" % sid if named else None}.get(rec.get("host"))
+    if native:
+        lines.append("  native: %s with: %s" % (native, resume))
+    provider = (" on another provider (`tezgah-route` names the tier; the same "
+                "account's limit would stop it again)"
+                if rec.get("failure") in ("quota", "rate_limit") else
+                " on any host or model")
+    lines.append("  %sre-dispatch%s with this brief:" % ("else " if native else "", provider))
+    lines.append(rec.get("brief") or "(no brief recorded)")
+    lines.append(resume)
+    return "\n".join(lines)
+
+
+def own_commits(root, rec):
+    """Does the record's branch carry a commit past the base it was opened on?
+    A branch still at its base is a slice that has not started, not one whose
+    work landed."""
+    base, branch = rec.get("base"), rec.get("branch")
+    if not base or not branch:
+        return False
+    count = git_out(root, "rev-list", "--count", "%s..%s" % (base, branch))
+    return bool(count) and count != "0"
+
+
+def prune_branches(root, bases):
+    """`git branch -d` every local branch whose work landed in `bases`, that no
+    worktree has checked out, that tracks no upstream (a long-lived branch such
+    as `develop` tracks one) and that carries a commit of its own (its reflog
+    names one, the guard `_keeps` applies to a worktree: a pre-created branch
+    nobody committed on is a slice not yet started) - never main, master or the
+    current branch. One line per branch it deletes or git refuses."""
+    current = git_out(root, "symbolic-ref", "-q", "--short", "HEAD")
+    held = {line[len("branch refs/heads/"):] for line in
+            (git_out(root, "worktree", "list", "--porcelain") or "").splitlines()
+            if line.startswith("branch refs/heads/")}
+    out = []
+    for row in (git_out(root, "for-each-ref", "--format=%(refname:short)\t%(upstream)",
+                        "refs/heads") or "").splitlines():
+        branch, _tab, upstream = row.partition("\t")
+        if branch in ("main", "master", current) or branch in held or upstream:
+            continue
+        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()):
+            continue
+        if not any(_landed(root, branch, b) for b in bases):
+            continue
+        done = subprocess.run(["git", "-C", root, "branch", "-d", branch],
+                              capture_output=True, text=True)
+        out.append("branch deleted: %s" % branch if done.returncode == 0 else
+                   "branch kept: %s (`git branch -d %s` refused: %s)"
+                   % (branch, branch, (done.stderr.strip().splitlines() or ["?"])[0]))
+    return out
+
+
+def _stamp(value):
+    """Seconds since the epoch of an ISO-8601 UTC record time, None when bad."""
+    import calendar
+    try:
+        return calendar.timegm(time.strptime(str(value), "%Y-%m-%dT%H:%M:%SZ"))
+    except ValueError:
+        return None
+
+
+def slice_stats(rows, window, now=None):
+    """Counts per status, failure class and host over the records updated in the
+    last `window` days, and the candidate signatures: `class+host`, one event per
+    record (the class it last stopped with) and `duplicate+host` per job record
+    run more than once, at STATS_EVENTS events or STATS_SHARE of the slices."""
+    from collections import Counter
+    cutoff = (time.time() if now is None else now) - window * 86400
+    picked = [r for r in rows if (_stamp(r.get("updated") or r.get("opened")) or 0) >= cutoff]
+    sigs = Counter()
+    for rec in picked:
+        host = rec.get("host") or "?"
+        if rec.get("failure") in LEVERS:
+            sigs[(rec["failure"], host)] += 1
+        if rec.get("kind") == "job" and int(rec.get("attempts") or 1) > 1:
+            sigs[("duplicate", host)] += 1
+    total = len(picked)
+    candidates = [{"signature": "%s+%s" % key, "events": n,
+                   "share": round(n / total, 3), "lever": LEVERS[key[0]]}
+                  for key, n in sorted(sigs.items(), key=lambda kv: (-kv[1], kv[0]))
+                  if n >= STATS_EVENTS
+                  or (total >= STATS_SHARE_FLOOR and n >= STATS_SHARE * total)]
+    return {"window_days": window, "slices": total,
+            "status": dict(Counter(r.get("status") or "?" for r in picked)),
+            "failure": dict(Counter(r["failure"] for r in picked if r.get("failure"))),
+            "host": dict(Counter(r.get("host") or "?" for r in picked)),
+            "candidates": candidates}
+
+
+def _counts(counter):
+    return ", ".join("%s %d" % kv for kv in sorted(counter.items())) or "none"
+
+
+# Files every slice appends to and only the integrator resolves (research
+# orchestrator-flow-audit S6, finding 8): a branch that touches one merges
+# after every branch that does not.
+HOTSPOTS = ("MANIFEST", "docs/citations-baseline.json")
+
+
+def merge_conflicts(root, ours, theirs):
+    """The files `git merge-tree` forecasts in conflict when `theirs` merges
+    into `ours`, minus the ones a `merge=union` attribute merges (CHANGELOG.md
+    here); None when git cannot answer (no such ref, git before 2.38)."""
+    try:
+        out = subprocess.run(["git", "-C", root, "merge-tree", "--write-tree",
+                              "--name-only", "--no-messages", ours, theirs],
+                             capture_output=True, text=True)
+    except OSError:
+        return None
+    if out.returncode not in (0, 1):
+        return None
+    files = sorted(set(out.stdout.split("\n\n")[0].splitlines()[1:]))
+    if not files:
+        return []
+    attrs = git_out(root, "check-attr", "merge", "--", *files) or ""
+    union = {line.rsplit(": merge: ", 1)[0] for line in attrs.splitlines()
+             if line.endswith(": merge: union")}
+    return [f for f in files if f not in union]
+
+
+def merge_plan(root, base):
+    """(lines, unjudged) for the done slices whose branch carries work `base`
+    lacks. The lines are the order to merge them: a branch touching no
+    HOTSPOTS first, then fewest forecast conflicts with `base`, then fewest
+    siblings it overlaps; each names its conflicting files and the siblings it
+    collides with. `unjudged` names each branch `git merge-tree` could not
+    forecast (git before 2.38, no shared history) instead of dropping it."""
+    branches = {}
+    for rec in tt.slices(root):
+        branch = rec.get("branch")
+        if (rec.get("status") == "done" and branch and branch not in branches
+                and own_commits(root, rec) and not _landed(root, branch, base)):
+            branches[branch] = rec
+    rows, unjudged = [], []
+    for branch, rec in branches.items():
+        mine = merge_conflicts(root, base, branch)
+        if mine is None:
+            unjudged.append("not judged: %s (slice %s): `git merge-tree --write-tree` "
+                            "could not forecast it against %s" % (branch, rec["id"], base))
+            continue
+        overlaps = {}
+        for other in branches:
+            files = merge_conflicts(root, other, branch) if other != branch else None
+            if files:
+                overlaps[other] = files
+        touched = (git_out(root, "diff", "--name-only", "%s...%s" % (base, branch))
+                   or "").splitlines()
+        hot = any(f in HOTSPOTS for f in touched)
+        rows.append(((hot, len(mine), len(overlaps), branch), rec, mine, overlaps))
+    rows.sort(key=lambda row: row[0])
+    out = []
+    for n, (key, rec, mine, overlaps) in enumerate(rows, 1):
+        line = "%d. %s (slice %s): %d conflict(s) with %s%s" % (
+            n, rec["branch"], rec["id"], len(mine), base,
+            ": " + ", ".join(mine) if mine else "")
+        for other, files in sorted(overlaps.items()):
+            line += "; overlaps %s on %s" % (other, ", ".join(files))
+        out.append(line + (" (touches a hotspot: the integrator merges it last)"
+                           if key[0] else ""))
+    return out, unjudged
+
+
+def board_parent():
+    """The parent whose slices `slice board` shows: the session in
+    TEZGAH_SESSION, or - read from a subagent - the parent that spawned it
+    (`tezgah_integrity.spawn_of`), so a slice sees its siblings; None, every
+    open slice, outside a session."""
+    session = os.environ.get("TEZGAH_SESSION")
+    if not session:
+        return None
+    try:
+        from tezgah_integrity import spawn_of
+        spawn = spawn_of(session)
+    except Exception:
+        spawn = None
+    return spawn[0] if spawn else session
+
+
+def cmd_slice(args):
+    usage = ("slice takes open|done|stop|reconcile|resume|stats|board|merge-plan "
+             "(open --id ID [--kind agent|job] [--host H] [--agent A] "
+             "[--brief TEXT|--brief-file F] [--parent P] [--cwd PATH]; done ID; stop ID "
+             "[--class C]; reconcile [--prune]; resume ID; stats [--window DAYS] "
+             "[--json]; board [--parent P]; merge-plan [--base REF])")
+    if not args:
+        return misuse(usage)
+    sub, rest = args[0], args[1:]
+    root = repo_root(os.getcwd())
+    if sub == "board":
+        opts, pos, bad = parse_options(rest, ("--parent",))
+        if bad or pos:
+            return misuse(bad or "slice board takes [--parent P] and nothing else")
+        lines = tt.board(root, opts.get("--parent") or board_parent())
+        print("\n".join(lines) if lines else "no open slice")
+        return 0
+    if sub == "merge-plan":
+        opts, pos, bad = parse_options(rest, ("--base",))
+        if bad or pos:
+            return misuse(bad or "slice merge-plan takes [--base REF] and nothing else")
+        base = opts.get("--base", "HEAD")
+        if git_out(root, "rev-parse", "-q", "--verify", base) is None:
+            return problems(["no revision %s in %s" % (base, root)])
+        lines, unjudged = merge_plan(root, base)
+        if lines or not unjudged:
+            print("\n".join(lines) if lines else "no done slice branch to merge into %s" % base)
+        for line in unjudged:
+            print(line)
+        return 1 if unjudged else 0
+    if sub == "open":
+        opts, pos, bad = parse_options(rest, ("--id", "--kind", "--host", "--agent",
+                                              "--brief", "--brief-file", "--parent",
+                                              "--cwd"))
+        if bad or pos:
+            return misuse(bad or "slice open takes options only (%r)" % pos[0])
+        if not opts.get("--id"):
+            return misuse("slice open needs --id ID")
+        if "--brief" in opts and "--brief-file" in opts:
+            return misuse("--brief and --brief-file contradict each other")
+        kind, host = opts.get("--kind", "agent"), opts.get("--host", "")
+        if kind not in tt.SLICE_KINDS:
+            return misuse("--kind is one of %s" % ", ".join(tt.SLICE_KINDS))
+        if host and host not in tt.SLICE_HOSTS:
+            return misuse("--host is one of %s" % ", ".join(tt.SLICE_HOSTS))
+        brief = opts.get("--brief", "")
+        if "--brief-file" in opts:
+            try:
+                brief = read(opts["--brief-file"])
+            except (OSError, UnicodeDecodeError) as exc:
+                return problems(["cannot read %s: %s" % (opts["--brief-file"], exc)])
+        try:
+            rec = tt.open_slice(root, opts["--id"], kind=kind, host=host,
+                                agent=opts.get("--agent", ""), brief=brief,
+                                parent=opts.get("--parent", ""),
+                                cwd=opts.get("--cwd") or os.getcwd())
+        except OSError as exc:
+            return problems(["cannot write the slice record: %s" % exc])
+        print("slice %s open (%s, attempt %d)%s" % (
+            rec["id"], rec["kind"], rec["attempts"],
+            " worktree %s on %s" % (rec["worktree"], rec["branch"] or "?")
+            if rec["worktree"] else ""))
+        return 0
+    if sub in ("done", "stop"):
+        opts, pos, bad = parse_options(rest, ("--class",) if sub == "stop" else ())
+        if bad or len(pos) != 1:
+            return misuse(bad or "slice %s takes one ID%s" % (
+                sub, " [--class C]" if sub == "stop" else ""))
+        failure = opts.get("--class", "")
+        if failure and failure not in tt.FAILURES:
+            return misuse("--class is one of %s" % ", ".join(tt.FAILURES))
+        status = "done" if sub == "done" else "stopped"
+        try:
+            found = tt.find_slice(root, pos[0], os.environ.get("TEZGAH_SESSION"))
+            rec = found and tt.close_slice(root, found["id"], status, failure)
+        except OSError as exc:
+            return problems(["cannot write the slice record: %s" % exc])
+        if not rec:
+            return problems(["no slice record %s under %s" % (pos[0], tt.slice_dir(root))])
+        print("slice %s %s%s" % (rec["id"], status,
+                                 " (%s)" % rec["failure"] if rec.get("failure") else ""))
+        return 0
+    if sub == "reconcile":
+        opts, pos, bad = parse_options(rest, (), ("--prune",))
+        if bad or pos:
+            return misuse(bad or "slice reconcile takes --prune and nothing else")
+        if opts.get("--prune"):
+            bases = landing_bases(root)
+            # read before the prune: a removed worktree takes its branch with it
+            landed = [rec for rec in tt.slices(root)
+                      if rec.get("status") != "done" and own_commits(root, rec)
+                      and any(_landed(root, rec["branch"], b) for b in bases)]
+            for line in prune_worktrees(root) + prune_branches(root, bases):
+                print(line)
+            for rec in landed:
+                tt.close_slice(root, rec["id"], "done")
+                print("slice %s done: %s landed" % (rec["id"], rec["branch"]))
+        rows = tt.pending(root)
+        if not rows:
+            print("no open or stopped slice")
+        for rec in rows:
+            print(resume_text(root, rec))
+        return 0
+    if sub == "resume":
+        if len(rest) != 1:
+            return misuse("slice resume takes one ID")
+        rec = tt.find_slice(root, rest[0], os.environ.get("TEZGAH_SESSION"))
+        if rec is None:
+            return problems(["no slice record %s under %s" % (rest[0], tt.slice_dir(root))])
+        print(resume_text(root, rec))
+        tt.close_slice(root, rec["id"], "resumed")
+        return 0
+    if sub == "stats":
+        opts, pos, bad = parse_options(rest, ("--window",), ("--json",))
+        if bad or pos:
+            return misuse(bad or "slice stats takes [--window DAYS] [--json]")
+        window = opts.get("--window", str(STATS_WINDOW))
+        if not window.isdigit() or int(window) < 1:
+            return misuse("--window takes a whole number of days")
+        stats = slice_stats(tt.slices(root), int(window))
+        if opts.get("--json"):
+            print(json.dumps(stats, indent=2, sort_keys=True))
+            return 0
+        print("slices in the last %d days: %d" % (stats["window_days"], stats["slices"]))
+        for key in ("status", "failure", "host"):
+            print("  %s: %s" % (key, _counts(stats[key])))
+        for row in stats["candidates"]:
+            print("candidate: %s - %d events (%d%% of slices) - lever: %s" % (
+                row["signature"], row["events"], round(row["share"] * 100), row["lever"]))
+        if not stats["candidates"]:
+            print("no signature at %d events or %d%% of the slices"
+                  % (STATS_EVENTS, round(STATS_SHARE * 100)))
+        return 0
+    return misuse(usage)
+
+
 def main(argv):
     if len(argv) < 2:
         print(__doc__, file=sys.stderr)
@@ -845,8 +1411,14 @@ def main(argv):
         return cmd_review(rest)
     if cmd == "close":
         return cmd_close(rest)
+    if cmd == "tick":
+        return cmd_tick(rest)
+    if cmd == "note":
+        return cmd_note(rest)
+    if cmd == "slice":
+        return cmd_slice(rest)
     return misuse("unknown command %r (start, phase, allow, stop, status, review, "
-                  "close)" % cmd)
+                  "close, tick, note, slice)" % cmd)
 
 
 if __name__ == "__main__":