@appchy/jarvis 0.1.91 → 0.1.93

package/harness/harness/config.py

@@ -1193,41 +1193,47 @@ def cmd_applies(cfg: dict, args=None, repo=None) -> int:
 
 
 def cmd_remind(cfg: dict, args=None, repo=None) -> int:
-    """Say whether a session this full should be wrapping up, and what that means here.
+    """Where the work stands at the end of a turn, and whether to wrap this session up.
+
+    **Two answers, and they go to two different readers.** `headline` is one short
+    block for the PERSON: the item, its bucket, its criteria, and what the completion
+    gate would still refuse on. It costs the session nothing and repeats as often as
+    the facts hold, because it replaces a question the founder was typing at the end
+    of nearly every session — the summary a session writes for itself does not say
+    what is actually complete, and this is derived rather than recalled. `note` is for
+    the AGENT and is rationed to once a session: delivering it RESUMES the run so it
+    can act, so a note that arrives every turn is a session that never gets to stop.
+
+    Two things earn the note. Context past the repo's threshold — unchanged, and it
+    lands near the end of a long session — and an item this session took reaching
+    complete, which is the early wrap a session that finishes with room to spare never
+    used to get. They say different first lines on purpose: one is "you are running
+    out of room", the other "the work you took is done".
 
     **It is handed a MEASUREMENT, never a transcript.** How many tokens a session is
     holding is a thing only its client can answer, and every client answers it its own
     way — so measuring is the client's half and it stays there. What is left is the
     part that is the same for all of them: the threshold, the window, the wording, the
     once-per-session rule, and whatever this repo adds. A harness command that took one
-    vendor's log file would be a harness that only works for that vendor.
+    vendor's log file would be a harness that only works for that vendor. The
+    measurement is now OPTIONAL: a client that cannot read its own usage still gets
+    everything the tree and git can answer.
 
     Prints one JSON object, or nothing at all. A caller wraps `headline` and `note` in
-    whatever its own surface expects; nothing here knows what that looks like.
+    whatever its own surface expects; nothing here knows what that looks like, and
+    `note` may be absent while a headline is not.
 
