@appchy/jarvis 0.1.103 → 0.1.104

package/dist/bin.js

@@ -10260,7 +10260,7 @@ import { createRequire as createRequire2 } from "module";
 var _require = createRequire2(import.meta.url);
 var VERSION2 = _require("../package.json").version ?? "0.0.0";
 var IS_DEV = String(_require("../package.json").name ?? "").endsWith("-dev");
-var SHA = "c1072c2";
+var SHA = "9f128de";
 var BUILT = "2026-09-11";
 var BUILD = SHA ?? "source";
 var BUILD_LABEL = `${SHA ? `${VERSION2} (${SHA}${BUILT ? ` ${BUILT}` : ""})` : `${VERSION2} (source)`}${IS_DEV ? " \u2014 development build" : ""}`;

package/harness/harness/check.py

@@ -0,0 +1,94 @@
+"""Read the item against the repo, once per session, before the work resumes.
+
+Every lock in this repo is on the exit. The eight verify commands, the evidence
+check and the completion refusals all fire at `complete`, by which point the work is
+spent — so a session that picked up a brief describing a world that ended finds out
+last. This is the one door at the other end.
+
+**It checks the ITEM, not the edit**, and that is what makes it possible at all. The
+earlier framing — check the CHANGE before the first file is written — could not be
+built: the map's scope call takes prose, so nothing tied a check to anything on the
+board, and every way of inferring it was worse than the problem. A check whose input
+is the item has the attribution for free. (Founder, 2026-09-12.)
+
+**Once per session per item.** Not once per item: a fresh session continuing old work
+is exactly when a brief has had time to go stale and nobody has looked. Not once per
+session: a session that picks up a second item has read nothing about it.
+
+**It reports; it never refuses on what it finds.** A brief can drift because somebody
+else renamed a file, and making your completion wait on cleaning up their change is a
+tax on whoever finishes next. What IS refused at completion is the check never having
+run — the session is answerable for having looked, never for what the looking found.
+(Founder, 2026-09-12.)
+"""
+
+from pathlib import Path
+
+from .config import load as load_config
+from .drift import describe, drift
+
+
+def _state(root: Path):
+    """Where the per-session record lives — the same gitignored root the wrap
+    reminder and the rules-delivery markers already use, reached through the same
+    helper so a second answer cannot drift from theirs."""
+    from .config import _session_state
+    repo = root.parent
+    return _session_state(load_config(repo), repo)
+
+
+def _marker(root: Path, item: str, session: str) -> Path:
+    return _state(root) / "checked" / item / (session or "unknown")
+
+
+def documents(root: Path, task) -> list:
+    """What this item claims: its own brief, and the epic plan it executes against.
+
+    The epic is in because a task deliberately does NOT restate the design — that
+    lives in `epic.md` §Plan and is what the task is built against, so a path that
+    died there misleads exactly as much as one in the brief.
+    """
+    docs = []
+    brief = task.folder / "task.md"
+    if brief.is_file():
+        docs.append(str(brief.relative_to(root.parent)))
+    epic = task.folder.parent.parent / "epic.md"
+    if epic.is_file():
+        docs.append(str(epic.relative_to(root.parent)))
+    return docs
+
+
+def run(root: Path, task, session: str) -> list:
+    """Check the item and record that this session did. Returns the findings.
+
+    The record is written whether or not anything was found — it says the looking
+    happened, which is the only thing the completion gate asks about.
+    """
+    findings = drift(root.parent, documents(root, task))
+    marker = _marker(root, task.name, session)
+    try:
+        marker.parent.mkdir(parents=True, exist_ok=True)
+        marker.write_text("")
+    except OSError:
+        pass  # unwritable state means the gate will ask again, which is the safe way to be wrong
+    return findings
+
+
+def checked(root: Path, task, session: str) -> bool:
+    """Has THIS session read THIS item against the repo?
+
+    A session id we never got is treated as checked. The alternative is refusing
+    every completion that arrives without one — a plain terminal, a script, another
+    agent — over a record none of them could ever have written.
+    """
+    if not session:
+        return True
+    return _marker(root, task.name, session).exists()
+
+
+def report(root: Path, task, session: str) -> str:
+    """The lines a pickup prints. Named separately from `run` so the gate can ask
+    whether the looking happened without printing a second copy of it."""
+    findings = run(root, task, session)
+    head = f"  read {task.name} against the repo:"
+    return f"{head}\n{describe(findings)}"

