@appchy/jarvis 0.1.102 → 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 = "2ef6df4";
+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/drift.py

@@ -0,0 +1,177 @@
+"""Does this brief still describe the repo?
+
+A brief is read and believed. Nothing checks that what it names still exists, so a
+session plans against a world that ended, and the first sign is the session hitting
+a path that is not there. Measured on this repo, 2026-09-11:
+
+what THIS code reports over the whole board, run against it once it was finished:
+
+    queued + in-flight briefs    35 gone    29 moved
+    live governance              20 gone     7 moved
+    shipped / archived briefs   240 gone   199 moved
+
+The last row is fine, and is exactly why this is aimed at an ITEM rather than swept
+over the tree: a completed brief records what was believed then and makes no claim
+about now. The first two rows are the defect — in the exploratory pass that led
+here, one path in six named by work a session was about to pick up pointed at a file
+that does not exist. Across 113 session transcripts in this repo, 50 (44%) hit a
+path that was not there and 24 (21%) said in so many words that a brief or doc was
+stale: _"the old `unify-the-tool-surface` brief's three-way table describes a package
+that no longer exists"_.
+
+**Paths, and nothing else.** Two other drift classes were measured and dropped.
+Rule ids came back 0% dead in live governance and live work — the only unresolvable
+one was a retired `S-15` in old briefs, so an id checker would be machinery for a
+problem this repo does not have. Work-item references came back 34% "missing" and
+were almost entirely false: epic names whose `epic.md` release deletes by design,
+and eslint rule names like `async-return-type` that a kebab-case regex cannot tell
+from an item id.
+
+**The resolver is the whole trustworthiness of this.** A first pass that checked
+paths against the repo root alone called 37% of them missing; resolving the way a
+writer actually means them — relative to the file, under `work/`, under `apps/cli/`
+— took that to 16%. A check that cries wolf is the failure this epic keeps finding,
+so a path is reported only when every honest reading of it fails.
+
+**Moved and gone are different findings.** A file whose basename lives somewhere
+else is a link to fix; a file with no trace anywhere is a brief describing something
+that does not exist, and that is a rethink. Saying "missing" for both would bury the
+second in the first, which is the more common and less important one.
+"""
+
+import re
+import subprocess
+from collections import defaultdict
+from pathlib import Path
+
+#: A path a brief NAMES, in backticks, with a real extension — `packages/x/y.ts`,
+#: optionally with a `:42` line. Bare prose paths are out: "the work/ tree" is not a
+#: claim about a file, and treating it as one is how a checker starts arguing with
+#: sentences. A markdown link is out too — `links.py` already owns those, and owns
+#: repairing them, which this never does.
+NAMED = re.compile(r"`([A-Za-z0-9_./-]+\.(?:ts|tsx|js|mjs|cjs|py|json|md|yml|yaml|sql))(?::\d+)?`")
+
+#: Never walked. Mirrors `links.py`'s list for the same reason: these dominate a
+#: repo's file count and no brief names anything inside them.
+SKIP = {"node_modules", ".git", "build", "dist", ".next", "target", "vendor",
+        ".data", ".work", "coverage", ".venv", "__pycache__"}
+
+
+def _tracked(repo: Path) -> set:
+    """What git has. Tracked files rather than a walk: a path that exists only in
+    somebody's working tree is not something a brief can rely on, and a walk would
+    also have to re-learn every ignore rule git already knows."""
+    try:
+        out = subprocess.run(["git", "ls-files"], cwd=repo, capture_output=True,
+                             text=True, timeout=30)
+        return set(out.stdout.split()) if out.returncode == 0 else set()
+    except (OSError, subprocess.SubprocessError):
+        return set()
+
+
+def _roots(owner: str) -> list:
+    """Every place a writer might mean, given the file the path was written in.
+
+    A brief in `work/architecture/` writes `product/board.md` meaning its sibling;
+    one anywhere writes `harness/gate.py` meaning the tree under `apps/cli`. Both
+    read as missing against the repo root alone, and both are correct English.
+    """
+    here = str(Path(owner).parent)
+    return ["", here, "work", "apps/cli"]
+
+
+def _resolve(path: str, owner: str, tracked: set) -> str:
+    for root in _roots(owner):
+        candidate = str(Path(root) / path) if root else path
+        if str(Path(candidate)) in tracked:
+            return candidate
+    return ""
+
+
+#: Build output. Git does not track it, so the tracked set calls it absent — but it
+#: exists on a machine that has built, and a brief naming `dist/hooks/session-start.js`
+#: is right. Caught by dogfooding this on its own board, where it was one of four
+#: findings and the only kind that was wrong.
+BUILT = {"dist", "build", ".next", "out", "node_modules", ".data", ".work"}
+
+
+def _unjudgeable(path: str) -> bool:
+    """Paths this cannot have an opinion about, kept apart from paths it says are
+    fine — silence here means *not my question*, not *checked and good*.
+
+    Two kinds. Build output, which git never tracks and which is present anyway on
+    any machine that has built. And anything climbing out of the repo: a brief that
+    names `../docdoc/.claude/skills/work/SKILL.md` is talking about a sibling repo,
+    whose contents this checkout cannot see and must not pronounce on.
+    """
+    return path.startswith("../") or bool(BUILT & set(Path(path).parts))
+
+
+def named_paths(text: str):
+    """Every path a document names, with the line it is on. Deduplicated per line so
+    one path written twice in a sentence is one finding, not two."""
+    seen = set()
+    for n, line in enumerate(text.splitlines(), 1):
+        for m in NAMED.finditer(line):
+            key = (m.group(1), n)
+            if key in seen:
+                continue
+            seen.add(key)
+            yield m.group(1), n
+
+
+def drift(repo: Path, docs, tracked=None) -> list:
+    """What the given documents claim that the repo no longer bears out.
+
+    Each finding is `(doc, line, path, state, where)` — `state` is `"moved"` with
+    `where` naming the file that now carries that basename, or `"gone"` with no
+    `where` at all. A doc that cannot be read is skipped rather than reported: this
+    answers a question about content, and "I could not open it" is not an answer to
+    that question.
+    """
+    tracked = _tracked(repo) if tracked is None else tracked
+    by_base = defaultdict(list)
+    for t in tracked:
+        by_base[Path(t).name].append(t)
+
+    found = []
+    for doc in docs:
+        rel = str(Path(doc).relative_to(repo)) if Path(doc).is_absolute() else str(doc)
+        try:
+            text = (repo / rel).read_text(errors="ignore")
+        except OSError:
+            continue
+        for path, line in named_paths(text):
+            if "/" not in path or _unjudgeable(path):
+                continue  # no location to check, or not this repo's to answer for
+            if _resolve(path, rel, tracked):
+                continue
+            elsewhere = sorted(by_base.get(Path(path).name, []))
+            if elsewhere:
+                found.append((rel, line, path, "moved", elsewhere[0]))
+            else:
+                found.append((rel, line, path, "gone", ""))
+    return found
+
+
+def describe(findings: list) -> str:
+    """The report a session reads. Gone first and counted separately, because a
+    brief naming something that does not exist anywhere is the finding worth acting
+    on, and a moved file is a link to fix."""
+    if not findings:
+        return "  nothing named in this item has moved or gone — the brief still describes the repo."
+
+    gone = [f for f in findings if f[3] == "gone"]
+    moved = [f for f in findings if f[3] == "moved"]
+    out = []
+    if gone:
+        out.append(f"  {len(gone)} path(s) named here do not exist anywhere — the brief "
+                   f"describes something that is not in the repo:")
+        for doc, line, path, _, _ in gone:
+            out.append(f"    {path}\n        named at {doc}:{line}")
+    if moved:
+        out.append(f"  {len(moved)} path(s) moved — the file is still here under another name:")
+        for doc, line, path, _, where in moved:
+            out.append(f"    {path}\n        now {where}  ({doc}:{line})")
+    out.append("  Fix the brief as part of this work; nothing is refused over what this found.")
+    return "\n".join(out)

