@appchy/jarvis 0.1.79 → 0.1.80

package/harness/harness/architecture.py

@@ -131,7 +131,12 @@ def cmd_init(args) -> int:
 
     write(root / "README.md", _README)
     write(root / "ROADMAP.md", _ROADMAP)
-    for d in ("versions", "versions/backlog", "versions/archive"):
+    # All THREE states a cut's work is in, not two. `complete/` was missing here
+    # and in `migrate`, so the folder a released cut belongs in did not exist until
+    # something created it — and the first repo to release a cut had nowhere to put
+    # it that was not a lie about what happened.
+    for d in ("versions", "versions/backlog", "versions/archive",
+              "versions/complete"):
         (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/generate.py

@@ -7,7 +7,7 @@ from pathlib import Path
 
 from .tree import (BACKLOG_END, BACKLOG_START, DONE_TIER, SYSTEMS_END,
                     SYSTEMS_START, die, rel)
-from .model import Task, Version, _ordered, scan
+from .model import Task, Version, _ordered, scan, scan_shipped
 from .registry import rules_by_domain, scan_domains, scan_systems
 from .lint import print_lint
 
@@ -105,6 +105,23 @@ def _regen_readme(root: Path) -> str:
             rows.append(f"| [{d.name}]({d.name}/README.md) | {counts.get(d.name) or '—'} |")
         sections.insert(0, "\n".join(rows))
 
+    # What this repo has DELIVERED, last and one line each — the mirror of the
+    # SHIPPED block in `list`, and here for the same reason. A README whose board
+    # simply stops at the live cuts describes a repo that has never released
+    # anything, which was false the day the first cut shipped.
+    shipped = scan_shipped(root)
+    if shipped:
+        rows = ["### Shipped _( released and off the board — the record is in "
+                "`versions/complete/` )_", ""]
+        for v in shipped:
+            link = f"[{v.title}]({_relpath_from_readme(v.md, root)})"
+            n = len(v.all_tasks())
+            rows.append(f"- **{link}** — `{v.name}` · released {v.released} "
+                        f"· {n} task(s)")
+            if v.outcome:
+                rows.append(f"  <br>{v.outcome}")
+        sections.append("\n".join(rows))
+
     block = "\n\n".join(sections) if sections else "_backlog is empty_"
     # The replacement is a CALLABLE so that what goes in comes back out. A title is
     # something a person typed, and as a replacement template `\d` is a bad escape

package/harness/harness/migrate.py

@@ -24,7 +24,7 @@ import shutil
 import subprocess
 from pathlib import Path
 
-from .tree import archive_dir, backlog_dir, die, find_work_root, rel
+from .tree import archive_dir, backlog_dir, complete_dir, die, find_work_root, rel
 from . import links
 
 
@@ -79,6 +79,7 @@ def cmd_migrate(args) -> int:
     old = root / "backlog"
     new = backlog_dir(root)
     archive = archive_dir(root)
+    complete = complete_dir(root)
     cuts = _archived_cuts(root)
 
     # The hard refusals. Two of anything means somebody has already started this,
@@ -101,6 +102,8 @@ def cmd_migrate(args) -> int:
         todo.append(f"{len(cuts)} archived cut(s) move inside versions/")
     if not archive.is_dir():
         todo.append("versions/archive/ is created")
+    if not complete.is_dir():
+        todo.append("versions/complete/ is created")
     if not todo:
         print(f"{rel(root, root)} is already on the current layout — nothing to do")
         return 0
@@ -142,12 +145,17 @@ def cmd_migrate(args) -> int:
             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)}")
+    # Both off-board homes, for the same reason: an empty directory does not
+    # survive git, and the point of making them now is that `archive` has somewhere
+    # to put a cut without inventing it later — under either outcome. A repo that
+    # migrated before `complete/` existed gets it here rather than on the day it
+    # first releases something, which is the worst moment to find a folder missing.
+    for d in (archive, complete):
+        if d.is_dir():
+            continue
+        d.mkdir(parents=True, exist_ok=True)
+        (d / ".gitkeep").write_text("")
+        print(f"created {rel(d, root)}")
 
     if cuts:
         # One block for every cut. Each carries a whole released version's worth of

package/harness/harness/model.py

