@appchy/jarvis 0.1.69 → 0.1.70

package/dist/bin.js

@@ -10115,7 +10115,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 = "f0e0cf3";
+var SHA = "8636478";
 var BUILT = "2026-09-10";
 var BUILD = SHA ?? "source";
 var BUILD_LABEL = `${SHA ? `${VERSION2} (${SHA}${BUILT ? ` ${BUILT}` : ""})` : `${VERSION2} (source)`}${IS_DEV ? " \u2014 development build" : ""}`;

package/harness/harness/architecture.py

@@ -131,7 +131,7 @@ def cmd_init(args) -> int:
 
     write(root / "README.md", _README)
     write(root / "ROADMAP.md", _ROADMAP)
-    for d in ("versions", "backlog"):
+    for d in ("versions", "versions/backlog", "versions/archive"):
         (root / d).mkdir(parents=True, exist_ok=True)
     # Reading order, not alphabetical — and read from config, so a repo that added a
     # tenth domain gets it scaffolded too rather than having to remember to.

package/harness/harness/branches.py

@@ -39,7 +39,7 @@ _PR_CACHE = "work-prs.json"
 #: `versions/<version>/<epic>/<bucket>/<name>/task.md`, or the backlog's shorter
 #: form. The bucket IS the status, so a path answers where an item stands without
 #: reading a byte of it — which is what makes reading a whole branch cheap.
-_ITEM = re.compile(r"^work/(versions|backlog)/.+/task\.md$")
+_ITEM = re.compile(r"^work/versions/.+/task\.md$")
 
 
 def items_at(repo, ref: str) -> list:
@@ -57,12 +57,12 @@ def items_at(repo, ref: str) -> list:
         if not _ITEM.match(path):
             continue
         parts = path.split("/")
-        backlog = parts[1] == "backlog"
+        backlog = len(parts) > 2 and parts[2] == "backlog"
         bucket = "queue" if backlog else (parts[-3] if len(parts) >= 3 else "")
         found.append({
             "name": parts[-2],
             "status": bucket if bucket in BUCKETS else "queue",
-            "epic": parts[2] if backlog else (parts[3] if len(parts) > 3 else ""),
+            "epic": parts[3] if len(parts) > 3 else "",
             "version": "backlog" if backlog else parts[2],
             "path": path,
         })

package/harness/harness/epic.py

@@ -1,7 +1,7 @@
 import shutil
 from datetime import date
 
-from .tree import BUCKETS, EPIC_FM_ORDER, die, find_work_root, rel
+from .tree import backlog_dir, BUCKETS, EPIC_FM_ORDER, die, find_work_root, rel
 from .frontmatter import rewrite_file
 from .model import epic_home, locate_epic, locate_version
 from .scaffold import _check_covers_ref, _check_kebab, _check_unused, _scaffold_epic
@@ -53,7 +53,7 @@ def cmd_epic_new(args) -> int:
         folder = version.folder / name
         home = f"version '{version_name}'"
     else:
-        folder = root / "backlog" / name
+        folder = backlog_dir(root) / name
         home = "backlog"
 
     if folder.exists():
@@ -92,7 +92,7 @@ def _epic_to_backlog(root, name: str) -> int:
             f"Move its unfinished tasks out one at a time instead:\n"
             f"  jarvis work place <task> --backlog --epic <a backlog epic>")
 
-    dest = root / "backlog" / name
+    dest = backlog_dir(root) / name
     if dest.exists():
         die(f"{rel(dest, root)} already exists")
     was = epic_home(root, epic)

package/harness/harness/links.py