package/harness/harness/epic.py

@@ -220,6 +220,31 @@ _DURABLE_SECTIONS = ("## Governance this implies", "## Non-goals", "### Settled"
                      "### Forward-compat")
 
 
+def removal_cost(version) -> tuple:
+    """What releasing this cut would delete: `(plans, bytes, sections)`.
+
+    One derivation, because two surfaces quote this price now — the notice
+    `release` prints just before the unlink, and the line `status` shows a person
+    deciding whether to run it at all. A warning and a confirmation that disagreed
+    about the cost would make both worth less than either.
+
+    `sections` is every durable heading found across the plans, deduplicated: it is
+    what a reader needs to judge whether the text is safe to lose, and it is the
+    half that is not recoverable from a byte count.
+    """
+    plans = [e for e in version.epics if e.planned]
+    total, held = 0, set()
+    for e in plans:
+        try:
+            text = e.md.read_text()
+        except OSError:                               # pragma: no cover — defensive
+            continue
+        total += len(text.encode())
+        held.update(h.split("## ")[-1].split("### ")[-1]
+                    for h in _DURABLE_SECTIONS if h in text)
+    return len(plans), total, sorted(held)
+
+
 def _cost_of_removing(version, root) -> list:
     """What this release is about to delete, as lines a person can act on.
 

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

@@ -35,11 +35,16 @@ def _epic_block(e, root: Path) -> str:
     return f"#### Epic — {head}\n\n" + _table(tasks, root)
 def _version_section(v: Version, root: Path) -> str:
     status = v.status()
+    # `.get` rather than `[...]`: a state this map has not heard of should print
+    # itself in the badge, not take the whole README down. It did — adding `ready`
+    # to the derivation raised `KeyError` here and killed every board write until
+    # this line was found, which is a lot of blast radius for a label.
     badge = {
         "released": f"released {v.released}",
+        "ready": "ready to close · every task complete",
         "current": "current",
         "planned": "planned" + (f" · target {v.target}" if v.target else ""),
-    }[status]
+    }.get(status, status)
     link = f"[{v.title}]({_relpath_from_readme(v.md, root)})"
     head = f"### Version — {link} _( {badge} )_"
     if v.outcome:

package/harness/harness/model.py

@@ -276,10 +276,26 @@ class Version:
             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`."""