@@ -310,15 +310,43 @@ def locate(root: Path, name: str):
             return t
     return None
 def locate_version(root: Path, name: str):
-    """Find a version by name. Looks in `versions/archive/` too, so a finished
-    cut stays LOOKUPABLE after it leaves the board — `path` and `where` keep
-    answering, while `scan` (and therefore `list`, the README and every lint)
-    sees only live work. Archived is off the board, not gone."""
-    for base in ("versions", "versions/archive"):
+    """Find a version by name. Looks in BOTH homes a cut leaves the board for —
+    `versions/complete/` and `versions/archive/` — so a finished cut stays
+    LOOKUPABLE after it goes, and `path` keeps answering, while `scan` (and
+    therefore `list`, the README and every lint) sees only live work. Off the
+    board is not gone.
+
+    Both are named here rather than one, because a lookup that knows only the
+    home a cut USED to have is how a move makes a cut vanish: 232 backlog rows
+    dropped out of one README when the tree moved under a reader that had not."""
+    for base in ("versions", "versions/complete", "versions/archive"):
         folder = root / base / name
         if (folder / "version.md").is_file():
             return Version(folder)
     return None
+
+
+def scan_shipped(root: Path) -> list:
+    """Every cut filed under `versions/complete/`, newest release first.
+
+    Deliberately NOT part of `scan`. `scan` answers "what is moving", and a shipped
+    cut is not — that separation is why archiving one stopped `list` having to be
+    read past 60 finished tasks. This answers the other question, "what has this
+    repo actually delivered", and its two readers (`list` and the README) render one
+    LINE per cut from it rather than its tasks.
+
+    Sorted by release date descending so the most recent thing shipped reads first.
+    Two passes rather than one reversed key: a same-day pair of cuts must still read
+    in roadmap order, and reversing a compound key would stand those on their head
+    too."""
+    cdir = root / "versions" / "complete"
+    if not cdir.is_dir():
+        return []
+    cuts = [Version(v) for v in sorted(cdir.iterdir())
+            if v.is_dir() and (v / "version.md").is_file()]
+    cuts.sort(key=lambda v: (v.order, v.name))
+    cuts.sort(key=lambda v: v.released or "", reverse=True)
+    return cuts
 def locate_epic(root: Path, name: str):
     """Find an epic by name anywhere — in a version or in the backlog. Names are
     globally unique across tasks, epics and versions, so a name alone resolves."""

package/harness/harness/report.py

@@ -5,7 +5,7 @@ from pathlib import Path
 
 from .tree import find_work_root, rel
 from .frontmatter import _eol, read_item, split_frontmatter, write_item
-from .model import Task, _ordered, scan
+from .model import Task, _ordered, scan, scan_shipped
 from .lint import lint_warnings
 from .generate import _regen_readme, _sync, settle_epic_tier
 from .align import (_align_acceptance, _align_agents, _align_citations,
@@ -69,7 +69,12 @@ def cmd_list(args) -> int:
                  for d in domains]
         print("DOMAINS  " + " · ".join(cells) + "        (n) = rules hosted")
 
-    if not s["versions"] and not s["backlog"]:
+    # READ BEFORE THE EMPTINESS TEST, because a shipped cut is not nothing. A repo
+    # whose only cut has been released has no live versions and no backlog, and the
+    # early return printed "backlog is empty" over the top of a delivered release —
+    # the precise reading this block exists to stop.
+    shipped = scan_shipped(root)
+    if not s["versions"] and not s["backlog"] and not shipped:
         print("\nbacklog is empty")
         return 0
 
@@ -116,6 +121,17 @@ def cmd_list(args) -> int:
             print()
             for t in loose:
                 print(f"    {_task_line(t)}")
+
+    # WHAT THIS REPO HAS ACTUALLY DELIVERED, at the bottom and one line each.
+    # A shipped cut leaves the live board — that is what made this list readable —
+    # but leaving it out entirely made a repo with a release behind it read exactly
+    # like a repo that has never shipped anything. The count is the whole cut, so
+    # `142/142` says a release closed rather than a bucket did.
+    for v in shipped:
+        n = len(v.all_tasks())
+        print(f"\nSHIPPED  {v.name} — {v.title} · released {v.released} · {n}/{n}")
+        if v.outcome:
+            print(f"         {v.outcome}")
     print()
     warns = lint_warnings(root)
     if warns:

package/harness/harness/tree.py

@@ -218,8 +218,29 @@ def backlog_dir(root: Path) -> Path:
 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."""
+    this it sits in the live list looking open forever.
+
+    One of TWO homes a cut leaves the board for, and the other is `complete_dir`.
+    Which one is not a choice a caller makes: `archive` reads the `released:` stamp,
+    because whether a cut shipped is a fact the tree already holds."""
     return root / "versions" / "archive"
+
+
+def complete_dir(root: Path) -> Path:
+    """Where a cut that SHIPPED is filed — released, outcome met, nothing owed.
+
+    The third folder of `versions/{backlog,archive,complete}`, and it exists because
+    the other two could not say this. A released cut sent to `archive/` is filed
+    under "releasing would be a lie" — the exact opposite of what happened to it —
+    and one left in `versions/` sits among the live cuts looking open. Measured: a
+    repo released its first cut and had nowhere to put it, so it stayed on the board
+    for a day rather than be described wrongly.
+
+    Off the live board is not gone. `locate_version` resolves a cut here, and the
+    board keeps ONE line for it — what it was, when it shipped, what it delivered —
+    because a board that drops its releases reads as a board that has never shipped
+    anything."""
+    return root / "versions" / "complete"
 def assets_dir() -> Path:
     return PAYLOAD_DIR / "assets"
 def rel(p: Path, root: Path) -> str:

package/harness/harness/version.py

@@ -5,7 +5,8 @@ from datetime import date
 from pathlib import Path
 
 from . import ids
-from .tree import archive_dir, DONE_TIER, VERSION_FM_ORDER, cli, die, find_work_root, rel
+from .tree import (archive_dir, complete_dir, DONE_TIER, VERSION_FM_ORDER, cli, die,
+                   find_work_root, rel)
 from .frontmatter import rewrite_file
 from .model import _is_epic_dir, locate_version, scan
 from .scaffold import _check_unused, _check_version_name, _scaffold_version
@@ -199,7 +200,8 @@ def cmd_release(args) -> int:
     print("\nDistill before archiving:")
     print("  1. Promote still-load-bearing decisions to the domain or system that owns them")
     print(f"  2. Repoint any inbound deep-links to those {ids.LEDGER}-nn entries")
-    print(f"  3. {cli()} archive {name}   (strips each task to task.md)")
+    print(f"  3. {cli()} archive {name}   (strips each task to task.md, and "
+          f"files a RELEASED cut under versions/complete/)")
     _sync(root)
     return 0
 def _short_sha() -> str:
@@ -233,6 +235,21 @@ def _contained(p: Path, root: Path) -> Path:
     return rp
 
 
+def _home_for(version, root: Path) -> Path:
+    """Which of the two off-board homes this cut belongs in, read from the tree.
+
+    A cut carrying `released:` SHIPPED, and goes to `versions/complete/`. One
+    without it is leaving the board for the other reason — its work moved elsewhere
+    and there is no outcome it honestly met — and goes to `versions/archive/`,
+    which is what that folder's own description has always said it was for.
+
+    Not a flag, and deliberately not a second verb. Whether a cut shipped is a fact
+    the tree already holds, and asking the caller to restate it is how the folder
+    and the stamp end up disagreeing — the same two-writers-for-one-fact that makes
+    a status field drift from the bucket it sits in."""
+    return complete_dir(root) if version.released else archive_dir(root)
+
+
 def cmd_archive(args) -> int:
     root = find_work_root()
     name = args["name"]
@@ -285,7 +302,7 @@ def cmd_archive(args) -> int:
             removed += 1
 
     if dry:
-        dest = archive_dir(root) / name
+        dest = _home_for(version, root) / name
         print(f"  stamp   archived: on {rel(version.md, root)}")
         print(f"  move    {rel(version.folder, root)} -> {rel(dest, root)}")
         print(f"\n  {removed} file(s)/dir(s) would be stripped. "
@@ -309,7 +326,7 @@ def cmd_archive(args) -> int:
     # past 60 completed tasks to find the 6 that were actually moving. The
     # record is preserved verbatim in `archive/versions/<v>/`, where `path` and
     # `where` still resolve it — it is just no longer in the way.
-    dest = _contained(archive_dir(root) / name, root)
+    dest = _contained(_home_for(version, root) / name, root)
     if dest.exists():
         die(f"{rel(dest, root)} already exists")
     dest.parent.mkdir(parents=True, exist_ok=True)
@@ -319,7 +336,12 @@ def cmd_archive(args) -> int:
 
     where = f" — full docs in git history @ {sha}" if sha else ""
     events.append(root, "archived", name, stripped=removed)
-    print(f"archived '{name}': stripped {removed} file(s) to task.md, "
+    # SAY WHICH, and say it in the words of what happened rather than the verb's
+    # name: "archived" reads as binned, and a cut that shipped has just been filed
+    # under the opposite of that. The verb is one because the move is one; the
+    # sentence is two because the outcomes are.
+    did = "filed as complete — it shipped" if version.released else "archived"
+    print(f"{did}: '{name}' stripped {removed} file(s) to task.md, "
           f"moved to {rel(dest, root)}{where}")
     _sync(root)
     return 0

package/harness/test_work.py

@@ -26,7 +26,7 @@ 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
                      events, extend, frontmatter, gate, generate, git, ids, kickoff,
-                     lint, model, peers, registry, safety, scaffold,
+                     lint, model, peers, registry, report, safety, scaffold,
                      shift, task, tree, version)
 
 # `parse_argv` is the ENTRY's own concern, so it is loaded from work.py by path
@@ -967,14 +967,18 @@ def test_release_does_not_treat_a_flat_versions_completed_tasks_as_epics():
             ("flat-shipped-thing", "complete")]
 
 
-def test_archive_moves_the_version_off_the_board_but_keeps_it_lookupable():
+def test_archive_moves_an_unreleased_cut_off_the_board_but_keeps_it_lookupable():
     # Archived is OFF THE BOARD, not gone: `scan` (and therefore list, the
     # README and every lint) stops seeing it, while `locate_version` still
     # resolves it so `path` and `where` keep answering.
+    #
+    # NO `released:` HERE, and that is the point of the fixture rather than an
+    # omission: `versions/archive/` is where a cut goes when releasing it would be
+    # a lie. The released arm lands somewhere else and has its own test below.
     import os
     with tempfile.TemporaryDirectory() as tmp:
         root = Path(tmp)
-        v = _tree(tmp, "26-cut", released="2026-08-01")
+        v = _tree(tmp, "26-cut")
         e = _epic(v, "an-epic")
         _task(e / "complete", "shipped-thing")
         (e / "complete" / "shipped-thing" / "plan.md").write_text("design\n")
@@ -995,6 +999,100 @@ def test_archive_moves_the_version_off_the_board_but_keeps_it_lookupable():
         assert model.locate_version(root, "26-cut") is not None
 
 
