@appchy/jarvis 0.1.71 → 0.1.73

package/dist/bin.js

@@ -10109,7 +10109,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 = "bf811fb";
+var SHA = "9e5b550";
 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/autonomy.py

@@ -30,7 +30,7 @@ from .tree import (BLOCKED, BUCKETS, DEFAULT_AUTONOMY_CEILING, TIER3_OWNERS,
 from .frontmatter import as_list, parse_frontmatter, rewrite_file
 from .model import locate, record_session, scan
 from .generate import _sync
-from . import events
+from . import events, links
 
 #: `autonomy.ceiling` from config — the highest tier an unattended run acts on
 #: alone. Set by `config.apply`, so a repo's answer is bound before any command
@@ -160,7 +160,9 @@ def cmd_ask(args) -> int:
         if dest.exists():
             die(f"{rel(dest, root)} already exists")
         dest.parent.mkdir(parents=True, exist_ok=True)
-        shutil.move(str(task.folder), str(dest))
+        with links.repairing(root.parent) as moved:
+            moved[task.folder.resolve()] = dest.resolve()
+            shutil.move(str(task.folder), str(dest))
 
     md = dest / "task.md"
 
@@ -241,7 +243,9 @@ def cmd_answer(args) -> int:
         if dest.exists():
             die(f"{rel(dest, root)} already exists")
         dest.parent.mkdir(parents=True, exist_ok=True)
-        shutil.move(str(task.folder), str(dest))
+        with links.repairing(root.parent, indent="        ") as moved:
+            moved[task.folder.resolve()] = dest.resolve()
+            shutil.move(str(task.folder), str(dest))
         events.append(root, "moved", name, **{"from": BLOCKED, "to": to})
         print(f"answered '{name}' -> {to}/")
     else:

package/harness/harness/epic.py

@@ -6,7 +6,7 @@ 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
 from .generate import _sync
-from . import events
+from . import events, links
 
 
 def cmd_epic_new(args) -> int:
@@ -98,11 +98,21 @@ def _epic_to_backlog(root, name: str) -> int:
     was = epic_home(root, epic)
     moved = epic.all_tasks()
     dest.parent.mkdir(parents=True, exist_ok=True)
-    shutil.move(str(epic.folder), str(dest))
-    for t in moved:
-        bucketed = dest / t.status / t.name
-        if bucketed.exists():
-            shutil.move(str(bucketed), str(dest / t.name))
+    # One snapshot for the epic AND every task lifted out of its bucket beneath it.
+    # Per-move would rescan the whole repo once per task, and a backlog epic can
+    # carry thirty.
+    with links.repairing(root.parent) as relocated:
+        # Each task keyed on where it was BEFORE the epic moved, because that is
+        # the path every link naming it used — and it lands loose under the new
+        # epic rather than at the bucketed path the epic move alone would imply.
+        for t in moved:
+            relocated[t.folder.resolve()] = (dest / t.name).resolve()
+        relocated[epic.folder.resolve()] = dest.resolve()
+        shutil.move(str(epic.folder), str(dest))
+        for t in moved:
+            bucketed = dest / t.status / t.name
+            if bucketed.exists():
+                shutil.move(str(bucketed), str(dest / t.name))
     for bucket in BUCKETS:
         empty = dest / bucket
         if empty.is_dir() and not any(empty.iterdir()):
@@ -166,14 +176,21 @@ def cmd_epic_move(args) -> int:
         die(f"{rel(dest, root)} already exists")
     was = epic_home(root, epic)
     moved = epic.all_tasks()
-    shutil.move(str(epic.folder), str(dest))
-
-    # A backlog epic's tasks were loose under it; give them the queue bucket.
-    if epic.in_backlog:
-        queue = dest / "queue"
-        queue.mkdir(exist_ok=True)
-        for t in moved:
-            shutil.move(str(dest / t.name), str(queue / t.name))
+    with links.repairing(root.parent) as relocated:
+        # A backlog epic's tasks were loose under it and gain the queue bucket, so
+        # they end one level deeper than the epic move alone would put them. Keyed
+        # on where each was before any of this, which is what links name.
+        if epic.in_backlog:
+            for t in moved:
+                relocated[t.folder.resolve()] = (dest / "queue" / t.name).resolve()
+        relocated[epic.folder.resolve()] = dest.resolve()
+        shutil.move(str(epic.folder), str(dest))
+
+        if epic.in_backlog:
+            queue = dest / "queue"
+            queue.mkdir(exist_ok=True)
+            for t in moved:
+                shutil.move(str(dest / t.name), str(queue / t.name))
 
     md = dest / "epic.md"
     rewrite_file(

package/harness/harness/generate.py

@@ -1,7 +1,7 @@
 import os
 import re
 
-from . import ids
+from . import ids, links
 import shutil
 from pathlib import Path
 
@@ -235,10 +235,12 @@ def settle_epic_tier(root: Path, include_released: bool = False) -> list:
 
     Released versions are skipped: they are a record, not a board, and `release`
     flattens the tier before stamping so an archived cut keeps a flat epic list."""
-    moved = []
-    for v in scan(root)["versions"]:
-        if v.released and not include_released:
-            continue
+    # Decided across every version BEFORE anything moves. This runs on each board
+    # mutation and settles nothing on almost all of them, so the link snapshot has
+    # to be paid for only when there is actually a move to repair.
+    versions = [v for v in scan(root)["versions"] if include_released or not v.released]
+    pending = []
+    for v in versions:
         for e in v.epics:
             done = e.is_done()
             if done == e.done_tier:
@@ -246,9 +248,18 @@ def settle_epic_tier(root: Path, include_released: bool = False) -> list:
             dest = (v.folder / DONE_TIER / e.name) if done else (v.folder / e.name)
             if dest.exists():
                 continue
-            dest.parent.mkdir(parents=True, exist_ok=True)
-            shutil.move(str(e.folder), str(dest))
-            moved.append((e.name, "complete" if done else "in flight"))
+            pending.append((e, dest, done))
+
+    moved = []
+    if pending:
+        with links.repairing(root.parent) as relocated:
+            for e, dest, done in pending:
+                dest.parent.mkdir(parents=True, exist_ok=True)
+                relocated[e.folder.resolve()] = dest.resolve()
+                shutil.move(str(e.folder), str(dest))
+                moved.append((e.name, "complete" if done else "in flight"))
+
+    for v in versions:
         # Leave no empty `complete/` behind — an empty tier reads as a claim that
         # something finished here.
         tier = v.folder / DONE_TIER

package/harness/harness/links.py

@@ -19,6 +19,7 @@ what is already broken, which is exactly the set that excludes the case above.
 
 import os
 import re
+from contextlib import contextmanager
 from pathlib import Path
 
 #: Markdown inline links. Reference-style links and bare paths in prose are out of
@@ -68,8 +69,16 @@ def snapshot(repo: Path) -> dict:
 
 
 def _after(path: Path, moves: dict) -> Path:
-    """Where `path` is now, given what moved. Children follow their parent."""
-    for old, new in moves.items():
+    """Where `path` is now, given what moved. Children follow their parent.
+
+    Deepest match wins, so the order a caller recorded its moves in cannot change
+    the answer. An epic moving with its tasks lifted out of their buckets records
+    both the epic and each task, and each task's own entry has to beat its epic's
+    — insertion order happened to give that and would have stopped the first time
+    somebody recorded the moves as they made them.
+    """
+    for old in sorted(moves, key=lambda p: len(p.parts), reverse=True):
+        new = moves[old]
         if path == old:
             return new
         try:
@@ -141,3 +150,44 @@ def stale_mentions(repo: Path, old_name: str, moved_into: Path) -> list:
         except OSError:
             continue
     return hits
+
+
+@contextmanager
+def repairing(repo: Path, indent: str = "  "):
+    """Snapshot once, collect `old -> new` as the body moves things, repair on exit.
+
+    The snapshot/move/repair dance was pasted into each mover that had grown one,
+    which is exactly how the other six went without: three of nine folder moves
+    repaired their links and the rest broke them silently, in the same way, for
+    the same reason. A helper nobody has to remember is the only version of this
+    that stays true — and it makes `shutil.move` inside the harness the smell
+    rather than the default.
+
+    ONE snapshot per block, not per move. A mover that moves a task at a time
+    would otherwise rescan the whole repo once per task, and two of them do
+    exactly that: ~1s over 351 markdown files here, and 1,186 on a sibling.
+
+    Enter the block only when something is actually going to move — the snapshot
+    is taken on the way in, so a mover that decides against moving pays for a
+    scan it did not need. Collect the pairs first, then open the block.
+
+    **Key every entry on where the thing was BEFORE the block, not on where the
+    previous line just put it.** Links pointed at the original path and that is
+    the only path there is anything to look up. A two-stage move — an epic
+    relocated, then a task lifted out of a bucket underneath it — records the
+    task's ORIGINAL folder against its final home, not the half-way one.
+
+    The repair runs even when the body raises, because `die()` is an exception
+    and whatever it left behind has already moved.
+    """
+    before = snapshot(repo)
+    moved: dict = {}
+    try:
+        yield moved
+    finally:
+        if moved:
+            repaired, unresolved = repair(before, moved)
+            if repaired:
+                print(f"{indent}repaired {repaired} link(s) that pointed at what moved")
+            for line in unresolved:
+                print(f"{indent}COULD NOT PLACE  {line}")

package/harness/harness/migrate.py

@@ -0,0 +1,129 @@
+"""Bring a repo's `work/` tree up to the layout this harness expects.
+
+Every repo on this harness has its own copy of the tree, and a layout change
+therefore has to happen once per repo, by hand, on somebody's afternoon. The last
+one was carried out by a script written into a session's scratchpad — which is to
+say it was carried out by a script that no longer exists, and the fifth repo to
+need it would have had it written a second time. That is the shape this command
+replaces: the migration ships with the harness that requires it.
+
+**Idempotent, and safe to run on a repo that is already current** — it reports
+what it found and changes nothing. That matters more than it sounds: nobody
+remembers which repos have been through it, and a command you have to check
+before running is a command somebody runs twice anyway.
+
+**It repairs links, which is the whole reason it is here rather than in a shell
+one-liner.** Moving `backlog/` moves every task under it, and the pointers at
+those tasks live all over a repo — in other versions, under `complete/`, and
+outside `work/` entirely. One repo's migration repaired ~450 of them across
+`work/`, `projects/`, `reviews/`, `apps/` and `research/`. A migration scoped to
+`work/` passes clean and silently rots the rest.
+"""
+
+import shutil
+import subprocess
+from pathlib import Path
+
+from .tree import archive_dir, backlog_dir, die, find_work_root, rel
+from . import links
+
+
+def _uncommitted(repo: Path, work: Path) -> list:
+    """Paths under `work/` with uncommitted changes.
+
+    A layout migration moves folders another session may have open, and the repo
+    that most needs this command is the one with five sessions live in it. Git is
+    the only thing that knows, and a repo that is not a git checkout answers with
+    an empty list rather than blocking the migration.
+    """
+    try:
+        out = subprocess.run(["git", "status", "--porcelain"], cwd=repo,
+                             capture_output=True, text=True, check=True).stdout
+    except Exception:
+        return []
+    dirty = []
+    for line in out.splitlines():
+        if len(line) <= 3:
+            continue
+        p = (repo / line[3:].strip().strip('"')).resolve()
+        if work.resolve() == p or work.resolve() in p.parents:
+            dirty.append(str(p.relative_to(repo)))
+    return sorted(dirty)
+
+
+def cmd_migrate(args) -> int:
+    """`work/backlog/` moves inside `versions/`, and `versions/archive/` is made.
+
+    Both halves of one layout: backlog and archive are states a cut's work is in,
+    so they belong beside the cuts rather than in a directory of their own.
+    """
+    root = find_work_root()
+    repo = root.parent
+    dry = bool(args.get("dry_run") or args.get("dry-run"))
+
+    old = root / "backlog"
+    new = backlog_dir(root)
+    archive = archive_dir(root)
+
+    # The one hard refusal. Both present means somebody has already started this,
+    # or a repo has grown a second backlog — and merging two trees is a judgement
+    # about which copy of a task is real, which is not a call a migration makes.
+    if old.is_dir() and new.is_dir():
+        die(f"both {rel(old, root)} and {rel(new, root)} exist — this repo has two "
+            f"backlogs and only a person can say which task is the real one. "
+            f"Merge them by hand, then run this again.")
+
+    todo = []
+    if old.is_dir():
+        todo.append("the backlog moves inside versions/")
+    if not archive.is_dir():
+        todo.append("versions/archive/ is created")
+    if not todo:
+        print(f"{rel(root, root)} is already on the current layout — nothing to do")
+        return 0
+
+    if dry:
+        print(f"would migrate {rel(root, root)}:")
+        for line in todo:
+            print(f"  {line}")
+        if old.is_dir():
+            print(f"  {sum(1 for _ in old.rglob('task.md'))} task(s) would move")
+        return 0
+
+    dirty = _uncommitted(repo, root)
+    if dirty and not args.get("force"):
+        die(f"{len(dirty)} uncommitted change(s) under {rel(root, root)} — a layout "
+            f"migration moves folders somebody may have open, and git is the only "
+            f"way back. Commit or stash first, then run this again (--force "
+            f"overrides).\n       " + "\n       ".join(dirty[:10]))
+
+    if old.is_dir():
+        moved_tasks = sum(1 for _ in old.rglob("task.md"))
+        new.parent.mkdir(parents=True, exist_ok=True)
+        with links.repairing(repo) as moved:
+            moved[old.resolve()] = new.resolve()
+            shutil.move(str(old), str(new))
+        print(f"moved {rel(old, root)} -> {rel(new, root)}  ({moved_tasks} task(s))")
+
+        # Reported, never rewritten. Whether a sentence naming the old path is
+        # stale or a deliberate record of what was true then is a question only a
+        # person can answer — and this is the half no link check ever sees.
+        stale = links.stale_mentions(repo, "work/backlog", new)
+        if stale:
+            print(f"  {len(stale)} line(s) still name `work/backlog` in prose — "
+                  f"read them, they are not all wrong:")
+            for hit in stale[:10]:
+                print(f"    {hit}")
+            if len(stale) > 10:
+                print(f"    … and {len(stale) - 10} more")
+
+    if not archive.is_dir():
+        archive.mkdir(parents=True, exist_ok=True)
+        # An empty directory does not survive git, and the point of making it now
+        # is that `archive` has somewhere to put a cut without inventing it later.
+        (archive / ".gitkeep").write_text("")
+        print(f"created {rel(archive, root)}")
+
+    print("done — commit this, then every machine working this repo needs a CLI "
+          "new enough to read it")
+    return 0

package/harness/harness/shift.py

@@ -27,7 +27,7 @@ from .tree import BLOCKED, BUCKETS, die, find_work_root, rel
 from .frontmatter import rewrite_file
 from .model import locate, record_session, scan
 from .generate import _sync
-from . import autonomy, events, peers
+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
 # `config.apply` setting it afterwards would leave this file quietly running on
@@ -178,7 +178,9 @@ def cmd_next(args) -> int:
     if dest.exists():
         die(f"{rel(dest, root)} already exists")
     dest.parent.mkdir(parents=True, exist_ok=True)
-    shutil.move(str(task.folder), str(dest))
+    with links.repairing(root.parent) as moved:
+        moved[task.folder.resolve()] = dest.resolve()
+        shutil.move(str(task.folder), str(dest))
     md = dest / "task.md"
     rewrite_file(
         md,

package/harness/harness/task.py

@@ -190,16 +190,9 @@ def cmd_place(args) -> int:
     # 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}")
+    with links.repairing(root.parent) as moved:
+        moved[task.folder.resolve()] = dest.resolve()
+        shutil.move(str(task.folder), str(dest))
 
     md = dest / "task.md"
     rewrite_file(
@@ -264,7 +257,9 @@ def _to_backlog(root, name: str, args) -> int:
     if dest.exists():
         die(f"{rel(dest, root)} already exists")
     dest.parent.mkdir(parents=True, exist_ok=True)
-    shutil.move(str(task.folder), str(dest))
+    with links.repairing(root.parent) as moved:
+        moved[task.folder.resolve()] = dest.resolve()
+        shutil.move(str(task.folder), str(dest))
     md = dest / "task.md"
     rewrite_file(
         md,
@@ -334,7 +329,14 @@ def cmd_move(args) -> int:
     if dest.exists():
         die(f"{rel(dest, root)} already exists")
     dest.parent.mkdir(parents=True, exist_ok=True)
-    shutil.move(str(task.folder), str(dest))
+
+    # The bucket is part of every path that names this task, so a status change
+    # moves the folder and breaks whatever pointed at it — and `move` fires on every
+    # pickup and every completion, far more often than `place`. One audited board
+    # had 16 of its 37 broken links from a bucket change alone.
+    with links.repairing(root.parent) as moved:
+        moved[task.folder.resolve()] = dest.resolve()
+        shutil.move(str(task.folder), str(dest))
 
     def mutate(d):
         d["updated"] = date.today().isoformat()

package/harness/harness/version.py

@@ -105,7 +105,7 @@ def cmd_version_new(args) -> int:
         print(f"        {rel(folder / 'architecture.md', root)}  (the cross-task technical brief)")
     _sync(root)
     return 0
-def _flatten_done_tier(version) -> None:
+def _flatten_done_tier(version, root) -> None:
     """Lift every epic out of `<v>/complete/` back to the version's top level.
 
     Called at release only. The tier exists to keep a moving board readable; once a
@@ -123,13 +123,22 @@ def _flatten_done_tier(version) -> None:
     tier = version.folder / DONE_TIER
     if not tier.is_dir():
         return
+    # Decided in full before anything moves, so the link snapshot is taken once and
+    # only when there is something to repair — and so a name collision refuses with
+    # the tier still intact rather than half-lifted.
+    pairs = []
     for epic in sorted(tier.iterdir()):
         if not _is_epic_dir(epic):
             continue
         dest = version.folder / epic.name
         if dest.exists():
             die(f"cannot flatten '{epic.name}' — {rel(dest, version.folder)} already exists")
-        shutil.move(str(epic), str(dest))
+        pairs.append((epic, dest))
+    if pairs:
+        with links.repairing(root.parent, indent="        ") as moved:
+            for epic, dest in pairs:
+                moved[epic.resolve()] = dest.resolve()
+                shutil.move(str(epic), str(dest))
     if not any(tier.iterdir()):
         tier.rmdir()
 
@@ -157,7 +166,7 @@ def cmd_release(args) -> int:
     # definition, so leaving them parked would make `<v>/complete/` the whole cut —
     # a board affordance turned into the archived record's shape, for no reader. The
     # record keeps the flat epic list it has always had.
-    _flatten_done_tier(version)
+    _flatten_done_tier(version, root)
     # THE FLATTEN MOVED FOLDERS, so every path hanging off `version` is now stale.
     # Re-locate before anything else touches the tree.
     #
@@ -304,14 +313,9 @@ def cmd_archive(args) -> int:
     if dest.exists():
         die(f"{rel(dest, root)} already exists")
     dest.parent.mkdir(parents=True, exist_ok=True)
-    before = links.snapshot(root.parent)
-    moved_from = version.folder.resolve()
-    shutil.move(str(_contained(version.folder, root)), str(dest))
-    repaired, unresolved = links.repair(before, {moved_from: dest.resolve()})
-    if repaired:
-        print(f"        repaired {repaired} link(s) that pointed into it")
-    for line in unresolved:
-        print(f"        COULD NOT PLACE  {line}")
+    with links.repairing(root.parent, indent="        ") as moved:
+        moved[version.folder.resolve()] = dest.resolve()
+        shutil.move(str(_contained(version.folder, root)), str(dest))
 
     where = f" — full docs in git history @ {sha}" if sha else ""
     events.append(root, "archived", name, stripped=removed)

package/harness/test_work.py

@@ -6,6 +6,7 @@ three-tier scan, the version gate, and the four shape lints."""
 import importlib.util
 import json
 import os
+import shutil
 import time
 import re
 import sys
@@ -13,6 +14,14 @@ import tempfile
 from datetime import date, datetime, timedelta, timezone
 from pathlib import Path
 
+# Every fixture's work root is a `TemporaryDirectory`, and link repair scans the
+# repo AROUND that root — its parent. Left on the system default that parent is the
+# shared temp directory, which on a developer's machine held 209,000 entries and was
+# walked once per move. Rooting the suite's own temp dir here makes that parent a
+# directory containing only what this run put there.
+_TMP = tempfile.mkdtemp(prefix="jarvis-board-suite-")
+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
 from harness import (align, architecture, autonomy, branches, config, coverage, epic,  # noqa: E402
@@ -544,7 +553,7 @@ def test_release_flattens_the_done_tier():
         generate.settle_epic_tier(root)
         assert (v / "complete" / "publish-under-your-name").is_dir()
 
-        version._flatten_done_tier(model.Version(v))
+        version._flatten_done_tier(model.Version(v), root)
         assert (v / "publish-under-your-name").is_dir()
         assert not (v / "complete").exists()
 
@@ -5382,6 +5391,159 @@ def test_rule_titles_and_enforcement_read_the_same_headings():
     assert set(registry.rule_titles(body)) == set(registry._parse_rules(body))
 
 
+def test_every_folder_move_in_the_harness_repairs_its_links():
+    # Three of nine movers repaired their links and six did not, all in the same
+    # way: the snapshot/move/repair dance was pasted in wherever somebody had been
+    # bitten. This is the check that stops a tenth being added the same way — it
+    # reads the source, so a new `shutil.move` outside a `repairing()` block fails
+    # here rather than in somebody's board six weeks later.
+    import ast
+
+    unguarded = []
+    for py in sorted((Path(__file__).parent / "harness").glob("*.py")):
+        tree_ = ast.parse(py.read_text())
+        guarded = set()
+        for node in ast.walk(tree_):
+            if not isinstance(node, ast.With):
+                continue
+            opens = any(isinstance(i.context_expr, ast.Call)
+                        and isinstance(i.context_expr.func, ast.Attribute)
+                        and i.context_expr.func.attr == "repairing"
+                        for i in node.items)
+            if opens:
+                guarded |= {id(d) for b in node.body for d in ast.walk(b)}
+        for node in ast.walk(tree_):
+            if (isinstance(node, ast.Call) and isinstance(node.func, ast.Attribute)
+                    and node.func.attr == "move"
+                    and isinstance(node.func.value, ast.Name)
+                    and node.func.value.id == "shutil"
+                    and id(node) not in guarded):
+                unguarded.append(f"{py.name}:{node.lineno}")
+
+    assert not unguarded, (
+        "a folder move outside `links.repairing(...)` breaks every link that "
+        f"pointed at it, silently: {', '.join(unguarded)}")
+
+
+def test_an_epic_leaving_a_cut_repairs_links_to_the_tasks_that_came_with_it():
+    # A two-stage move: the epic relocates AND each task is lifted out of its
+    # bucket underneath it, so a task ends somewhere neither move alone predicts.
+    # Keyed on the half-way path this silently rewrites every inbound link to a
+    # folder that does not exist.
+    with tempfile.TemporaryDirectory() as tmp:
+        v = _tree(tmp)
+        root = Path(tmp)
+        e = _epic(v, "an-epic")
+        (e / "queue").mkdir()
+        _task(e / "queue", "came-along")
+
+        elsewhere = root / "product" / "note.md"
+        elsewhere.parent.mkdir(parents=True, exist_ok=True)
+        elsewhere.write_text(
+            "planned in [the task](../versions/26-cut/an-epic/queue/"
+            "came-along/task.md)\n")
+
+        os.environ["WORK_DIR"] = tmp
+        try:
+            epic.cmd_epic_move({"name": "an-epic", "backlog": "true"})
+        finally:
+            os.environ.pop("WORK_DIR", None)
+
+        landed = root / "versions" / "backlog" / "an-epic" / "came-along" / "task.md"
+        assert landed.is_file(), "fixture: the task did not land where expected"
+        href = re.search(r"\]\(([^)]+)\)", elsewhere.read_text()).group(1)
+        assert (elsewhere.parent / href).resolve() == landed.resolve(), \
+            f"link points at {href}, which is not where the task went"
+
+
+def test_an_epic_move_snapshots_the_repo_once_not_once_per_task():
+    # The whole-repo scan is ~1s here and slower on a bigger board, so a mover that
+    # moves a task at a time must not pay for it per task. Two of them move in a
+    # loop, which is what made the shared block worth having over a pasted pair.
+    from harness import links as links_mod
+
+    with tempfile.TemporaryDirectory() as tmp:
+        v = _tree(tmp)
+        root = Path(tmp)
+        e = _epic(v, "an-epic")
+        (e / "queue").mkdir()
+        for n in ("one", "two", "three"):
+            _task(e / "queue", n)
+
+        real, calls = links_mod.snapshot, []
+        links_mod.snapshot = lambda repo: (calls.append(repo), real(repo))[1]
+        os.environ["WORK_DIR"] = tmp
+        try:
+            epic.cmd_epic_move({"name": "an-epic", "backlog": "true"})
+        finally:
+            links_mod.snapshot = real
+            os.environ.pop("WORK_DIR", None)
+
+        assert len(calls) == 1, f"scanned the repo {len(calls)} times for 3 tasks"
+
+
+def _migrate(tmp: str, **flags):
+    """`migrate` against a fixture, with WORK_DIR pointing at it."""
+    from harness import migrate as migrate_mod
+    os.environ["WORK_DIR"] = tmp
+    try:
+        return migrate_mod.cmd_migrate(flags)
+    finally:
+        os.environ.pop("WORK_DIR", None)
+
+
+def test_migrate_moves_the_backlog_inside_versions_and_repairs_what_pointed_at_it():
+    # The migration used to be a script in a session's scratchpad, which is to say
+    # it did not exist by the time the next repo needed it. The links are why it
+    # cannot be a shell one-liner: the pointers at a moved task live all over a
+    # repo, and a migration scoped to `work/` passes clean and rots the rest.
+    with tempfile.TemporaryDirectory() as tmp:
+        _tree(tmp)
+        root = Path(tmp)
+        (root / "versions" / "backlog").rmdir()
+        old = root / "backlog" / "later-on" / "a-task"
+        old.mkdir(parents=True)
+        (old / "task.md").write_text("---\npriority: P1\n---\n\n# A task\n")
+
+        # A pointer from OUTSIDE work/ — the half a work-scoped migration misses.
+        outside = root.parent / "notes.md"
+        outside.write_text(f"see [it]({root.name}/backlog/later-on/a-task/task.md)\n")
+
+        assert _migrate(tmp) == 0
+        landed = root / "versions" / "backlog" / "later-on" / "a-task" / "task.md"
+        assert landed.is_file(), "the backlog did not move inside versions/"
+        assert not (root / "backlog").exists()
+        assert (root / "versions" / "archive").is_dir()
+
+        href = re.search(r"\]\(([^)]+)\)", outside.read_text()).group(1)
+        assert (outside.parent / href).resolve() == landed.resolve(), \
+            f"a link outside work/ was left pointing at {href}"
+
+
+def test_migrate_says_nothing_to_do_on_a_repo_already_migrated():
+    # Nobody remembers which repos have been through it, so the safe answer to
+    # running it twice has to be "nothing", not a second move or an error.
+    with tempfile.TemporaryDirectory() as tmp:
+        _tree(tmp)
+        (Path(tmp) / "versions" / "archive").mkdir(exist_ok=True)
+        assert _migrate(tmp) == 0
+        assert not (Path(tmp) / "backlog").exists()
+
+
+def test_migrate_refuses_a_repo_holding_two_backlogs():
+    # Which copy of a task is the real one is a judgement, and a migration that
+    # guesses at it silently loses whichever it did not pick.
+    with tempfile.TemporaryDirectory() as tmp:
+        _tree(tmp)
+        (Path(tmp) / "backlog").mkdir()
+        try:
+            _migrate(tmp)
+            assert False, "migrating a repo with two backlogs should refuse"
+        except SystemExit:
+            pass
+        assert (Path(tmp) / "backlog").is_dir(), "it moved something before refusing"
+
+
 if __name__ == "__main__":
     tests = [v for k, v in sorted(globals().items())
              if k.startswith("test_") and callable(v)]
@@ -5411,4 +5573,5 @@ if __name__ == "__main__":
         config.apply(config.DEFAULTS)
         fn()
         print(f"ok  {fn.__name__}")
+    shutil.rmtree(_TMP, ignore_errors=True)
     print(f"\n{len(tests)} passed")

package/harness/work.py

@@ -12,15 +12,17 @@ ledger: a durable rule lives in the domain or system that owns it, and
     ├── architecture/<system>.md                   how it is built     (hosted rules)
     ├── design/ quality/ security/ operations/     the remaining domains,
     │   support/ commercial/ legal/                each hosting its own rules
-    ├── versions/<v>/version.md                    a RELEASE — permanent record
-    │   └── <epic>/epic.md                         the plan-it-together doc; removed at release
-    │       └── {queue,in-progress,complete}/<task>/
-    └── backlog/<epic>/<task>/                     epics planned but not yet in a cut
-
-A VERSION is a release: it states a user-visible `outcome:` and cannot open
-while an earlier one is unreleased. An EPIC is temporary — the coherent goal
-planned together, archived at release. A TASK is ONE goal, end-to-end,
-internally phased, and always belongs to an epic.
+    └── versions/                                  every state a cut's work is in
+        ├── NN-<name>/version.md                   a RELEASE — permanent record
+        │   └── <epic>/epic.md                     the plan-it-together doc; removed at release
+        │       └── {queue,in-progress,blocked,complete}/<task>/
+        ├── backlog/<epic>/<task>/                 epics planned but not yet in a cut
+        └── archive/<cut>/                         a cut taken off the board unreleased
+
+A VERSION is a release: it states a user-visible `outcome:`, and its folder is
+named `NN-<name>` because the order is part of the name and nothing derives it.
+An EPIC is temporary — the coherent goal planned together, archived at release.
+A TASK is ONE goal, end-to-end, internally phased, and always belongs to an epic.
 
 A task's status is the bucket it sits in — never a frontmatter field; a backlog
 task has none until pulled, which is why the backlog has no buckets. A version's
@@ -53,6 +55,7 @@ Subcommands:
                                    the opening prompt for the NEXT session, derived —
                                    and how to start it where `session.mcp` names a server
     release <v>                    archive <v> [--dry-run]
+    migrate [--dry-run] [--force]  bring work/ up to the layout this harness expects
     init [--project <dir>]         scaffold work/ + the nine domains (idempotent)
     doctor [--project <dir>]       runtime, config, tree, ids, graph — self-diagnosis
     id-new --host <name> --title "…"   claim the next free rule id, atomically
@@ -150,6 +153,7 @@ from harness.gate import cmd_observed, cmd_verify
 from harness.kickoff import cmd_kickoff
 from harness.git import cmd_sync
 from harness.branches import cmd_find
+from harness.migrate import cmd_migrate
 
 
 #: Every subcommand the ladder in `main` dispatches, in the order it tries them.
@@ -161,7 +165,7 @@ SUBCOMMANDS = (
     "epic-new", "feature-new", "version-new", "place", "handoff", "release", "archive",
     "find", "list", "readme", "move", "plan", "session", "kickoff", "path", "code",
     "domain-new", "system-new", "where", "rules", "align", "wrap", "coverage",
-    "migrate-owner", "next", "status", "drop", "ask", "answer", "needs", "verify",
+    "migrate", "migrate-owner", "next", "status", "drop", "ask", "answer", "needs", "verify",
     "observed", "log", "digest", "sync",
 )
 
@@ -489,6 +493,8 @@ def dispatch(cmd, pos, flags, cfg) -> int:
         return cmd_wrap(cfg, flags, _project_root(flags))
     if cmd == "coverage":
         return cmd_coverage(flags)
+    if cmd == "migrate":
+        return cmd_migrate(flags)
     if cmd == "migrate-owner":
         return cmd_migrate_owner(flags)
 

package/package.json

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