-    Silent on every path where it cannot be sure. A reminder that arrives at the wrong
-    moment is worse than one that never arrives — it teaches its reader to ignore the
-    next one, and there is only ever one that matters.
+    Silent on every path where it cannot be sure, and silence still means clean. A
+    reminder that arrives at the wrong moment is worse than one that never arrives —
+    it teaches its reader to ignore the next one.
     """
     args = args or {}
-    at = cfg["wrap"]["at_percent"]
-    window = cfg["wrap"]["context_tokens"]
-    try:
-        used = int(args.get("used") or 0)
-    except (TypeError, ValueError):
-        used = 0
-    if not at or not window or used <= 0:
-        return 0
-    percent = used / window * 100
-    if percent < at:
-        return 0
-
     repo = Path(repo) if repo is not None else Path.cwd()
-    if not _first_time(cfg, repo, args.get("session")):
-        return 0
+    session = args.get("session")
 
     from . import extend
     from .tree import cli
+    from .wrap import standing
     spec = cfg["hooks"]["stop"]
     extra = extend.run(spec.get("extend"), repo)
     if not spec.get("enabled", True):
@@ -1236,6 +1242,30 @@ def cmd_remind(cfg: dict, args=None, repo=None) -> int:
         print(json.dumps({"headline": "\n".join(extra), "note": "\n".join(extra)}))
         return 0
 
+    at = cfg["wrap"]["at_percent"]
+    window = cfg["wrap"]["context_tokens"]
+    try:
+        used = int(args.get("used") or 0)
+    except (TypeError, ValueError):
+        used = 0
+    percent = (used / window * 100) if (window and used > 0) else 0
+    full = bool(at and percent >= at)
+
+    where = standing(session, repo) if session else None
+    lines = _standing_lines(where) if where else []
+    # Why the note fires, most specific first, and each spends its OWN claim: a
+    # session told once that it is nearly full must still be told when the work it
+    # took is finished, and neither can quietly consume the other's turn to speak.
+    why = []
+    if where and where.finished and _first_time(cfg, repo, session, "wrap-finished"):
+        why.append(f"{_and_list(where.finished)} — the work you took — is complete, so "
+                   f"this session has reached its end rather than its limit.")
+    if full and _first_time(cfg, repo, session):
+        why.append(f"Context is {percent:.0f}% full ({used:,} of {window:,} tokens; "
+                   f"the threshold is {at}%).")
+    if not lines and not why and not extra:
+        return 0
+
     # Null when the repo names none, and then the reminder says to wrap without naming
     # a command — better than sending the reader to one that resolves for nobody.
     command = cfg["wrap"]["command"]
@@ -1250,28 +1280,93 @@ def cmd_remind(cfg: dict, args=None, repo=None) -> int:
     else:
         last = (f"`{cli()} kickoff <task>` — the prompt that opens the next session on "
                 "this work, with the method actually loaded.")
-    note = (
-        f"Context is {percent:.0f}% full ({used:,} of {window:,} tokens; the threshold "
-        f"is {at}%). Finish this session cleanly while there is still room to do it "
-        f"well:\n"
-        f"  1. `{cli()} handoff <task>` — status, next step, and what you learned.\n"
-        f"  2. Bring the task and epic docs to current — a stale brief is a trap for "
-        f"the next session.\n"
-        f"  3. Move anything finished: `{cli()} move <task> complete`.\n"
-        f"  4. Park anything still open: `{cli()} ask <task> --question \"…\"`.\n"
-        f"  5. {last}\n"
-        + (f"`{command}` runs all five. " if command else "")
-        + "Say so before you start, and if the user is mid-thought, finish their point "
-        "first — this is a reminder, not a stop."
-        + ("\n" + "\n".join(extra) if extra else "")
-    )
-    headline = (f"work: {percent:.0f}% of context used ({used // 1000}k/"
-                f"{window // 1000}k) — time to wrap up"
-                + (f" (`{command}`)." if command else "."))
-    print(json.dumps({"headline": headline, "note": note}))
+    note = ""
+    if why:
+        note = (
+            " ".join(why) + " Finish this session cleanly while there is still room "
+            "to do it well:\n"
+            f"  1. `{cli()} handoff <task>` — status, next step, and what you learned.\n"
+            f"  2. Bring the task and epic docs to current — a stale brief is a trap "
+            f"for the next session.\n"
+            f"  3. Move anything finished: `{cli()} move <task> complete`.\n"
+            f"  4. Park anything still open: `{cli()} ask <task> --question \"…\"`.\n"
+            f"  5. {last}\n"
+            + (f"`{command}` runs all five. " if command else "")
+            + "Say so before you start, and if the user is mid-thought, finish their "
+            "point first — this is a reminder, not a stop."
+            + ("\n" + "\n".join(extra) if extra else "")
+        )
+    elif extra:
+        note = "\n".join(extra)
+
+    head = list(lines)
+    if full:
+        # Said whether or not the note fired. The note is spent after one turn and the
+        # window keeps filling, so a person who saw "50%" once and nothing at 80% has
+        # been told less as it got worse.
+        head.append(f"{percent:.0f}% of context used ({used // 1000}k/"
+                    f"{window // 1000}k) — time to wrap up"
+                    + (f" (`{command}`)" if command else ""))
+    elif why:
+        head.append("the work you took is complete — time to wrap up"
+                    + (f" (`{command}`)" if command else ""))
+    # An extension with nothing of ours to say speaks for itself, exactly as it does
+    # on the path where the shipped half is switched off.
+    headline = ("work: " + "\n      ".join(head)) if head else "\n".join(extra)
+    out = {"headline": headline}
+    if note:
+        out["note"] = note
+    print(json.dumps(out))
     return 0
 
 
+def _and_list(names) -> str:
+    """`a`, `a and b`, `a, b and c` — for a sentence a person reads."""
+    names = list(names)
+    if len(names) < 3:
+        return " and ".join(names)
+    return ", ".join(names[:-1]) + f" and {names[-1]}"
+
+
+def _standing_lines(where) -> list:
+    """The bottom line, in as few words as it can be said in.
+
+    **What a person cannot get from a session's own summary**, which is where this
+    came from: whether the work is actually complete, and where the item, its epic
+    and the cut stand. So every line is derived — the bucket, the criteria ratio, the
+    completion gate's own verdict — and none of it is this session's account of
+    itself.
+
+    The criteria ratio carries the "not done" case on its own, so the gate's reason
+    is only shown once they are all ticked and something else is still holding: with
+    boxes left unchecked the gate's first reason IS the boxes, and printing both says
+    one thing twice.
+    """
+    out = []
+    for held in where.held:
+        task = held.task
+        bits = [task.status]
+        if held.total:
+            bits.append(f"{held.total - len(held.unchecked)}/{held.total} criteria")
+        if not held.unchecked and held.reasons:
+            # Cut at the em dash: every reason the gate gives names the fix after one,
+            # and the fix is the note's business rather than this line's.
+            bits.append(held.reasons[0].split(" — ")[0])
+        elif not held.reasons:
+            bits.append("READY TO COMPLETE")
+        out.append(f"{task.name} — " + " · ".join(bits))
+    for name in where.finished:
+        out.append(f"{name} — complete")
+    if where.loose:
+        shown = ", ".join(where.loose[:3])
+        more = f" and {len(where.loose) - 3} more" if len(where.loose) > 3 else ""
+        out.append(f"{len(where.loose)} file(s) outside the board NOT IN GIT: "
+                   f"{shown}{more}")
+    for cut in where.cuts:
+        out.append(f"cut {cut} — every task complete, not released")
+    return out
+
+
 def _first_time(cfg: dict, repo, session, what="wrap-reminded") -> bool:
     """Claim one of the things this session is told once, or say it is already spent.
 