+def test_archive_files_a_released_cut_under_complete_not_archive():
+    # THE ARM THAT DID NOT EXIST. A cut carrying `released:` shipped — it met its
+    # outcome and owes nothing — so filing it under "releasing would be a lie" is
+    # the one description of it that is false. It goes to `versions/complete/`, and
+    # `archive/` is not even created on this path.
+    #
+    # Same strip either way: what a task carries beyond its brief is the working
+    # papers of a session, and `release` already tells you to lift anything still
+    # load-bearing into the domain that owns it before this runs.
+    import os
+    with tempfile.TemporaryDirectory() as tmp:
+        root = Path(tmp)
+        v = _tree(tmp, "26-cut", released="2026-08-01")
+        e = _epic(v, "an-epic")
+        _task(e / "complete", "shipped-thing")
+        (e / "complete" / "shipped-thing" / "handoff.md").write_text("notes\n")
+        os.environ["WORK_DIR"] = tmp
+        try:
+            version.cmd_archive({"name": "26-cut"})
+        finally:
+            os.environ.pop("WORK_DIR")
+
+        assert not (root / "versions" / "26-cut").exists()
+        assert not (root / "versions" / "archive" / "26-cut").exists()
+        dest = root / "versions" / "complete" / "26-cut"
+        assert (dest / "version.md").is_file()
+        assert (dest / "an-epic" / "complete" / "shipped-thing" / "task.md").is_file()
+        assert not (dest / "an-epic" / "complete" / "shipped-thing" / "handoff.md").exists()
+
+        # Off the LIVE board, still resolvable by name — `path` keeps answering.
+        assert model.scan(root)["versions"] == []
+        found = model.locate_version(root, "26-cut")
+        assert found is not None
+        assert found.folder == dest
+
+
+def test_archive_dry_run_names_the_home_a_released_cut_is_going_to():
+    # A dry run whose printed destination is not the real one is worse than no dry
+    # run: it is a rehearsal of a different command. Both arms read the same stamp.
+    import io, os, contextlib
+    with tempfile.TemporaryDirectory() as tmp:
+        v = _tree(tmp, "26-cut", released="2026-08-01")
+        e = _epic(v, "an-epic")
+        _task(e / "complete", "shipped-thing")
+        os.environ["WORK_DIR"] = tmp
+        try:
+            out = io.StringIO()
+            with contextlib.redirect_stdout(out):
+                version.cmd_archive({"name": "26-cut", "dry-run": "true"})
+        finally:
+            os.environ.pop("WORK_DIR")
+        text = out.getvalue()
+        assert "versions/complete/26-cut" in text, text
+        assert "versions/archive/26-cut" not in text, text
+
+
+def test_the_board_accounts_for_a_shipped_cut_in_one_line():
+    # A cut that shipped leaves the live board — that is what keeps `list`
+    # readable — but leaving it out ENTIRELY made a repo with a release behind it
+    # read exactly like one that has never shipped anything. So both readers keep
+    # one line for it: what it was, when it shipped, what it delivered.
+    import io, os, contextlib
+    with tempfile.TemporaryDirectory() as tmp:
+        root = Path(tmp)
+        v = _tree(tmp, "26-cut", outcome="a user can bounce a mix",
+                  released="2026-08-01")
+        e = _epic(v, "an-epic")
+        _task(e / "complete", "shipped-thing")
+        os.environ["WORK_DIR"] = tmp
+        try:
+            with contextlib.redirect_stdout(io.StringIO()):
+                version.cmd_archive({"name": "26-cut"})
+            out = io.StringIO()
+            with contextlib.redirect_stdout(out):
+                report.cmd_list({})
+        finally:
+            os.environ.pop("WORK_DIR")
+
+        listed = out.getvalue()
+        assert "SHIPPED  26-cut" in listed, listed
+        assert "released 2026-08-01" in listed, listed
+        assert "a user can bounce a mix" in listed, listed
+        assert "1/1" in listed, listed
+        # ONE LINE, not the cut's task rows — the tasks stay in the record.
+        assert "shipped-thing" not in listed, listed
+
+        readme = (root / "README.md").read_text()
+        assert "### Shipped" in readme, readme
+        assert "versions/complete/26-cut/version.md" in readme, readme
+        assert "released 2026-08-01" in readme, readme
+        assert "a user can bounce a mix" in readme, readme
+        assert "shipped-thing" not in readme, readme
+
+
 def test_epic_covers_must_be_feature_qualified():
     # A bare AC-01 would name a different criterion in each feature an epic
     # spans, so the format check is a refusal at write time.

package/harness/work.py

@@ -17,6 +17,7 @@ ledger: a durable rule lives in the domain or system that owns it, and
         │   └── <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
+        ├── complete/<cut>/                        a cut that SHIPPED — released, outcome met
         └── archive/<cut>/                         a cut taken off the board unreleased
 
 A VERSION is a release: it states a user-visible `outcome:`, and its folder is

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appchy/jarvis",
-  "version": "0.1.79",
+  "version": "0.1.80",
   "description": "Jarvis — local AI coding assistant CLI",
   "private": false,
   "type": "module",
@@ -57,15 +57,15 @@
     "typescript": "^5.7.0",
     "vitest": "^2.1.0",
     "@jarvis/agents": "1.0.0",
-    "@jarvis/anthropic": "1.0.0",
     "@jarvis/board": "0.1.0",
+    "@jarvis/anthropic": "1.0.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/typescript-config": "1.0.0",
     "@jarvis/vitest-config": "1.0.0"
   },
   "scripts": {