+        """`released` if version.md carries a released date; `ready` if every task
+        is complete and nobody has closed it; `current` if any task is in-progress;
+        otherwise `planned`.
+
+        **`ready` is the state that was missing, and its absence printed the most
+        misleading word available.** A cut with 120 tasks done and nothing open fell
+        through to `planned` — *not started yet* — so nothing on any surface said the
+        work was finished or that closing it was a person's move. It is derived from
+        the same predicate the alignment sweep and the end-of-turn line already use,
+        and it is reversible by construction: reopening one task makes `finishable`
+        false again and the cut goes straight back to `current`.
+
+        It says READY rather than *finished* deliberately. The word a person acts on
+        is the one about what is owed, and `finished` sits one column from `released`
+        on the same screen — a skim would read the cut as already out.
+        """
         if self.released:
             return "released"
+        if self.finishable():
+            return "ready"
         if any(t.status == "in-progress" for t in self.all_tasks()):
             return "current"
         return "planned"

package/harness/harness/report.py

@@ -76,11 +76,15 @@ def cmd_list(args) -> int:
         return 0
 
     for v in sorted(s["versions"], key=lambda x: (x.order, x.name)):
+        # Same shape, same reason as the README badge: an unknown state prints
+        # itself rather than raising out of `jarvis work list`, which is the one
+        # command everything else is read through.
         flag = {
             "released": f" · released {v.released}",
+            "ready": " · ready to close",
             "current": " · current",
             "planned": " · planned",
-        }[v.status()]
+        }.get(v.status(), f" · {v.status()}")
         target = f" · target {v.target}" if v.target and not v.released else ""
         print(f"\nVERSION  {v.name} — {v.title}{flag}{target}")
         if v.outcome:

package/harness/harness/shift.py

@@ -27,6 +27,7 @@ from .tree import BLOCKED, BUCKETS, die, find_work_root, rel
 from .frontmatter import rewrite_file
 from .model import locate, missing, record_session, scan
 from .generate import _sync
+from .epic import removal_cost
 from . import autonomy, events, links, peers
 # The ceiling is read through the MODULE, never bound in with `from … import`.
 # A `from .autonomy import CEILING` captures the value at import time, so
@@ -278,11 +279,24 @@ def cmd_status(args) -> int:
 
     waiting = [(t, q) for v in s["versions"] for t in v.all_tasks()
                for q in _open_questions(t)]
-    print(f"WAITING ON YOU  ({len(waiting)})")
+    # A finished cut nobody has closed IS waiting on a person, and until now nothing
+    # said so anywhere. Closing one is deliberately not automatic — `release` deletes
+    # every epic plan and cannot be undone — so this announces and never acts, and it
+    # quotes the price so the decision is made with it visible rather than after.
+    ready = [v for v in s["versions"] if v.finishable()]
+    print(f"WAITING ON YOU  ({len(waiting) + len(ready)})")
+    for v in ready:
+        plans, size, held = removal_cost(v)
+        cost = ""
+        if plans:
+            cost = (f" — releasing deletes {plans} epic plan(s), {size:,} bytes"
+                    + (f", holding §{', §'.join(held)}" if held else ""))
+        print(f"  {v.name}: every task is complete and the cut is still open "
+              f"— `jarvis work release {v.name}`{cost}")
     for t, q in waiting[:8]:
         parts = q.split("  ")
         print(f"  {t.name}: {'  '.join(parts[2:]) if len(parts) > 2 else q}")
