@appchy/jarvis 0.1.37 → 0.1.39

package/harness/harness/architecture.py

@@ -0,0 +1,254 @@
+from pathlib import Path
+
+from . import ids
+from .tree import BACKLOG_END, BACKLOG_START, assets_dir, die, find_work_root, rel
+from .model import locate
+from .registry import (DOMAIN_ORDER, _citation_counts, definition_sites,
+                       domains_for_owner, hosts, locate_domain, locate_system,
+                       scan_systems, systems_for_code)
+from .scaffold import _check_kebab
+from .generate import _sync
+
+#: The shipped charters, beside the other scaffold assets. A charter for one of the
+#: known domains is AUTHORED PROSE about a boundary — which neighbour owns what, and
+#: why the split is there — and that cannot be generated from a name. So the nine
+#: ship as files and `domain-new`/`init` copy them; anything else gets the generic
+#: stub, which is still a working domain.
+#: Derived from `assets_dir()` rather than counted out again from this file: getting
+#: it wrong is silent — `_charter` falls back to the generic stub, so every domain
+#: still scaffolds and still declares itself, and the only symptom is that nine
+#: authored charters quietly never ship.
+ASSETS = assets_dir() / "domains"
+
+
+def _charter(name: str, title: str) -> str:
+    """The shipped charter for `name`, or a generic stub.
+
+    `README.md`, not a bespoke `domain.md`: the landing doc of a folder should be
+    named what every reader, tool and folder view already looks for. The
+    `type: domain` frontmatter — not the filename — is what makes it a domain.
+
+    A domain hosts rules exactly as a system does, so every shape carries the
+    `## Rules` heading: a domain whose README has nowhere to put an id is a domain
+    whose ids get mis-filed into the nearest system.
+    """
+    shipped = ASSETS / f"{name}.md"
+    if shipped.is_file():
+        return shipped.read_text()
+    return (
+        f"---\ntype: domain\nid: {name}\n---\n\n# {title}\n\n## What belongs here\n\n"
+        f"_One paragraph: the kind of durable call this domain owns, and how you "
+        f"tell it from its neighbours._\n\n"
+        f"## Non-goals\n\n- _What lives elsewhere._\n\n"
+        f"## Rules\n\n<!-- ### {ids.LEDGER}-nn — _the rule, in one line_\n"
+        f"     enforced_by: _…_ -->\n"
+    )
+
+
+def cmd_domain_new(args) -> int:
+    root = find_work_root()
+    name = args["name"]
+    _check_kebab("domain", name)
+    if locate_domain(root, name):
+        die(f"a domain named '{name}' already exists")
+    folder = root / name
+    folder.mkdir(parents=True, exist_ok=True)
+    title = args.get("title") or name.replace("-", " ").capitalize()
+    (folder / "README.md").write_text(_charter(name, title))
+    shipped = " (shipped charter)" if (ASSETS / f"{name}.md").is_file() else ""
+    print(f"created {rel(folder / 'README.md', root)}{shipped}")
+    _sync(root)
+    return 0
+
+
+#: The one file `_regen_readme` cannot work without, so `init` writes it first.
+_README = f"""# Work
+
+The board. Tasks live in three tiers — version, epic, task — beside the org-domains
+that host every kind of durable call. `jarvis work list` prints what is moving;
+`jarvis work where <id>` resolves any rule id to its home.
+
+The table below is GENERATED. Edit the prose around it, never the block itself.
+
+{BACKLOG_START}
+{BACKLOG_END}
+"""
+
+_ROADMAP = """# Roadmap
+
+The release **order**, never the status — status is derived from the tree, and a
+second copy of it here is a second copy to drift.
+
+<!-- One line per planned version, in the order they open. A version is a RELEASE:
+     it states what a user can newly DO when it ships, and it cannot open while an
+     earlier one is unreleased. -->
+"""
+
+
+def cmd_init(args) -> int:
+    """Scaffold a work tree: the board, the roadmap, and the nine org-domains.
+
+    **Idempotent, and never destructive.** It creates what is missing and skips what
+    exists, reporting both — because the realistic second run of `init` is a repo
+    that got half a tree and wants the rest, and an `init` that refuses outright
+    sends that user to `mkdir`. Nothing is ever overwritten, so a charter a repo has
+    edited stays edited.
+
+    All nine domains are created, including the ones that will hold no rules for a
+    long time. The cost of an empty charter is one file; the cost of a missing domain
+    is a rule mis-filed under whichever system happened to be nearby, which is the
+    failure the domain split exists to end.
+
+    The root comes from the caller (`--project` / `CLAUDE_PROJECT_DIR` / cwd) rather
+    than from `find_work_root`, which cannot help here: it looks for a `work/` that
+    does not exist yet.
+    """
+    project = Path(args["project_root"]).resolve()
+    if not project.is_dir():
+        die(f"project root '{project}' is not a directory")
+    root = project / "work"
+
+    made, skipped = [], []
+
+    def write(path: Path, text: str) -> None:
+        if path.exists():
+            skipped.append(rel(path, root))
+            return
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(text)
+        made.append(rel(path, root))
+
+    write(root / "README.md", _README)
+    write(root / "ROADMAP.md", _ROADMAP)
+    for d in ("versions", "backlog"):
+        (root / d).mkdir(parents=True, exist_ok=True)
+    # Reading order, not alphabetical — and read from config, so a repo that added a
+    # tenth domain gets it scaffolded too rather than having to remember to.
+    for name in DOMAIN_ORDER:
+        write(root / name / "README.md",
+              _charter(name, name.replace("-", " ").capitalize()))
+
+    print(f"initialised {rel(root, root) or 'work/'} at {root}")
+    if made:
+        print(f"  created {len(made)}: {', '.join(made)}")
+    if skipped:
+        print(f"  kept {len(skipped)} existing: {', '.join(skipped)}")
+    if not made:
+        print("  nothing to do — the tree was already complete")
+    _sync(root)
+    return 0
+def cmd_system_new(args) -> int:
+    root = find_work_root()
+    name = args["name"]
+    _check_kebab("system", name)
+    if locate_system(root, name):
+        die(f"a system named '{name}' already exists")
+    code = [c.strip() for c in (args.get("code") or "").split(",") if c.strip()]
+    owned = {c: s.name for s in scan_systems(root) for c in s.code}
+    for c in code:
+        if c in owned:
+            die(f"code region '{c}' is already owned by system '{owned[c]}' — "
+                f"a region belongs to exactly one system")
+    md = root / "architecture" / f"{name}.md"
+    md.parent.mkdir(parents=True, exist_ok=True)
+    title = args.get("title") or name.replace("-", " ").capitalize()
+    md.write_text(
+        f"---\ntype: system\ncode: [{', '.join(code)}]\npaths: []\ndepends_on: []\n---\n\n"
+        f"# {title}\n\n## Purpose\n\n_What capability this owns, in two sentences._\n\n"
+        f"## Boundary\n\n**In** — _…_\n\n**Out** — _…_\n\n"
+        f"## Shape\n\n```mermaid\nflowchart TD\n  A[\"…\"] --> B[\"…\"]\n```\n\n"
+        # The PROSE is the definition — `_parse_rules` reads these headings and the
+        # `enforced_by:` under each. The summary table this used to scaffold is
+        # deleted, not generated: a table three lines above the entry it summarises
+        # is one more thing to keep in sync.
+        #
+        # The word is RULE. Scaffolding "Invariants" here is how the retired word
+        # comes back one system at a time, however carefully the docs were renamed.
+        f"## Rules\n\n### {ids.LEDGER}-nn — _the rule, in one line_\nenforced_by: _…_\n\n"
+        f"**Rule.** _…_\n\n**Why.** _…_\n\n**Never.** _…_\n\n"
+        f"## Seams\n\n- _…_\n\n## Non-goals\n\n- _…_\n"
+    )
+    print(f"created {rel(md, root)}")
+    _sync(root)
+    return 0
+def cmd_where(args) -> int:
+    """Resolve an id → its home, its `code:` regions, its `enforced_by` and how
+    many files cite it. Ids are permanent; the home is a lookup, never a
+    renumber."""
+    root = find_work_root()
+    id_ = args["id"].upper()
+    if not ids.ID_EXACT.match(id_):
+        die(f"'{args['id']}' is not a {ids.LEDGER}-nn id")
+    id_ = ids.normalise(id_)
+    sites = definition_sites(root).get(id_, [])
+    # Every HOST, not just systems: a rule about proof or shipping lives in its
+    # org-domain, and a `where` that only walked systems reported it as unhosted.
+    homes = [(home, name, rules, code) for home, name, rules, code in hosts(root)
+             if id_ in rules]
+
+    if not sites and not homes:
+        die(f"{id_} resolves to nothing — no `### {id_}` on any surface and no "
+            f"host declares it")
+
+    title = next((t for _, t in sites if t), "")
+    print(f"  {id_}  {title or '(no title)'}")
+    if homes:
+        for home, _, rules, code in homes:
+            print(f"        home    {home}")
+            if code:
+                print(f"        code    {', '.join(code)}")
+            print(f"        enforced_by  {rules[id_] or '⚠ none declared'}")
+        if len(homes) > 1:
+            print(f"        ⚠ {len(homes)} docs host {id_} — an id has ONE home")
+    else:
+        print(f"        home    {sites[0][0]}")
+    if len(sites) > 1:
+        print(f"        ⚠ defined on {len(sites)} surfaces "
+              f"({', '.join(h for h, _ in sites)}) — an id has ONE definition site")
+    n = _citation_counts(root).get(id_, 0)
+    print(f"        cited by     {n} file(s)")
+    return 0
+def cmd_rules(args) -> int:
+    """The rules that constrain a task, DERIVED — `task.code ∩ system.code` for
+    systems, `task.owner` for domains. Run it while planning the EPIC, over the
+    union of its tasks' regions: a plan that trips one of these is the plan that
+    gets rewritten, and finding that out per-task is finding it out four times."""
+    root = find_work_root()
+    name = args.get("task")
+    if not name:
+        die("usage: jarvis work rules --task <name>")
+    t = locate(root, name)
+    if not t:
+        die(f"no task named '{name}'")
+    systems = systems_for_code(root, t.code) if t.code else []
+    domains = domains_for_owner(root, t.owner)
+    if not systems and not domains:
+        print(f"  {name}: no `code:` regions and no resolvable `owner:` — "
+              f"nothing to derive from")
+        return 0
+    # Titles come from wherever the id is DEFINED. Reading only a central ledger
+    # printed a column of blanks for every id that had already moved to its host.
+    titles = {id_: next((t_ for _, t_ in s if t_), "")
+              for id_, s in definition_sites(root).items()}
+
+    if t.code:
+        print(f"  code: [{', '.join(t.code)}]  →  "
+              f"system: {', '.join(s.name for s in systems) or '(none)'}")
+    if t.owner:
+        print(f"  owner: {t.owner}  →  "
+              f"domain: {', '.join(d.name for d in domains) or '(none)'}")
+    by_home = {h[0]: h[2] for h in hosts(root)}
+    total = 0
+    for home, hit in ([(f"architecture/{s.name}", sorted(set(t.code) & set(s.code)))
+                       for s in systems]
+                      + [(f"{d.name}/README", [t.owner]) for d in domains]):
+        rules = by_home.get(home, {})
+        print(f"\n  {home}   (via {', '.join(hit)})")
+        for id_, evidence in sorted(rules.items(), key=lambda kv: ids.sort_key(kv[0])):
+            total += 1
+            mark = " " if evidence else "!"
+            print(f"   {mark}{id_:7} {titles.get(id_, '')[:76]}")
+    if total:
+        print(f"\n  ⚠ these {total} rules constrain your plan — cite them, or "
+              f"change the plan.  `!` = no enforced_by, so nothing will catch you.")
+    return 0