@@ -0,0 +1,140 @@
+"""Keep relative links pointing at what they pointed at, across a move.
+
+**A link is repaired by IDENTITY, never by text.** What a link resolved to before
+the move is what it must resolve to after it. Everything else falls out of that:
+a referrer that got deeper needs more `../`, a target that moved needs a new path,
+and both are the same question asked once.
+
+It is also the only way to catch the class nothing else can. After a renumber
+hands an old name to a different folder, a stale pointer still RESOLVES — to a
+real file, the wrong one — and reads as correct. A checker arriving afterwards
+sees a link that works and has no memory that the name used to mean something
+else. Only the thing performing the move holds that map, so the check lives here
+or nowhere. Measured on one repo: seven such pointers survived a renumber, green
+on every link check it had.
+
+Deliberately NOT driven by a doc checker's broken-link output. That repairs only
+what is already broken, which is exactly the set that excludes the case above.
+"""
+
+import os
+import re
+from pathlib import Path
+
+#: Markdown inline links. Reference-style links and bare paths in prose are out of
+#: scope on purpose: rewriting text that is not addressing a file is how a repair
+#: tool starts editing sentences.
+LINK = re.compile(r"\]\(([^)\s]+)\)")
+
+#: Directories no board link ever points into, and which dominate a repo's file
+#: count. Skipping them is what keeps this ~1s rather than ~1min.
+SKIP = {"node_modules", ".git", "build", "dist", ".next", "target", "vendor",
+        ".data", "coverage", ".venv", "__pycache__"}
+
+
+def _docs(repo: Path):
+    for p in repo.rglob("*.md"):
+        if SKIP & set(p.parts):
+            continue
+        # Resolved, so every path in play is in one namespace. On macOS `/var` is a
+        # symlink to `/private/var`, and mixing the two makes a sibling look like a
+        # cousin seven levels up — which is what a relative path would then say.
+        yield p.resolve()
+
+
+def snapshot(repo: Path) -> dict:
+    """Every relative markdown link in the repo, and the file it resolves to NOW.
+
+    Links that already resolve to nothing are recorded as such and never repaired:
+    a link broken before the move is somebody else's bug, and inventing a target
+    for it would be a guess wearing a repair's clothes.
+    """
+    seen = {}
+    for doc in _docs(repo):
+        try:
+            text = doc.read_text(errors="ignore")
+        except OSError:
+            continue
+        found = []
+        for m in LINK.finditer(text):
+            href = m.group(1)
+            if "://" in href or href.startswith(("#", "mailto:", "/")):
+                continue
+            target = (doc.parent / href.split("#")[0]).resolve()
+            found.append((href, target, target.exists()))
+        if found:
+            seen[doc] = found
+    return seen
+
+
+def _after(path: Path, moves: dict) -> Path:
+    """Where `path` is now, given what moved. Children follow their parent."""
+    for old, new in moves.items():
+        if path == old:
+            return new
+        try:
+            return new / path.relative_to(old)
+        except ValueError:
+            continue
+    return path
+
+
+def repair(before: dict, moves: dict) -> tuple:
+    """Rewrite links so they resolve to what they resolved to before.
+
+    Returns (repaired, unresolved) — the count fixed, and a line per link this
+    could not place, which is reported rather than guessed at.
+    """
+    repaired, unresolved = 0, []
+
+    for doc, links in before.items():
+        now = _after(doc, moves)
+        if not now.is_file():
+            unresolved.append(f"{doc} — the file itself is gone")
+            continue
+
+        text = original = now.read_text(errors="ignore")
+        for href, target, existed in links:
+            if not existed:
+                continue
+            want = _after(target, moves)
+            if want == target and now == doc:
+                continue  # neither end moved
+
+            path, _, anchor = href.partition("#")
+            fixed = os.path.relpath(want, now.parent) + (f"#{anchor}" if anchor else "")
+            if fixed == href:
+                continue
+            # Anchored on the link's own syntax, so a path that also appears in
+            # prose is not rewritten by accident.
+            if f"]({href})" not in text:
+                unresolved.append(f"{now} — {href}")
+                continue
+            text = text.replace(f"]({href})", f"]({fixed})")
+            repaired += 1
+
+        if text != original:
+            now.write_text(text)
+
+    return repaired, unresolved
+
+
+def stale_mentions(repo: Path, old_name: str, moved_into: Path) -> list:
+    """Prose still naming a folder that has moved — the part no link check sees.
+
+    A rename does not only break links. `08` meant one cut before a renumber and
+    another after it, and every sentence naming it kept reading as correct. These
+    are reported, never edited: whether a mention is stale or a deliberate record
+    of what was true then is a question only a person can answer.
+    """
+    hits = []
+    for doc in _docs(repo):
+        if moved_into in doc.parents:
+            continue
+        try:
+            for n, line in enumerate(doc.read_text(errors="ignore").splitlines(), 1):
+                if old_name in line and f"]({old_name}" not in line:
+                    hits.append(f"{doc.relative_to(repo)}:{n}")
+        except OSError:
+            continue
+    return hits