-    if not waiting:
+    if not waiting and not ready:
         print("  nothing — the shift is not blocked on you.")
 
     # One read of the record, shared by every section below. It is a `git log`

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,
@@ -7240,6 +7246,46 @@ def test_a_cut_with_every_task_complete_says_it_is_finishable():
             config.apply(config.DEFAULTS)
 
 
+def test_a_finished_cut_is_ready_rather_than_planned_and_goes_back_when_reopened():
+    # `planned` means NOT STARTED YET, and it is what a cut with every task complete
+    # printed — the most misleading word available for work that is finished. The
+    # founder asked three times to close 01-one-board and the board kept calling it
+    # unstarted. Derived and reversible in both directions, like the epic tier:
+    # reopening one task has to take the state straight back.
+    with tempfile.TemporaryDirectory() as tmp:
+        v = _tree(tmp)
+        root = Path(tmp)
+        _task(v / "complete", "one")
+        _task(v / "complete", "two")
+
+        cut = model.scan(root)["versions"][0]
+        assert cut.finishable() and cut.status() == "ready", \
+            "every task complete and nobody closed it is its own state"
+
+        # Both surfaces that render a status must survive one they have not met.
+        # 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)
+        # `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)
+        (v / "complete" / "two").rename(v / "in-progress" / "two")
+        back = model.scan(root)["versions"][0]
+        assert not back.finishable() and back.status() == "current"
+
+    # A released cut stays released — `ready` is about a cut nobody has closed, so
+    # it must never shadow one that shipped.
+    with tempfile.TemporaryDirectory() as tmp:
+        out = _tree(tmp, released="2026-09-12")
+        _task(out / "complete", "one")
+        assert model.scan(Path(tmp))["versions"][0].status() == "released"
+
+
 def test_a_session_that_left_nothing_behind_is_told_nothing():
     # Silence has to keep meaning clean. A line that also appears when there is
     # nothing to say is one nobody can read anything out of.
@@ -7432,6 +7478,199 @@ def test_a_release_with_no_plans_left_says_nothing_about_deleting_any():
             config.apply(config.DEFAULTS)
 
 
