@appchy/jarvis 0.1.102 → 0.1.103

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 = "c1072c2";
 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/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/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/test_work.py

@@ -7240,6 +7240,44 @@ 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)
+        # `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
+
+        # 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 +7470,112 @@ 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([])
+
+
 if __name__ == "__main__":
     tests = [v for k, v in sorted(globals().items())
              if k.startswith("test_") and callable(v)]
@@ -7462,4 +7606,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appchy/jarvis",
-  "version": "0.1.102",
+  "version": "0.1.103",
   "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/board": "0.1.0",
     "@jarvis/logger": "1.0.0",
+    "@jarvis/errors": "1.0.0",
     "@jarvis/data": "0.1.0",
     "@jarvis/rpc": "1.0.0",
-    "@jarvis/types": "1.0.0",
     "@jarvis/typescript-config": "1.0.0",
-    "@jarvis/vitest-config": "1.0.0",
-    "@jarvis/ui": "0.1.0"
+    "@jarvis/types": "1.0.0",
+    "@jarvis/ui": "0.1.0",
+    "@jarvis/vitest-config": "1.0.0"
   },
   "scripts": {
     "dev": "tsx watch src/bin.ts start --foreground",