package/harness/harness/model.py

@@ -3,7 +3,7 @@ import re
 from datetime import date
 from pathlib import Path
 
-from .tree import BUCKETS, DONE_TIER, PRIORITIES, RESERVED_MD
+from .tree import backlog_dir, BUCKETS, DONE_TIER, PRIORITIES, RESERVED_MD
 from .frontmatter import as_list, parse_frontmatter, read_item, rewrite_file, title_of
 
 
@@ -279,7 +279,7 @@ def scan(root: Path) -> dict:
     versions.sort(key=lambda v: (v.order, v.name))
 
     backlog, backlog_epics = [], []
-    bdir = root / "backlog"
+    bdir = backlog_dir(root)
     if bdir.is_dir():
         # A folder is an EPIC if it holds epic.md, a TASK if it holds task.md.
         # The marker file is the discriminator, so there is no registry to keep

package/harness/harness/scaffold.py

@@ -10,9 +10,20 @@ def _check_kebab(kind: str, name: str):
     if not re.match(r"^[a-z0-9]+(-[a-z0-9]+)*$", name):
         die(f"{kind} name must be kebab-case (got '{name}')")
 def _check_version_name(name: str):
-    """Version names allow dots and dashes (semver-style): v0.3, v1.0, 0.2.1-rc1."""
-    if not re.match(r"^[a-z0-9]+([._-][a-z0-9]+)*$", name):
-        die(f"version name must be kebab-case or dotted (got '{name}')")
+    """A version folder is `NN-<name>`, and the number is part of the NAME.
+
+    `order:` in the frontmatter is not enough and never was: it is invisible in a
+    directory listing, in a path, and in every link a brief writes. So a cut created
+    with `--order 0` and a bare name landed unprefixed beside `01-…`, and once the
+    tool cannot produce the shape it wants, people scaffold folders by hand — which
+    is how one repo ended up with five cuts all reading as current and an `order:`
+    that had stopped meaning anything.
+    """
+    if not re.match(r"^\d{2,}-[a-z0-9]+(-[a-z0-9]+)*$", name):
+        die(f"version name must be NN-<name> — two or more digits, a dash, then "
+            f"kebab-case (got '{name}'). The number orders the cut and is part of "
+            f"the folder name, because that is where it is visible: in a listing, "
+            f"in a path, and in every link that points at it.")
 def _check_priority(p: str):
     if p not in PRIORITIES:
         die(f"priority must be one of {', '.join(PRIORITIES)}")

package/harness/harness/task.py

@@ -7,6 +7,7 @@ from . import peers, tree
 # `TASK_TAGS_OK` is deliberately NOT imported by name: `config.apply` binds it on
 # the `tree` module, and a `from … import` captures the value at import time, so
 # the name here would still hold the pre-config default. Read through the module.
+from . import links
 from .tree import BLOCKED, BUCKETS, die, find_work_root, rel
 from .frontmatter import as_list, parse_frontmatter, read_item, rewrite_file, split_frontmatter
 from .model import current_session_id, locate, locate_epic, locate_version, record_session, scan
@@ -185,7 +186,21 @@ def cmd_place(args) -> int:
     if dest.exists():
         die(f"{rel(dest, root)} already exists")
     dest.parent.mkdir(parents=True, exist_ok=True)
+
+    # What every link in the repo pointed at, read BEFORE the move — because after
+    # it there is nothing left to compare against, and a link that still resolves
+    # to the wrong file is indistinguishable from one that is right.
+    repo = root.parent
+    before = links.snapshot(repo)
+
     shutil.move(str(task.folder), str(dest))