package/harness/harness/autonomy.py

@@ -0,0 +1,374 @@
+"""The decision boundary: what an unattended run may settle alone, and what it
+parks for the founder.
+
+Every load-bearing rule in `SKILL.md` was written for a session with a person in
+the chair — *route every product, UX or architecture decision through the user*.
+Run that same skill on a schedule and the rule does not fail loudly; it degrades
+into *decide it yourself*, with no record that a call the founder owned was made
+without them. That is the failure this module exists to make impossible.
+
+Two mechanics, and they only work together:
+
+**`tier:`** is what a task's blast radius IS — the axis the harness lacked, since
+`code:` region count measured size and size is not risk. It is DERIVED where the
+tree already knows the answer (an `owner:` of security/legal/commercial floors a
+task at 3) and can be raised by hand, never lowered: a run that could talk its own
+tier down is a run with no ceiling at all.
+
+**`ask`** is what happens at the boundary. It writes the question, moves the task
+to `blocked/`, and **exits 0** — so the instance takes other work instead of
+stalling. `needs` is the founder's one screen; `answer` unblocks. Nothing here
+decides anything: that is the point.
+"""
+import re
+import shutil
+import sys
+from datetime import date
+
+from .tree import (BLOCKED, BUCKETS, DEFAULT_AUTONOMY_CEILING, TIER3_OWNERS,
+                   TIER_MEANING, TIERS, die, find_work_root, rel)
+from .frontmatter import as_list, parse_frontmatter, rewrite_file
+from .model import locate, record_session, scan
+from .generate import _sync
+from . import events
+
+#: `autonomy.ceiling` from config — the highest tier an unattended run acts on
+#: alone. Set by `config.apply`, so a repo's answer is bound before any command
+#: reads it.
+CEILING = DEFAULT_AUTONOMY_CEILING
+
+
+def derive_tier(owner: str, code: list, given=None) -> tuple:
+    """A task's tier, and the one-line reason for it.
+
+    The floor comes from the tree, so it cannot be forgotten the way a hand-set
+    field can; `given` may raise it and is refused if it tries to lower it. Returns
+    `(tier, why)` — `why` is printed on refusal, because a floor that will not say
+    which signal set it is a floor people argue with.
+    """
+    floor, why = 1, "default for an ordinary change"
+    owner_root = (owner or "").split("/")[0]
+    if owner_root in TIER3_OWNERS:
+        floor, why = 3, f"owner: {owner_root} — this domain is always tier 3"
+
+    if given is None:
+        return floor, why
+    try:
+        want = int(str(given).strip())
+    except ValueError:
+        die(f"--tier must be one of {', '.join(str(t) for t in TIERS)} (got {given!r})")
+    if want not in TIERS:
+        die(f"--tier must be one of {', '.join(str(t) for t in TIERS)} (got {want})")
+    if want < floor:
+        die(f"--tier {want} is below this task's derived floor of {floor} ({why}).\n"
+            f"       A tier may be raised, never lowered — a run that can talk its "
+            f"own blast radius down has no ceiling at all.")
+    return want, ("as given" if want == floor else f"raised from {floor} ({why})")
+
+
+def tier_of(task) -> int:
+    """The tier on a task, defaulting to its derived floor. Tolerates a task
+    written before tiers existed — every consumer must keep working on a tree that
+    predates this field, or adding it would strand every existing board."""
+    raw = str(task.fm.get("tier", "")).strip()
+    if raw:
+        try:
+            return int(raw)
+        except ValueError:
+            pass
+    return derive_tier(task.owner, task.code)[0]
+
+
+def within_ceiling(task) -> bool:
+    """May an unattended run act on this alone?"""
+    return tier_of(task) <= CEILING
+
+
+def _open_questions(task) -> list:
+    """Questions with no answer yet, oldest first.
+
+    `asked:` is an append-only transcript: a question is
+    `<date>  <owner>  <question>  [options: …]`, and an answer is a later entry
+    beginning `answered`. So openness is not a property of a single line — it is
+    what is left when each answer is paired off against the longest-waiting
+    question. Reading it any other way (matching a prefix, trusting a flag) is how
+    an answered question keeps showing up in `needs` forever, which trains the one
+    person this list exists for to stop reading it.
+    """
+    out = []
+    for entry in as_list(task.fm.get("asked")):
+        s = str(entry).strip()
+        if s.startswith("answered"):
+            if out:
+                out.pop(0)
+        elif s:
+            out.append(s)
+    return out
+
+
+def _reread(root, name):
+    """The task as it is on disk NOW — after a write this process just made.
+
+    `locate` returns a snapshot with the frontmatter parsed at scan time, and a caller
+    that has since written to the file is holding a stale one.
+    """
+    return locate(root, name)
+
+
+def cmd_ask(args) -> int:
+    """Park a question and RETURN — the instance moves on to other work.
+
+    This is the anti-babysitting primitive. It never blocks the caller, never
+    guesses, and never lets a question be asked twice: the answer lands in the
+    tree, and `--durable` says it belongs in a domain rule instead."""
+    root = find_work_root()
+    name = args["name"]
+    question = (args.get("question") or "").strip()
+    if not question:
+        die("usage: jarvis work ask <task> --question \"…\" [--options \"a | b\"] "
+            "[--owner founder] [--durable]")
+    task = locate(root, name)
+    if not task:
+        die(f"no task named '{name}' found")
+    if task.in_backlog:
+        die(f"'{name}' is in backlog — a backlog task has no status to park. "
+            f"Pull it into a version first.")
+
+    owner = (args.get("owner") or "founder").strip()
+    options = (args.get("options") or "").strip()
+    durable = bool(args.get("durable"))
+
+    # A question already on this task, asked again, is a run going in circles —
+    # the exact loop an unattended shift can run all night without noticing.
+    for existing in _open_questions(task):
+        if question.lower() in existing.lower():
+            print(f"'{name}' already has this question open — not asking twice:")
+            print(f"  {existing}")
+            return 0
+
+    entry = f"{date.today().isoformat()}  {owner}  {question}"
+    if options:
+        entry += f"  [options: {options}]"
+    if durable:
+        entry += "  [durable]"
+
+    was = task.status
+    dest = task.folder
+    if was != BLOCKED:
+        container = task.folder.parent.parent
+        dest = container / BLOCKED / name
+        if dest.exists():
+            die(f"{rel(dest, root)} already exists")
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        shutil.move(str(task.folder), str(dest))
+
+    md = dest / "task.md"
+
+    def mutate(d):
+        d["asked"] = as_list(d.get("asked")) + [entry]
+        d["updated"] = date.today().isoformat()
+
+    rewrite_file(md, mutate)
+    record_session(dest)
+    events.append(root, "asked", name, question=question, owner=owner,
+                  options=options or None, durable=durable or None)
+    if was != BLOCKED:
+        events.append(root, "blocked", name, was=was)
+        print(f"parked '{name}': {was}/ -> {BLOCKED}/")
+    print(f"        asked {owner}: {question}")
+    if options:
+        print(f"        options: {options}")
+    print(f"        take other work — `jarvis work next` skips blocked tasks. "
+          f"`jarvis work needs` shows every open question.")
+    _sync(root)
+    return 0
+
+
+def cmd_answer(args) -> int:
+    """Resolve the open question and put the task back to work."""
+    root = find_work_root()
+    name = args["name"]
+    choice = (args.get("choose") or args.get("answer") or "").strip()
+    if not choice:
+        die("usage: jarvis work answer <task> --choose \"…\"")
+    task = locate(root, name)
+    if not task:
+        die(f"no task named '{name}' found")
+    open_qs = _open_questions(task)
+    if not open_qs:
+        die(f"'{name}' has no open question — nothing to answer")
+
+    to = (args.get("to") or "queue").strip()
+    # Checked against the real buckets, because nothing scans a directory that is not
+    # one: `--to complte` used to create it, move the folder in, print success and
+    # exit 0, after which `locate` returned None and the item was off the board with
+    # no way back through the CLI.
+    if to not in BUCKETS:
+        die(f"--to {to!r} is not a bucket — one of {', '.join(BUCKETS)}")
+    # Completion runs a gate: the evidence has to exist, the criteria have to be met,
+    # and `completed:` has to be stamped. Answering a question is not that, and this
+    # door used to skip all of it — landing a task in `complete/` with no `completed:`
+    # and parking the whole epic as done behind it.
+    if to == "complete":
+        die("answering a question cannot complete a task — the completion gate has "
+            "to run. Answer it, then `jarvis work move <task> complete`.")
+    md = task.folder / "task.md"
+    answered = f"answered {date.today().isoformat()}  {choice}"
+
+    def mutate(d):
+        d["asked"] = as_list(d.get("asked")) + [answered]
+        d["updated"] = date.today().isoformat()
+
+    rewrite_file(md, mutate)
+    events.append(root, "answered", name, choice=choice, question=open_qs[0])
+
+    # Re-read after the answer landed: a task asked two questions and answered one is
+    # still blocked on the other, and leaving `blocked/` here put it back in `queue/`
+    # where an unattended run could take it — the exact invariant the bucket holds.
+    still_open = _open_questions(_reread(root, name) or task)
+    dest = task.folder
+    if task.status == BLOCKED and still_open:
+        print(f"answered '{name}' — still blocked on {len(still_open)} more "
+              f"question(s), so it stays put:")
+        for q in still_open:
+            print(f"        {q[:120]}")
+        print(f"        {choice}")
+        _sync(root)
+        return 0
+    if task.status == BLOCKED:
+        container = task.folder.parent.parent
+        dest = container / to / name
+        if dest.exists():
+            die(f"{rel(dest, root)} already exists")
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        shutil.move(str(task.folder), str(dest))
+        events.append(root, "moved", name, **{"from": BLOCKED, "to": to})
+        print(f"answered '{name}' -> {to}/")
+    else:
+        print(f"answered '{name}' (already in {task.status}/)")
+    print(f"        {choice}")
+    if any("[durable]" in q for q in open_qs):
+        print("        NOTE  this was asked as [durable] — promote the answer to "
+              "the domain that owns it (`jarvis work id-new --host <domain> --title …`) "
+              "so it is never asked again.")
+    _sync(root)
+    return 0
+
+
+def cmd_needs(args) -> int:
+    """Every open question, on one screen. The founder's whole obligation.
+
+    Sorted oldest-first: a question waiting three days is more urgent than one
+    asked this morning, and a list that hides that is a list that trains people to
+    skim it."""
+    root = find_work_root()
+    s = scan(root)
+    rows = []
+    for v in s["versions"]:
+        for t in v.all_tasks():
+            for q in _open_questions(t):
+                rows.append((q.split("  ")[0], v.name, t, q))
+    for t in s["backlog"]:
+        for q in _open_questions(t):
+            rows.append((q.split("  ")[0], "backlog", t, q))
+
+    if not rows:
+        blocked = [t for v in s["versions"] for t in v.bucket(BLOCKED)]
+        if blocked:
+            print("nothing is waiting on you — but these are parked in blocked/ "
+                  "with no question recorded, which is a bug in whatever parked them:")
+            for t in blocked:
+                print(f"  {t.name} — {t.title}")
+            return 0
+        print("nothing is waiting on you.")
+        return 0
+
+    rows.sort(key=lambda r: (r[0], r[2].name))
+    today = date.today()
+    print(f"WAITING ON YOU  ({len(rows)} question(s))\n")
+    for asked_on, where, t, q in rows:
+        parts = q.split("  ")
+        owner = parts[1] if len(parts) > 2 else "founder"
+        body = "  ".join(parts[2:]) if len(parts) > 2 else q
+        age = ""
+        try:
+            days = (today - date.fromisoformat(asked_on)).days
+            age = f" · waiting {days}d" if days else " · asked today"
+        except ValueError:
+            pass
+        print(f"  {t.name}  [{where} · tier {tier_of(t)} · for {owner}{age}]")
+        print(f"      {body}")
+        print(f"      → jarvis work answer {t.name} --choose \"…\"\n")
+    return 0
+
+
+def cmd_log(args) -> int:
+    """The raw record, oldest first."""
+    root = find_work_root()
+    rows = events.read(root, since=(args.get("since") or "").strip(),
+                       name=(args.get("task") or "").strip())
+    if not rows:
+        print("no events recorded yet")
+        return 0
+    for e in rows:
+        # Under git the record also knows WHICH MACHINE — the thing a session id
+        # could never say, and the reason the file it replaced was not enough.
+        who = "  [" + " @ ".join(p for p in (e.get("by", "")[:8], e.get("machine", "")) if p) + "]" \
+            if (e.get("by") or e.get("machine")) else ""
+        extra = {k: v for k, v in e.items()
+                 if k not in ("ts", "event", "name", "by", "machine", "sha", "author")}
+        tail = ("  " + " · ".join(f"{k}={v}" for k, v in sorted(extra.items()))) if extra else ""
+        print(f"{e['ts']}  {e['event']:>14}  {e['name']}{who}{tail}")
+    return 0
+
+
+def cmd_digest(args) -> int:
+    """What happened, in the founder's terms. The morning read after a shift.
+
+    Deliberately reads the log and NOTHING else — it is the one view that is about
+    time, and mixing in current state is how a history file starts being consulted
+    for what is true now."""
+    root = find_work_root()
+    since = (args.get("since") or "").strip()
+    rows = events.read(root, since=since)
+    if not rows:
+        print(f"no events{f' since {since}' if since else ''} yet")
+        return 0
+
+    def names(kind):
+        return sorted({e["name"] for e in rows if e["event"] == kind})
+
+    shipped = names("completed")
+    asked = [e for e in rows if e["event"] == "asked"]
+    answered = names("answered")
+    refused = [e for e in rows if e["event"] == "gate-refused"]
+    released = names("released")
+    # What was WORKED ON is a task moving into in-progress, not a lease being taken.
+    # A claim is one way to arrive there and it is not the only one — a person who
+    # moved three tasks by hand read as an idle shift, and under git a claim is not
+    # recorded at all, because a hold belongs to a machine rather than to a branch.
+    worked = sorted({e["name"] for e in rows
+                     if e["event"] == "claimed"
+                     or (e["event"] == "moved" and e.get("to") == "in-progress")})
+
+    print(f"DIGEST  {len(rows)} event(s)"
+          + (f" since {since}" if since else "") + "\n")
+    if released:
+        print(f"  RELEASED   {', '.join(released)}")
+    if shipped:
+        print(f"  SHIPPED    {len(shipped)}: {', '.join(shipped)}")
+    if worked:
+        print(f"  WORKED     {len(worked)}: {', '.join(worked)}")
+    if asked:
+        print(f"  ASKED      {len(asked)} question(s) — `jarvis work needs` to answer:")
+        for e in asked:
+            print(f"               {e['name']}: {e.get('question', '')}")
+    if answered:
+        print(f"  ANSWERED   {', '.join(answered)}")
+    if refused:
+        print(f"  GATE HELD  {len(refused)} completion(s) refused:")
+        for e in refused:
+            print(f"               {e['name']}: {e.get('why', '')}")
+    if not any((released, shipped, worked, asked, answered, refused)):
+        print("  nothing notable — no work was taken, and nothing was asked.")
+    return 0