package/harness/harness/gate.py

@@ -555,6 +555,27 @@ def _observed_acs(task) -> set:
     return out
 
 
+def criteria(task) -> tuple:
+    """(still unchecked, how many there are) over a task's acceptance criteria.
+
+    One reader for the checkboxes, because two things judge a task by them: the
+    completion gate REFUSES on the unchecked ones, and the end-of-turn line prints
+    the ratio to a person who is deciding whether the work is finished. A second
+    regex over the same boxes would be a second answer to whether a task is done,
+    and the one on screen is the one that gets believed.
+
+    A scaffold's placeholder criterion counts as neither. It is a template line
+    rather than an unmet promise, and refusing on it would make every task that
+    never edited its brief permanently incompletable — which trains people to
+    reach for `--accept`.
+    """
+    body = split_frontmatter((task.folder / "task.md").read_text())[1]
+    rows = [(mark, text) for mark, text
+            in re.findall(r"^\s*-\s*\[([ xX])\]\s*(.+)$", body, re.MULTILINE)
+            if not text.strip().startswith("<!--")]
+    return [text for mark, text in rows if mark == " "], len(rows)
+
+
 def _last_verify(task) -> tuple:
     """(passed, sha, when) from the newest recorded verify run, or (False, "", "")."""
     entries = as_list(task.fm.get("verified"))
@@ -602,12 +623,7 @@ def gate(root, task, accept: str = "", owner: str = "") -> list:
     """
     reasons = []
 
-    body = split_frontmatter((task.folder / "task.md").read_text())[1]
-    unchecked = re.findall(r"^\s*-\s*\[ \]\s*(.+)$", body, re.MULTILINE)
-    # A scaffold's placeholder criterion is a template line, not an unmet promise —
-    # refusing on it would mean every task that never edited its brief is
-    # permanently incompletable, which trains people to pass `--accept`.
-    unchecked = [u for u in unchecked if not u.strip().startswith("<!--")]
+    unchecked, _ = criteria(task)
     if unchecked:
         reasons.append(f"{len(unchecked)} unchecked acceptance criterion/criteria: "
                        + "; ".join(u[:60] for u in unchecked[:3]))

package/harness/harness/model.py

@@ -261,6 +261,20 @@ class Version:
         """Every task in one bucket, across the loose tier and every epic."""
         return self.tasks[name] + [t for e in self.epics for t in e.tasks[name]]
 
+    def finishable(self) -> bool:
+        """Whether every task in this cut is complete and nobody has closed it.
+
+        A cut has no status field — it is derived from its tasks, and with nothing
+        in flight it falls back to `planned`, which is the most misleading word
+        available for a cut whose work is finished. So the question is asked here,
+        once: the alignment sweep reports it and the end-of-turn line mentions it,
+        and two derivations of the same thing would eventually disagree about which
+        cuts are waiting on somebody.
+        """
+        tasks = self.all_tasks()
+        return bool(tasks) and not self.released and all(
+            t.status == "complete" for t in tasks)
+
     def status(self) -> str:
         """`released` if version.md carries a released date; `current` if any
         task is in-progress; otherwise `planned`."""

package/harness/harness/wrap.py

@@ -11,12 +11,111 @@ Everything here is a thing a session cannot reliably remember and a machine can
 answer. The sharpest is the first: work that is not in git. Three tasks have been
 completed on this board with their implementation in no commit anywhere, one of them
 the task about that exact failure.
+
+`standing` is the same knowledge at a smaller size, for the end of a turn rather than
+the end of a session. It exists because a session's own summary is the thing a person
+cannot use: measured against the founder, the complaint was never that the leftovers
+were hidden but that the closing prose _"is more confusing than helping… doesn't really
+say what's actually completed or not and where are we standing"_. So the bottom line is
+derived — the bucket, the criteria, what the completion gate would still refuse on — and
+the prose is left to say whatever it says.
 """