+
+    repaired, unresolved = links.repair(before, {task.folder.resolve(): dest.resolve()})
+    if repaired:
+        print(f"  repaired {repaired} link(s) that pointed at it")
+    for line in unresolved:
+        print(f"  COULD NOT PLACE  {line}")
+
     md = dest / "task.md"
     rewrite_file(
         md,

package/harness/harness/tree.py

@@ -203,10 +203,23 @@ def locate_work_root() -> tuple:
         tried.append(str(cand))
     for d in (cur, *cur.parents):
         cand = d / "work"
-        if cand.is_dir() and any((cand / sub).is_dir()
-                                 for sub in ("versions", "backlog")):
+        if cand.is_dir() and (cand / "versions").is_dir():
             return cand, tried, cur
     return None, tried, cur
+
+
+def backlog_dir(root: Path) -> Path:
+    """Where work waits before it is cut. Inside `versions/` because it is one of
+    the states a cut's work is in, not a place beside the cuts — the tree now reads
+    versions/{backlog,archive,complete,NN-name}."""
+    return root / "versions" / "backlog"
+
+
+def archive_dir(root: Path) -> Path:
+    """Where a finished cut goes when releasing it would be a lie. A cut whose work
+    all moved elsewhere has nothing left to deliver and no outcome it met; without
+    this it sits in the live list looking open forever."""
+    return root / "versions" / "archive"
 def assets_dir() -> Path:
     return PAYLOAD_DIR / "assets"
 def rel(p: Path, root: Path) -> str:

package/harness/test_work.py

@@ -401,7 +401,7 @@ def _tree(tmp: str, name: str = "26-cut", outcome: str = "a user can do x",
     root = Path(tmp)
     v = root / "versions" / name
     v.mkdir(parents=True)
-    (root / "backlog").mkdir(exist_ok=True)
+    (root / "versions" / "backlog").mkdir(exist_ok=True)
     # Every mutating command ends in `_sync`, which regenerates this file and
     # dies without its markers — so a fixture that omits it fails the command
     # for the wrong reason.
@@ -562,7 +562,7 @@ def test_a_backlog_epic_holds_its_tasks_without_buckets():
     with tempfile.TemporaryDirectory() as tmp:
         root = Path(tmp)
         _tree(tmp)
-        e = _epic(root / "backlog", "richer-exercise-vocabulary")
+        e = _epic(root / "versions" / "backlog", "richer-exercise-vocabulary")
         _task(e, "code-block")
         s = model.scan(root)
         assert [x.name for x in s["backlog_epics"]] == ["richer-exercise-vocabulary"]
@@ -576,8 +576,8 @@ def test_a_loose_backlog_task_still_resolves_alongside_epics():
     with tempfile.TemporaryDirectory() as tmp:
         root = Path(tmp)
         _tree(tmp)
-        _epic(root / "backlog", "an-epic")
-        _task(root / "backlog", "a-loose-one")
+        _epic(root / "versions" / "backlog", "an-epic")
+        _task(root / "versions" / "backlog", "a-loose-one")
         s = model.scan(root)
         assert [t.name for t in s["backlog"]] == ["a-loose-one"]
         assert s["backlog"][0].epic is None
@@ -618,12 +618,12 @@ def test_work_comes_back_out_of_a_cut_it_does_not_belong_in():
         e = _epic(v, "an-epic")
         (e / "queue").mkdir()
         _task(e / "queue", "not-this-cut")
-        _epic(root / "backlog", "later-on")
+        _epic(root / "versions" / "backlog", "later-on")
         os.environ["WORK_DIR"] = tmp
         try:
             task.cmd_place({"name": "not-this-cut", "backlog": "true",
                              "epic": "later-on"})
-            assert (root / "backlog" / "later-on" / "not-this-cut").is_dir()
+            assert (root / "versions" / "backlog" / "later-on" / "not-this-cut").is_dir()
             # A backlog task has no bucket — status only exists inside a cut.
             assert not (e / "queue" / "not-this-cut").exists()
         finally:
@@ -641,7 +641,7 @@ def test_what_a_release_delivered_cannot_be_edited_afterwards():
         e = _epic(v, "an-epic")
         (e / "complete").mkdir()
         _task(e / "complete", "already-shipped")
-        _epic(root / "backlog", "later-on")
+        _epic(root / "versions" / "backlog", "later-on")
         os.environ["WORK_DIR"] = tmp
         try:
             for move in ({"backlog": "true", "epic": "later-on"},
@@ -664,13 +664,13 @@ def test_an_epic_carried_into_a_later_cut_says_what_it_continues():
         import os
         _tree(tmp)
         root = Path(tmp)
-        _epic(root / "backlog", "the-original")
+        _epic(root / "versions" / "backlog", "the-original")
         os.environ["WORK_DIR"] = tmp
         try:
             epic.cmd_epic_new({"name": "the-rest-of-it",
                                "continues": "the-original"})
             fm = frontmatter.parse_frontmatter(
-                (root / "backlog" / "the-rest-of-it" / "epic.md").read_text())
+                (root / "versions" / "backlog" / "the-rest-of-it" / "epic.md").read_text())
             assert fm.get("continues") == "the-original"
             assert model.scan(root)["backlog_epics"], "and it is on the board"
             # A link to nothing is worse than no link: it reads as provenance and
@@ -831,7 +831,7 @@ def test_a_backlog_epic_is_not_asked_what_it_covers():
     with tempfile.TemporaryDirectory() as tmp:
         root = Path(tmp)
         _tree(tmp)
-        _epic(root / "backlog", "you-reach-it-from-your-phone", covers="[]")
+        _epic(root / "versions" / "backlog", "you-reach-it-from-your-phone", covers="[]")
         assert not any("you-reach-it-from-your-phone: no covers:"
                        in w for w in _warns(root))
 
@@ -842,7 +842,7 @@ def test_a_backlog_epic_is_not_held_to_the_task_floor():
     with tempfile.TemporaryDirectory() as tmp:
         root = Path(tmp)
         _tree(tmp)
-        _epic(root / "backlog", "it-sings-what-you-write", covers="[]")
+        _epic(root / "versions" / "backlog", "it-sings-what-you-write", covers="[]")
         assert not any("it-sings-what-you-write: 0 task(s)"
                        in w for w in _warns(root))
 
@@ -1778,6 +1778,42 @@ def test_doctor_passes_a_degraded_but_legal_install_and_fails_a_real_break():
         assert f"{tree.cli()} init" in out.getvalue()
 
 
+def test_links_are_repaired_by_what_they_pointed_at_not_by_what_they_say():
+    from harness import links
+    with tempfile.TemporaryDirectory() as tmp:
+        repo = Path(tmp)
+        (repo / "a" / "deep").mkdir(parents=True)
+        (repo / "b").mkdir()
+        (repo / "target.md").write_text("# target\n")
+        (repo / "b" / "other.md").write_text("# other\n")
+
+        # Three links from one file: one at a thing that will move, one at a thing
+        # that will not, and one that is already dead.
+        doc = repo / "a" / "note.md"
+        doc.write_text(
+            "See [it](../target.md), and [other](../b/other.md), "
+            "and [gone](../nowhere.md).\n")
+
+        before = links.snapshot(repo)
+        moved_to = repo / "a" / "deep" / "target.md"
+        (repo / "target.md").rename(moved_to)
+        repaired, unresolved = links.repair(
+            before, {(repo / "target.md").resolve(): moved_to.resolve()})
+
+        text = doc.read_text()
+        assert "](deep/target.md)" in text, f"target moved, link did not follow: {text}"
+        assert "](../b/other.md)" in text, "a link at something that did not move was touched"
+        assert "](../nowhere.md)" in text, "a link dead before the move was invented a target"
+        assert repaired == 1 and unresolved == []
+
+        # The class nothing else catches: the old name now belongs to a DIFFERENT
+        # real file, so the stale pointer still resolves and reads as correct.
+        (repo / "target.md").write_text("# an impostor now wearing the old name\n")
+        assert (repo / "a" / "../target.md").exists()
+        assert "](deep/target.md)" in doc.read_text(), \
+            "identity, not resolvability, is what the repair preserves"
+
+
 def test_place_carries_a_tasks_bucket_into_the_new_cut():
     # The bucket IS the status, so landing everything in `queue/` does not move a
     # task, it un-starts it — silently, and for blocked work the obvious repair is
@@ -1945,7 +1981,9 @@ def test_init_scaffolds_the_whole_tree_and_is_idempotent_and_non_destructive():
         assert (root / "README.md").is_file() and (root / "ROADMAP.md").is_file()
         assert tree.BACKLOG_START in (root / "README.md").read_text(), \
             "`_regen_readme` dies without the markers, so `init` must write them"
-        for d in ("versions", "backlog"):
+        # backlog and archive are STATES a cut's work is in, so they live inside
+        # versions/ beside the cuts rather than as siblings of it.
+        for d in ("versions", "versions/backlog", "versions/archive"):
             assert (root / d).is_dir()
         assert len(registry.scan_domains(root)) == 9
 
@@ -3497,8 +3535,8 @@ def test_a_gitignored_board_is_the_failure_wearing_a_success_s_clothes():
             _git(repo, "rm", "-r", "-q", "--cached", "work")
             _git(repo, "add", ".gitignore")
             _git(repo, "commit", "-qm", "ignore the board")
-            (repo / "work" / "backlog").mkdir(parents=True, exist_ok=True)
-            (repo / "work" / "backlog" / "an-item.md").write_text("a board write\n")
+            (repo / "work" / "versions" / "backlog").mkdir(parents=True, exist_ok=True)
+            (repo / "work" / "versions" / "backlog" / "an-item.md").write_text("a board write\n")
 
             assert git.ignored(repo) == ["work"], \
                 "an ignored board must be nameable, or nothing can report it"
@@ -3525,8 +3563,8 @@ def test_sync_recovers_a_branch_that_never_had_an_upstream():
             _git(repo, "checkout", "-qb", "never-pushed")
             assert _git(repo, "rev-parse", "--abbrev-ref", "@{upstream}").returncode != 0, \
                 "the whole point of this test is a branch with no upstream"
-            (repo / "work" / "backlog").mkdir(parents=True, exist_ok=True)
-            (repo / "work" / "backlog" / "born-offline.md").write_text("offline\n")
+            (repo / "work" / "versions" / "backlog").mkdir(parents=True, exist_ok=True)
+            (repo / "work" / "versions" / "backlog" / "born-offline.md").write_text("offline\n")
             committed, pushed, _ = git.land(repo, "born-offline", [])
             assert committed and not pushed
             git.GIT = {**git.GIT, "push": True}
@@ -3553,9 +3591,9 @@ def test_a_board_write_that_landed_never_reports_as_one_that_failed():
     with tempfile.TemporaryDirectory() as tmp:
         try:
             repo = _git_repo(tmp, push=False)
-            (repo / "work" / "backlog").mkdir(parents=True, exist_ok=True)
-            (repo / "work" / "backlog" / "first.md").write_text("first\n")
-            (repo / "work" / "backlog" / "second.md").write_text("second\n")
+            (repo / "work" / "versions" / "backlog").mkdir(parents=True, exist_ok=True)
+            (repo / "work" / "versions" / "backlog" / "first.md").write_text("first\n")
+            (repo / "work" / "versions" / "backlog" / "second.md").write_text("second\n")
             rows = [{"event": "created", "name": "first"}]
             committed, _, note = git.land(repo, "first", rows)
             assert committed and note == ""

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appchy/jarvis",
-  "version": "0.1.69",
+  "version": "0.1.70",
   "description": "Jarvis — local AI coding assistant CLI",
   "private": false,
   "type": "module",
@@ -61,12 +61,12 @@
     "@jarvis/data": "0.1.0",
     "@jarvis/errors": "1.0.0",
     "@jarvis/logger": "1.0.0",
-    "@jarvis/board": "0.1.0",
     "@jarvis/rpc": "1.0.0",
-    "@jarvis/types": "1.0.0",
+    "@jarvis/board": "0.1.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",