@appchy/jarvis 0.1.92 → 0.1.94

package/harness/harness/config.py

@@ -1001,6 +1001,19 @@ def session_pointers(cfg: dict, repo=None) -> list:
                    f"always high. Until it fires or the user asks, keep working"
                    + (f"; then run `{cfg['wrap']['command']}`." if cfg["wrap"]["command"]
                       else "."))
+    # Said whether or not a threshold is configured, because neither half of it
+    # depends on one. The second sentence is the one that changes how a turn ENDS:
+    # the founder's standing complaint was never that the leftovers were hidden, it
+    # was that a session's own closing prose does not say what is actually finished
+    # — so the machine-derived version is on screen already, and re-narrating it in
+    # paragraphs competes with it rather than adding to it.
+    if cfg["hooks"]["stop"]["enabled"]:
+        out.append("the same hook wraps you EARLY when an item you took reaches "
+                   "complete — that is the end of the work, not a warning about "
+                   "room. At the end of every turn it also shows the person the "
+                   "derived standing: the item, its bucket, its criteria and what "
+                   "the completion gate would still refuse on. Do not restate any "
+                   "of that in prose — say what you decided and what you need.")
     return out
 
 
@@ -1090,8 +1103,13 @@ def _session_state(cfg: dict, repo) -> Path:
     """Where per-machine, per-session markers live — beside the coverage shard, which
     is already the gitignored root for facts that are about this checkout and not
     about the repo. One reader, because the hook that replays these has the default
-    baked in and a second answer here would silently stop matching it."""
-    return repo / Path(cfg["coverage"]["shard"]).parent
+    baked in and a second answer here would silently stop matching it.
+
+    WHICH directory that is comes from `shard.state_root`, shared with the check that
+    decides whether a file is somebody's uncommitted work — the two have to name the
+    same place, or the harness reports its own markers as a person's."""
+    from .shard import state_root
+    return repo / state_root(cfg["coverage"]["shard"])
 def _remember_systems(cfg: dict, repo, session, systems, off=False) -> None:
     """Leave this repo's file-to-system declarations where the caller can replay them.
 
@@ -1193,41 +1211,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 +1260,33 @@ 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}%).")
+    # `full` earns a headline of its own even once the note is spent: the window
+    # keeps filling after the one turn that was allowed to interrupt, and a person
+    # who saw 50% once and nothing at 90% was told less as it got worse.
+    if not lines and not why and not full 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 +1301,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/git.py

@@ -123,9 +123,20 @@ def uncommitted_code(repo) -> list:
     this check's business.
 
     Claims and the run file are excluded for the reason they are never committed —
-    they are one machine's coordination, true for minutes.
+    they are one machine's coordination, true for minutes. **So is the harness's own
+    scratch root**, and that exclusion was missing: the coverage shards, the id
+    allocator and the session markers are all written by the harness itself, and in
+    a repo that had not gitignored them by hand this named them as somebody's
+    unsaved work — then refused every completion, because a verify run drops a shard
+    and the gate reads this. A check that accuses a person of leaving behind a file
+    the harness just wrote is one nobody can act on.
     """
+    from .shard import DIR, state_root
+
     board = [r.rstrip("/") for r in (GIT.get("paths") or [])]
+    scratch = state_root(DIR)
+    if scratch:
+        board.append(scratch)
     code, out, _ = _git(repo, "status", "--porcelain", "-z",
                         "--untracked-files=all", "--no-renames")
     if code != 0:

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/shard.py

@@ -20,6 +20,26 @@ from typing import NamedTuple
 #: close a cycle.
 DIR = ".work/coverage"
 
+def state_root(configured: str) -> str:
+    """The directory this checkout's own scratch hangs off, repo-relative.
+
+    The shards, the session markers and the id allocator all live under it, and
+    four docstrings in this harness call it gitignored on purpose — while nothing
+    made it so. So it is DERIVED from where shards are configured to land rather
+    than named again wherever somebody needs it: a repo that moved its shards moved
+    this, and a second spelling would stop matching without saying so.
+
+    Falls back to the configured directory itself when that is one segment deep.
+    The parent of `coverage` is the repo, and a check that excluded the repo would
+    be vacuous rather than wrong-looking — which is the failure that cannot be seen
+    from its output.
+    """
+    d = str(configured or "").replace("\\", "/").strip("/")
+    if not d:
+        return ""
+    return d.rsplit("/", 1)[0] if "/" in d else d
+
+
 #: Precedence when several sites claim one criterion — the SAME rank both
 #: reporters already apply within a single runner. Anything unrecognised ranks
 #: below `passed`, so a shard that learns a new status can never silently

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}"]