+from datetime import date, timedelta
 from pathlib import Path
+from typing import NamedTuple
+
+from . import gate, git, kickoff, report
+from .events import read as read_events
+from .model import locate, scan
+from .tree import cli, find_work_root, locate_work_root
+
+
+class Held(NamedTuple):
+    """One item this session took, and what stands between it and complete."""
+    task: object
+    unchecked: list
+    total: int
+    reasons: list
+
+
+class Standing(NamedTuple):
+    """Where the work stands, for a reader deciding whether this session is done."""
+    #: `Held` — taken here and still open.
+    held: list
+    #: Names taken here and moved to complete.
+    finished: list
+    #: Paths outside the board that are not in git.
+    loose: list
+    #: Cuts whose every task is complete and which nobody has released.
+    cuts: list
+
+    def anything(self) -> bool:
+        return bool(self.held or self.finished or self.loose or self.cuts)
+
+
+#: How far back to read the board's own history when working out what THIS session
+#: took. A session does not outlive a few days, and the log it is read out of grows
+#: forever — so the window bounds what a per-turn hook costs in a repo with a long
+#: history. A move older than this leaves its item UNNAMED rather than guessed at,
+#: which is the safe direction: the line going quiet about one item costs a person a
+#: question, and the line naming work that is not this session's costs it its
+#: credibility. A plain date rather than one of git's fuzzy forms, because the file
+#: backend compares it as text against an ISO timestamp and "3 days ago" would sort
+#: above every row there.
+_WINDOW_DAYS = 3
+
 
-from . import git, kickoff, report
-from .model import scan
-from .tree import cli, find_work_root
+def standing(session: str, repo: Path) -> Standing:
+    """What this session is answerable for, and what of it is still outstanding.
+
+    **Which items are THIS session's comes out of the commit trailers**, not out of
+    the items' own `sessions:` lists. Both record a session id and they record
+    different facts: the frontmatter names every run that TOUCHED an item — including
+    one that only wrote its brief and never picked it up — while a `moved` trailer
+    names the run that put the item in the bucket it is in. Calling somebody else's
+    work yours, in the one line a person reads to decide whether this session is
+    finished, is the failure that would make the whole line worth ignoring.
+
+    Answers with the board half empty rather than failing when there is no work tree:
+    this runs in every repo the harness is configured in, and code that is not in git
+    is knowable in all of them while a board is not.
+
+    Empty everywhere is the honest answer for a session that took nothing and left a
+    clean tree, and the caller then says nothing at all — silence has to keep meaning
+    clean or it stops meaning anything.
+    """
+    # Never conditioned on whether BOARD writes commit. That setting says how the
+    # tree is kept; whether a session's code reached git is a question about the
+    # repo, and it is the one worth answering in a repo that has not switched the
+    # board's own commits on.
+    loose = git.uncommitted_code(repo)
+    root, _, _ = locate_work_root()
+    if not root or not root.is_dir():
+        return Standing(held=[], finished=[], loose=loose, cuts=[])
+
+    since = (date.today() - timedelta(days=_WINDOW_DAYS)).isoformat()
+    mine = {}
+    for e in read_events(root, since=since):
+        if e.get("event") == "moved" and e.get("by") == session and e.get("name"):
+            mine[e["name"]] = e.get("to")
+
+    held, finished = [], []
+    for name in mine:
+        task = locate(root, name)
+        # Gone from the live board entirely — filed with a released cut, or renamed
+        # under us. The trailer is history and history is allowed to name something
+        # that has moved on; the bottom line is about now.
+        if not task:
+            continue
+        if task.status == "complete":
+            finished.append(name)
+        elif task.status in ("in-progress", "blocked"):
+            unchecked, total = gate.criteria(task)
+            held.append(Held(task=task, unchecked=unchecked, total=total,
+                             reasons=gate.gate(root, task)))
+
+    cuts = [v.name for v in scan(root)["versions"] if v.finishable()]
+    return Standing(held=held, finished=sorted(finished), loose=loose, cuts=cuts)
 
 
 def cmd_wrap(cfg: dict, args=None, repo=None) -> int:
@@ -40,14 +139,19 @@ def _uncommitted(repo) -> list:
 
     Said as a refusal to round down. "3 files uncommitted" reads as routine; a session
     that has just been told its work would be lost does not skim.
+
+    Asks whether git can answer before asking what it says, because the list itself
+    comes back empty from a repo git cannot read — and reporting that as "nothing
+    uncommitted" is the one wrong answer this section must not give.
     """
-    code, out, _ = git._git(repo, "status", "--porcelain", "--untracked-files=all")
+    code, _, _ = git._git(repo, "rev-parse", "--git-dir")
     if code != 0:
         return ["  code in git: cannot tell — this is not a git repo, or git did not "
                 "answer. Check it yourself before you walk away."]
-    paths = [line[3:] for line in out.splitlines() if len(line) > 3]
-    # The board writes itself, so its own churn is not somebody's unsaved work.
-    theirs = [p for p in paths if not p.startswith("work/")]
+    # One reader for what is outside the board, shared with the end-of-turn line and
+    # the completion gate: which paths ARE the board is configuration, and a second
+    # copy of that filter here read `work/` whatever the repo had said.
+    theirs = git.uncommitted_code(repo)
     if not theirs:
         ahead = _unpushed(repo)
         if ahead:
@@ -82,7 +186,13 @@ def _in_flight(root) -> list:
             if t.status == "in-progress"]
     if not live:
         return ["  in progress: nothing — the board claims nobody is on anything."]
-    named = "\n      ".join(f"{t.name} — {t.title}" for t in live)
+    # The ratio, because "move what finished" needs to know which of these is
+    # anywhere near finished, and the criteria are the only answer to that which
+    # does not depend on somebody's recollection.
+    named = "\n      ".join(
+        f"{t.name} — {t.title}"
+        + (f"  [{total - len(unchecked)}/{total} criteria]" if total else "")
+        for t in live for unchecked, total in [gate.criteria(t)])
     return [f"  in progress: {len(live)} item(s). Move what finished, park what did "
             f"not — the bucket IS the status:\n      {named}"]
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appchy/jarvis",
-  "version": "0.1.91",
+  "version": "0.1.93",
   "description": "Jarvis — local AI coding assistant CLI",
   "private": false,
   "type": "module",
@@ -59,14 +59,14 @@
     "@jarvis/agents": "1.0.0",
     "@jarvis/anthropic": "1.0.0",
     "@jarvis/board": "0.1.0",
+    "@jarvis/data": "0.1.0",
     "@jarvis/errors": "1.0.0",
     "@jarvis/logger": "1.0.0",
     "@jarvis/rpc": "1.0.0",
     "@jarvis/types": "1.0.0",
     "@jarvis/typescript-config": "1.0.0",
     "@jarvis/ui": "0.1.0",
-    "@jarvis/vitest-config": "1.0.0",
-    "@jarvis/data": "0.1.0"
+    "@jarvis/vitest-config": "1.0.0"
   },
   "scripts": {
     "dev": "tsx watch src/bin.ts start --foreground",