+
+
+# ── does this brief still describe the repo? ────────────────────────────────────
+# Measured before any of this was written: 50 of 113 session transcripts in this
+# repo hit a path that was not there, and one path in six named by work about to be
+# picked up pointed at a file that does not exist. The checker is only worth having
+# if it is quiet about the paths that are fine, so most of these are about silence.
+
+def test_a_brief_naming_a_file_that_is_gone_is_reported():
+    from harness.drift import drift
+    with tempfile.TemporaryDirectory() as tmp:
+        repo = _git_repo(tmp, push=False)
+        (repo / "src").mkdir(exist_ok=True)
+        (repo / "src" / "here.ts").write_text("export const a = 1;\n")
+        brief = repo / "work" / "brief.md"
+        brief.parent.mkdir(parents=True, exist_ok=True)
+        brief.write_text("names `src/here.ts` and `src/vanished.ts`\n")
+        _git(repo, "add", "-A"); _git(repo, "commit", "-m", "seed")
+
+        found = drift(repo, ["work/brief.md"])
+        assert [(f[2], f[3]) for f in found] == [("src/vanished.ts", "gone")]
+
+
+def test_a_file_that_merely_moved_is_reported_as_moved_and_says_where():
+    # A link to fix, not a brief to rethink — burying one in the other makes the
+    # rarer and more important finding invisible.
+    from harness.drift import drift
+    with tempfile.TemporaryDirectory() as tmp:
+        repo = _git_repo(tmp, push=False)
+        (repo / "packages" / "deep").mkdir(parents=True, exist_ok=True)
+        (repo / "packages" / "deep" / "moved.ts").write_text("export const a = 1;\n")
+        brief = repo / "work" / "brief.md"
+        brief.parent.mkdir(parents=True, exist_ok=True)
+        brief.write_text("names `src/moved.ts`\n")
+        _git(repo, "add", "-A"); _git(repo, "commit", "-m", "seed")
+
+        found = drift(repo, ["work/brief.md"])
+        assert len(found) == 1
+        assert found[0][3] == "moved"
+        assert found[0][4] == "packages/deep/moved.ts"
+
+
+def test_a_path_written_the_way_a_writer_means_it_is_not_a_finding():
+    # The whole trustworthiness of this. A first pass that resolved against the repo
+    # root alone called 37% of the board's paths missing; a brief in work/ writing
+    # `product/board.md` means its sibling, and that is correct English.
+    from harness.drift import drift
+    with tempfile.TemporaryDirectory() as tmp:
+        repo = _git_repo(tmp, push=False)
+        (repo / "work" / "product").mkdir(parents=True, exist_ok=True)
+        (repo / "work" / "product" / "board.md").write_text("# board\n")
+        (repo / "apps" / "cli" / "harness").mkdir(parents=True, exist_ok=True)
+        (repo / "apps" / "cli" / "harness" / "gate.py").write_text("# gate\n")
+        brief = repo / "work" / "architecture" / "data.md"
+        brief.parent.mkdir(parents=True, exist_ok=True)
+        brief.write_text("see `product/board.md` and `harness/gate.py`\n")
+        _git(repo, "add", "-A"); _git(repo, "commit", "-m", "seed")
+
+        assert drift(repo, ["work/architecture/data.md"]) == []
+
+
+def test_build_output_and_sibling_repos_are_not_this_checkouts_to_judge():
+    # Both found by running this on its own board: `apps/cli/dist/hooks/session-start.js`
+    # is real on any machine that has built and git tracks none of it, and
+    # `../docdoc/...` is a different repo whose contents this cannot see. Silence
+    # here means NOT MY QUESTION, which is not the same as checked-and-good.
+    from harness.drift import drift
+    with tempfile.TemporaryDirectory() as tmp:
+        repo = _git_repo(tmp, push=False)
+        brief = repo / "work" / "brief.md"
+        brief.parent.mkdir(parents=True, exist_ok=True)
+        brief.write_text("`apps/cli/dist/hooks/session-start.js` and "
+                         "`../docdoc/.claude/skills/work/SKILL.md`\n")
+        _git(repo, "add", "-A"); _git(repo, "commit", "-m", "seed")
+
+        assert drift(repo, ["work/brief.md"]) == []
+
+
+def test_prose_that_is_not_addressing_a_file_is_left_alone():
+    # A checker that argues with sentences gets switched off. Only backticked paths
+    # carrying a real extension AND a directory are claims about a file.
+    from harness.drift import drift
+    with tempfile.TemporaryDirectory() as tmp:
+        repo = _git_repo(tmp, push=False)
+        brief = repo / "work" / "brief.md"
+        brief.parent.mkdir(parents=True, exist_ok=True)
+        brief.write_text("the `work/` tree, a `Session`, the word `gone.ts` alone, "
+                         "and the phrase packages/data/src/nope.ts unbackticked\n")
+        _git(repo, "add", "-A"); _git(repo, "commit", "-m", "seed")
+
+        assert drift(repo, ["work/brief.md"]) == []
+
+
+def test_the_report_puts_gone_before_moved_and_refuses_nothing():
+    from harness.drift import describe
+    report = describe([("work/b.md", 3, "src/vanished.ts", "gone", ""),
+                       ("work/b.md", 9, "src/moved.ts", "moved", "pkg/moved.ts")])
+    assert report.index("do not exist anywhere") < report.index("moved")
+    assert "nothing is refused" in report
+
+
+def test_a_brief_that_still_describes_the_repo_says_so_rather_than_saying_nothing():
+    from harness.drift import describe
+    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)]
@@ -7462,4 +7701,4 @@ if __name__ == "__main__":
         fn()
         print(f"ok  {fn.__name__}")
     shutil.rmtree(_TMP, ignore_errors=True)
-    print(f"\n{len(tests)} passed")
+    print(f"\n{len(tests)} passed")

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.102",
+  "version": "0.1.104",
   "description": "Jarvis — local AI coding assistant CLI",
   "private": false,
   "type": "module",
@@ -57,16 +57,16 @@
     "typescript": "^5.7.0",
     "vitest": "^2.1.0",
     "@jarvis/agents": "1.0.0",
-    "@jarvis/board": "0.1.0",
     "@jarvis/anthropic": "1.0.0",
-    "@jarvis/errors": "1.0.0",
-    "@jarvis/logger": "1.0.0",
+    "@jarvis/board": "0.1.0",
     "@jarvis/data": "0.1.0",
+    "@jarvis/errors": "1.0.0",
     "@jarvis/rpc": "1.0.0",
     "@jarvis/types": "1.0.0",
+    "@jarvis/logger": "1.0.0",
     "@jarvis/typescript-config": "1.0.0",
-    "@jarvis/vitest-config": "1.0.0",
-    "@jarvis/ui": "0.1.0"
+    "@jarvis/ui": "0.1.0",
+    "@jarvis/vitest-config": "1.0.0"
   },
   "scripts": {
     "dev": "tsx watch src/bin.ts start --foreground",