package/harness/harness/gate.py

@@ -623,6 +623,17 @@ def gate(root, task, accept: str = "", owner: str = "") -> list:
     """
     reasons = []
 
+    # Answerable for having LOOKED, never for what the looking found. The check
+    # reports drift and refuses nothing over it — a brief goes stale because of
+    # somebody else's rename as often as your own, and taxing whoever finishes next
+    # for that is the shape of defect this gate exists to stop, not to add.
+    from . import check as _check
+    from .model import current_session_id as _sid
+    if not _check.checked(root, task, _sid()):
+        reasons.append(f"this session has not read {task.name} against the repo — "
+                       f"`jarvis work check {task.name}`. It reports what the brief "
+                       f"names that is no longer here; nothing is refused over what it finds")
+
     unchecked, _ = criteria(task)
     if unchecked:
         reasons.append(f"{len(unchecked)} unchecked acceptance criterion/criteria: "

package/harness/harness/task.py

@@ -357,6 +357,17 @@ def cmd_move(args) -> int:
     events.append(root, "moved", name, **{"from": task.status, "to": to})
     print(f"moved '{name}': {task.status}/ -> {to}/")
 
+    # Picking it up is the moment to find out the brief describes something that is
+    # no longer here — cheap to act on now, and the alternative is finding out by
+    # walking into it. Reported, never refused: a path can die because of somebody
+    # else's rename, and completion is not the place to pay for that.
+    if to == "in-progress":
+        from . import check as _check
+        from .model import current_session_id as _sid
+        moved_task = locate(root, name)
+        if moved_task:
+            print(_check.report(root, moved_task, _sid()))
+
     # No handoff is scaffolded on pickup — `handoff.md` is created on demand via
     # `jarvis work handoff` only when a task actually hands across conversations
     # (a blank scaffold on every pickup was noise). Working checklists live in
@@ -377,6 +388,23 @@ def cmd_move(args) -> int:
 
     _sync(root)
     return 0
+def cmd_check(args) -> int:
+    """Read an item against the repo and say where the two have come apart.
+
+    The same thing `move <name> in-progress` prints, reachable on its own — because
+    the completion gate asks whether this session has looked, and a gate naming a
+    command that does not exist is the trap this cut exists to remove.
+    """
+    from . import check as _check
+    root = find_work_root()
+    name = args["name"]
+    task = locate(root, name)
+    if not task:
+        die(missing(root, name))
+    print(_check.report(root, task, current_session_id()))
+    return 0
+
+
 def cmd_handoff(args) -> int:
     root = find_work_root()
     name = args["name"]

package/harness/test_work.py

@@ -25,6 +25,12 @@ tempfile.tempdir = _TMP
 
 sys.path.insert(0, str(Path(__file__).resolve().parent))
 from harness.ids import LEDGER as L  # noqa: E402 — fixtures render in the repo's dialect
+
+# A suite that inherits the developer's own session id answers differently depending
+# on who ran it — and it does now, because the completion gate asks whether THIS
+# session read the item against the repo. Cleared once here; the handful of tests
+# that are about session identity set it themselves and put it back.
+os.environ.pop("CLAUDE_CODE_SESSION_ID", None)
 from harness import (align, architecture, autonomy, branches, config, coverage, epic,  # noqa: E402
                      events, extend, frontmatter, gate, generate, git, ids, kickoff,
                      lint, model, peers, registry, report, safety, scaffold,
@@ -7260,9 +7266,11 @@ def test_a_finished_cut_is_ready_rather_than_planned_and_goes_back_when_reopened
         # Adding `ready` to the derivation took the whole README generator down
         # through a bare dict lookup, which is a lot of blast radius for a label.
         assert "ready" in generate._version_section(cut, root)
-        # `report` renders the same status through its own map; both now fall back
-        # to printing an unknown state rather than raising.
-        assert report is not None
+        # `jarvis work list` renders the same status through its own map in
+        # `report`; both now fall back to printing an unknown state rather than
+        # raising. Not asserted here — it prints rather than returns, and a test
+        # that captures stdout to prove a dict has a key is worth less than the
+        # sentence saying both were changed together.
 
         # Reopened: straight back to current, with nothing to undo by hand.
         (v / "in-progress").mkdir(exist_ok=True)
@@ -7576,6 +7584,93 @@ def test_a_brief_that_still_describes_the_repo_says_so_rather_than_saying_nothin
     assert "still describes the repo" in describe([])
 
 
+def test_completing_asks_whether_this_session_read_the_item_against_the_repo():
+    # The one thing this refuses: not having looked. Never what the looking found.
+    import harness.gate as gate, harness.model as model, harness.check as check
+    with tempfile.TemporaryDirectory() as tmp:
+        repo = _git_repo(tmp, push=False)
+        root = repo / "work"
+        v = root / "versions" / "26-cut"
+        t = v / "an-epic" / "in-progress" / "alpha"
+        t.mkdir(parents=True)
+        (v / "version.md").write_text(
+            "---\ncreated: 2026-09-01\norder: 26\noutcome: a user can do it\n---\n\n# A cut\n")
+        (v / "an-epic" / "epic.md").write_text(
+            "---\ntype: epic\nowner: quality\n---\n\n# An epic\n")
+        (t / "task.md").write_text("---\npriority: P0\n---\n\n# Alpha\n")
+        keep = os.environ.get("CLAUDE_CODE_SESSION_ID")
+        os.environ["CLAUDE_CODE_SESSION_ID"] = "2222bbbb-0000-0000-0000-000000000000"
+        try:
+            task = model.locate(root, "alpha")
+            assert any("read alpha against the repo" in r for r in gate.gate(root, task))
+            check.run(root, task, "2222bbbb-0000-0000-0000-000000000000")
+            assert not any("read alpha against the repo" in r for r in gate.gate(root, task))
+        finally:
+            if keep is None: os.environ.pop("CLAUDE_CODE_SESSION_ID", None)
+            else: os.environ["CLAUDE_CODE_SESSION_ID"] = keep
+
+
+def test_a_second_session_on_the_same_item_is_asked_again():
+    # The drift case the founder named: continuing old work in a new session is
+    # exactly when a brief has had time to go stale and nobody has looked.
+    import harness.model as model, harness.check as check
+    with tempfile.TemporaryDirectory() as tmp:
+        repo = _git_repo(tmp, push=False)
+        root = repo / "work"
+        v = root / "versions" / "26-cut"
+        t = v / "an-epic" / "in-progress" / "alpha"
+        t.mkdir(parents=True)
+        (v / "version.md").write_text(
+            "---\ncreated: 2026-09-01\norder: 26\noutcome: a user can do it\n---\n\n# A cut\n")
+        (v / "an-epic" / "epic.md").write_text(
+            "---\ntype: epic\nowner: quality\n---\n\n# An epic\n")
+        (t / "task.md").write_text("---\npriority: P0\n---\n\n# Alpha\n")
+        task = model.locate(root, "alpha")
+        check.run(root, task, "first-session")
+        assert check.checked(root, task, "first-session")
+        assert not check.checked(root, task, "second-session")
+
+
+def test_a_caller_with_no_session_is_not_refused_over_a_record_it_could_never_write():
+    # A plain terminal, a script, another agent. Refusing those would be refusing
+    # everything that is not Claude Code over a marker none of them can leave.
+    import harness.model as model, harness.check as check
+    with tempfile.TemporaryDirectory() as tmp:
+        repo = _git_repo(tmp, push=False)
+        root = repo / "work"
+        v = root / "versions" / "26-cut"
+        t = v / "an-epic" / "in-progress" / "alpha"
+        t.mkdir(parents=True)
+        (v / "version.md").write_text(
+            "---\ncreated: 2026-09-01\norder: 26\noutcome: a user can do it\n---\n\n# A cut\n")
+        (v / "an-epic" / "epic.md").write_text(
+            "---\ntype: epic\nowner: quality\n---\n\n# An epic\n")
+        (t / "task.md").write_text("---\npriority: P0\n---\n\n# Alpha\n")
+        assert check.checked(root, model.locate(root, "alpha"), "")
+
+
+def test_the_check_reads_the_epic_plan_too_not_only_the_brief():
+    # A task deliberately does not restate the design — it lives in epic.md §Plan and
+    # is what the task is built against, so a path that died there misleads as much.
+    import harness.model as model, harness.check as check
+    with tempfile.TemporaryDirectory() as tmp:
+        repo = _git_repo(tmp, push=False)
+        root = repo / "work"
+        v = root / "versions" / "26-cut"
+        e = v / "an-epic"
+        (e / "in-progress" / "alpha").mkdir(parents=True)
+        (v / "version.md").write_text(
+            "---\ncreated: 2026-09-01\norder: 26\noutcome: a user can do it\n---\n\n# A cut\n")
+        (e / "epic.md").write_text("---\ntype: epic\nowner: quality\n---\n\n"
+                                   "# An epic\n\n## Plan\n\nbuilt on `src/long-gone.ts`\n")
+        (e / "in-progress" / "alpha" / "task.md").write_text(
+            "---\npriority: P0\n---\n\n# Alpha\n")
+        _git(repo, "add", "-A"); _git(repo, "commit", "-m", "seed")
+
+        found = check.run(root, model.locate(root, "alpha"), "s1")
+        assert [f[2] for f in found] == ["src/long-gone.ts"]
+
+
 if __name__ == "__main__":
     tests = [v for k, v in sorted(globals().items())
              if k.startswith("test_") and callable(v)]

package/harness/work.py

@@ -135,7 +135,7 @@ sys.path.insert(0, str(Path(__file__).resolve().parent))
 
 from harness.tree import die, locate_work_root
 from harness import events, git
-from harness.task import cmd_code, cmd_handoff, cmd_move, cmd_new, cmd_path, cmd_place, cmd_plan, cmd_session
+from harness.task import cmd_check, cmd_code, cmd_handoff, cmd_move, cmd_new, cmd_path, cmd_place, cmd_plan, cmd_session
 from harness.epic import cmd_epic_new
 from harness.version import cmd_archive, cmd_release, cmd_version_new
 from harness.product import cmd_feature_new
@@ -167,7 +167,7 @@ SUBCOMMANDS = (
     "find", "list", "readme", "move", "plan", "session", "kickoff", "path", "code",
     "domain-new", "system-new", "where", "rules", "align", "wrap", "coverage",
     "migrate", "next", "status", "drop", "ask", "answer", "needs", "verify",
-    "observed", "log", "digest", "sync",
+    "observed", "log", "digest", "sync", "check",
 )
 
 
@@ -450,6 +450,11 @@ def dispatch(cmd, pos, flags, cfg) -> int:
         if not pos:
             die("usage: jarvis work handoff <name>")
         return cmd_handoff({"name": pos[0]})
+    if cmd == "check":
+        if not pos:
+            die("usage: jarvis work check <name>   "
+                "(reads the item's brief and its epic plan against the repo)")
+        return cmd_check({"name": pos[0]})
     if cmd == "release":
         if not pos:
             die("usage: jarvis work release <v>")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appchy/jarvis",
-  "version": "0.1.103",
+  "version": "0.1.104",
   "description": "Jarvis — local AI coding assistant CLI",
   "private": false,
   "type": "module",
@@ -59,12 +59,12 @@
     "@jarvis/agents": "1.0.0",
     "@jarvis/anthropic": "1.0.0",
     "@jarvis/board": "0.1.0",
-    "@jarvis/logger": "1.0.0",
-    "@jarvis/errors": "1.0.0",
     "@jarvis/data": "0.1.0",
+    "@jarvis/errors": "1.0.0",
     "@jarvis/rpc": "1.0.0",
-    "@jarvis/typescript-config": "1.0.0",
     "@jarvis/types": "1.0.0",
+    "@jarvis/logger": "1.0.0",
+    "@jarvis/typescript-config": "1.0.0",
     "@jarvis/ui": "0.1.0",
     "@jarvis/vitest-config": "1.0.0"
   },