@appchy/jarvis 0.1.124 → 0.1.126

package/harness/test_work.py

@@ -8536,6 +8536,354 @@ def test_a_tier_zero_item_is_not_asked_to_have_looked():
         assert check.checked(root, model.locate(root, "trivial"), "some-session")
 
 
+
+# ---------------------------------------------------------------------------
+# Work we stopped doing — `archive` at the item tier.
+#
+# The board could say an item was FINISHED and could not say we decided not to do
+# it. The only way off the board was completion or deleting the folder by hand,
+# which the method forbids, so the cheapest legal action was always to leave the
+# item — and four boards measured on 2026-09-12 are what that looks like after a
+# month: 62 items had ever left three of them, against 1,290 created.
+#
+# `archive` already meant the right thing at the wrong size: it took a whole cut
+# and refused unless every task in it was complete. So the verb dispatches on what
+# the name IS, exactly as `place` does, rather than a second word being invented.
+# ---------------------------------------------------------------------------
+
+
+def _archived_entries(folder: Path) -> list:
+    return frontmatter.as_list(
+        frontmatter.parse_frontmatter((folder / "task.md").read_text()).get("archived"))
+
+
+def test_an_archive_reason_survives_a_comma():
+    # The reason is free text somebody typed, and the INLINE list form splits on
+    # commas — so "we tried it, it did not work" came back as two entries with the
+    # date attached to half of it. The same failure `--question` already had, and
+    # the same fix: this key is written as a block list, never inline.
+    with tempfile.TemporaryDirectory() as tmp:
+        root = Path(tmp)
+        v = _tree(tmp, "26-cut")
+        e = _epic(v, "an-epic")
+        _task(e / "queue", "comma-case")
+        os.environ["WORK_DIR"] = tmp
+        try:
+            version.cmd_archive({"name": "comma-case",
+                                 "why": "we tried it, it did not work"})
+        finally:
+            os.environ.pop("WORK_DIR")
+        entries = _archived_entries(root / "versions" / "archive" / "comma-case")
+        assert len(entries) == 1, entries
+        assert "we tried it, it did not work" in entries[0], entries
+
+
+def test_archive_takes_one_item_off_the_board_and_records_why():
+    # THE MISSING STATE. Nothing is deleted and nothing claims the work was done:
+    # what remains says when we stopped and what the reason was, so the same
+    # proposal can be answered with a citation instead of being re-argued.
+    with tempfile.TemporaryDirectory() as tmp:
+        root = Path(tmp)
+        v = _tree(tmp, "26-cut")
+        e = _epic(v, "an-epic")
+        _task(e / "queue", "a-duplicate")
+        os.environ["WORK_DIR"] = tmp
+        try:
+            assert version.cmd_archive(
+                {"name": "a-duplicate", "why": "duplicate of ten-tasks"}) == 0
+        finally:
+            os.environ.pop("WORK_DIR")
+
+        assert not (e / "queue" / "a-duplicate").exists()
+        dest = root / "versions" / "archive" / "a-duplicate"
+        assert (dest / "task.md").is_file(), "the item's own text survives"
+
+        entries = _archived_entries(dest)
+        assert len(entries) == 1, entries
+        assert "duplicate of ten-tasks" in entries[0], entries
+        assert date.today().isoformat() in entries[0], entries
+        # WHERE it was proposed, so a reader knows what it was part of without
+        # having to go and find the commit that moved it.
+        assert "26-cut/an-epic" in entries[0], entries
+
+
+def test_an_archived_item_is_off_the_board_but_still_resolves():
+    # The whole difference between this and a delete. `scan` — and therefore
+    # `list`, the README table and every lint — stops seeing it, while `path`
+    # keeps answering, exactly as an archived CUT already does.
+    with tempfile.TemporaryDirectory() as tmp:
+        root = Path(tmp)
+        v = _tree(tmp, "26-cut")
+        e = _epic(v, "an-epic")
+        _task(e / "queue", "not-doing-this")
+        _task(e / "queue", "still-doing-this")
+        os.environ["WORK_DIR"] = tmp
+        try:
+            version.cmd_archive({"name": "not-doing-this", "why": "wrong idea"})
+        finally:
+            os.environ.pop("WORK_DIR")
+
+        live = [t.name for vv in model.scan(root)["versions"] for t in vv.all_tasks()]
+        assert live == ["still-doing-this"], live
+        # A write cannot reach it; a READ opts in, the same seam a filed cut uses.
+        assert model.locate(root, "not-doing-this") is None
+        found = model.locate(root, "not-doing-this", filed=True)
+        assert found is not None and found.status == "archived"
+        assert found.folder == root / "versions" / "archive" / "not-doing-this"
+
+
+def test_archive_refuses_an_item_with_no_reason():
+    # An archived item with no WHY is one somebody re-proposes next month, which
+    # is the failure this state exists to end rather than a field to be tidy about.
+    with tempfile.TemporaryDirectory() as tmp:
+        v = _tree(tmp, "26-cut")
+        e = _epic(v, "an-epic")
+        _task(e / "queue", "no-reason-given")
+        os.environ["WORK_DIR"] = tmp
+        try:
+            version.cmd_archive({"name": "no-reason-given"})
+            raise AssertionError("archived an item without saying why")
+        except SystemExit as ex:
+            assert ex.code == 1
+        finally:
+            os.environ.pop("WORK_DIR")
+        assert (e / "queue" / "no-reason-given").is_dir(), "nothing moved"
+
+
+def test_archive_refuses_a_completed_item():
+    # A completed task stays in the cut it shipped in — the one thing the board
+    # fixes. A release whose contents can be edited afterwards cannot answer what
+    # it delivered, and archiving one would be exactly that edit.
+    with tempfile.TemporaryDirectory() as tmp:
+        v = _tree(tmp, "26-cut")
+        e = _epic(v, "an-epic")
+        _task(e / "complete", "already-shipped")
+        os.environ["WORK_DIR"] = tmp
+        try:
+            version.cmd_archive({"name": "already-shipped", "why": "changed my mind"})
+            raise AssertionError("archived work that had already shipped")
+        except SystemExit as ex:
+            assert ex.code == 1
+        finally:
+            os.environ.pop("WORK_DIR")
+        assert (e / "complete" / "already-shipped").is_dir()
+
+
+def test_archive_refuses_an_item_another_one_still_depends_on():
+    # Dropping something under a dependent leaves that dependent waiting on a name
+    # nothing will ever complete — and `next` skips it forever with "depends on
+    # incomplete", which reads as a queue problem rather than as this.
+    with tempfile.TemporaryDirectory() as tmp:
+        v = _tree(tmp, "26-cut")
+        e = _epic(v, "an-epic")
+        _task(e / "queue", "the-foundation")
+        _task(e / "queue", "built-on-it",
+              fm="priority: P1\ndepends_on: [the-foundation]\n")
+        os.environ["WORK_DIR"] = tmp
+        try:
+            version.cmd_archive({"name": "the-foundation", "why": "not worth it"})
+            raise AssertionError("archived an item something else waits on")
+        except SystemExit as ex:
+            assert ex.code == 1
+        finally:
+            os.environ.pop("WORK_DIR")
+        assert (e / "queue" / "the-foundation").is_dir()
+
+
+def test_archiving_an_item_strips_nothing():
+    # The opposite of what archiving a CUT does, and deliberately so. A cut is
+    # archived AFTER its plans have been distilled into the domains that own them;
+    # an item is archived INSTEAD of being done, so the thinking that reached that
+    # decision is the whole of what there is to keep.
+    with tempfile.TemporaryDirectory() as tmp:
+        root = Path(tmp)
+        v = _tree(tmp, "26-cut")
+        e = _epic(v, "an-epic")
+        t = _task(e / "in-progress", "half-built")
+        (t / "handoff.md").write_text("where it got to\n")
+        (t / "research").mkdir()
+        (t / "research" / "00-report.md").write_text("what we found out\n")
+        os.environ["WORK_DIR"] = tmp
+        try:
+            version.cmd_archive({"name": "half-built", "why": "the approach was wrong"})
+        finally:
+            os.environ.pop("WORK_DIR")
+
+        dest = root / "versions" / "archive" / "half-built"
+        assert (dest / "handoff.md").is_file()
+        assert (dest / "research" / "00-report.md").is_file()
+
+
+def test_a_backlog_item_can_be_archived():
+    # Where most droppable work actually sits. The backlog is read as intent, so an
+    # item nobody means to do overstates what is coming just as loudly there.
+    with tempfile.TemporaryDirectory() as tmp:
+        root = Path(tmp)
+        _tree(tmp, "26-cut")
+        be = _epic(root / "versions" / "backlog", "a-backlog-epic")
+        _task(be, "never-mind")
+        os.environ["WORK_DIR"] = tmp
+        try:
+            assert version.cmd_archive({"name": "never-mind", "why": "superseded"}) == 0
+        finally:
+            os.environ.pop("WORK_DIR")
+        assert (root / "versions" / "archive" / "never-mind" / "task.md").is_file()
+        assert model.scan(root)["backlog"] == []
+
+
+def test_a_cut_holding_an_archived_item_releases_and_archives():
+    # The item left the cut when it was archived, so a release never sees it —
+    # which is the arithmetic that has to hold or a cut can never close behind one.
+    with tempfile.TemporaryDirectory() as tmp:
+        root = Path(tmp)
+        v = _tree(tmp, "26-cut")
+        e = _epic(v, "an-epic")
+        _task(e / "complete", "the-work-we-did")
+        _task(e / "queue", "the-work-we-didnt")
+        os.environ["WORK_DIR"] = tmp
+        try:
+            version.cmd_archive({"name": "the-work-we-didnt", "why": "out of scope"})
+            # Every task that is still IN the cut is complete, so this may close.
+            assert version.cmd_release({"name": "26-cut"}) == 0
+            assert version.cmd_archive({"name": "26-cut"}) == 0
+        finally:
+            os.environ.pop("WORK_DIR")
+
+        # The cut shipped, so it files under complete/ …
+        assert (root / "versions" / "complete" / "26-cut" / "version.md").is_file()
+        # … and the archived item is untouched by either, still where it went.
+        assert (root / "versions" / "archive" / "the-work-we-didnt" / "task.md").is_file()
+
+
+def test_an_archived_item_can_come_back_and_keeps_its_history():
+    # Archived is not deleted, so it is reversible — and putting one back is a
+    # person's deliberate act, which is what keeps the archive read as decisions
+    # rather than as a second queue. The record is APPENDED to, never erased: a
+    # board that can forget it changed its mind cannot be asked why it did.
+    with tempfile.TemporaryDirectory() as tmp:
+        root = Path(tmp)
+        v = _tree(tmp, "26-cut")
+        e = _epic(v, "an-epic")
+        _task(e / "queue", "worth-doing-after-all")
+        os.environ["WORK_DIR"] = tmp
+        try:
+            version.cmd_archive({"name": "worth-doing-after-all", "why": "too early"})
+            assert task.cmd_place({"name": "worth-doing-after-all",
+                                   "version": "26-cut", "epic": "an-epic"}) == 0
+        finally:
+            os.environ.pop("WORK_DIR")
+
+        back = e / "queue" / "worth-doing-after-all"
+        assert back.is_dir(), "it lands queued — it has no bucket to keep"
+        assert not (root / "versions" / "archive" / "worth-doing-after-all").exists()
+        entries = _archived_entries(back)
+        assert len(entries) == 2, entries
+        assert "too early" in entries[0], entries
+        assert entries[1].startswith("restored "), entries
+
+
+def test_archive_still_takes_a_version():
+    # The dispatch must not have cost the tier it already served. Names are unique
+    # across all three tiers, so what the name IS decides which archive runs.
+    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")
+        os.environ["WORK_DIR"] = tmp
+        try:
+            assert version.cmd_archive({"name": "26-cut"}) == 0
+        finally:
+            os.environ.pop("WORK_DIR")
+        assert (root / "versions" / "complete" / "26-cut" / "version.md").is_file()
+
+
+def test_archive_of_an_unknown_name_names_both_tiers():
+    import io, contextlib
+    # One verb over two tiers means the refusal has to say what it looked for —
+    # "no version named 'x'" against a mistyped TASK sends the reader to the wrong
+    # question entirely.
+    with tempfile.TemporaryDirectory() as tmp:
+        _tree(tmp, "26-cut")
+        os.environ["WORK_DIR"] = tmp
+        buf = io.StringIO()
+        try:
+            with contextlib.redirect_stderr(buf):
+                version.cmd_archive({"name": "never-existed", "why": "x"})
+            raise AssertionError("archived a name that resolves to nothing")
+        except SystemExit as ex:
+            assert ex.code == 1
+        finally:
+            os.environ.pop("WORK_DIR")
+        assert "task or version" in buf.getvalue(), buf.getvalue()
+
+
+def test_archiving_twice_says_where_it_already_went():
+    import io, contextlib
+    # The second attempt is somebody who has lost track of it, not somebody making
+    # a mistake — so it answers the question they actually have.
+    with tempfile.TemporaryDirectory() as tmp:
+        v = _tree(tmp, "26-cut")
+        e = _epic(v, "an-epic")
+        _task(e / "queue", "gone-already")
+        os.environ["WORK_DIR"] = tmp
+        buf = io.StringIO()
+        try:
+            version.cmd_archive({"name": "gone-already", "why": "no"})
+            with contextlib.redirect_stderr(buf):
+                version.cmd_archive({"name": "gone-already", "why": "still no"})
+            raise AssertionError("archived the same item twice")
+        except SystemExit as ex:
+            assert ex.code == 1
+        finally:
+            os.environ.pop("WORK_DIR")
+        assert "already archived" in buf.getvalue(), buf.getvalue()
+
+
+def test_list_archived_says_what_was_taken_off_the_board():
+    import io, contextlib
+    # The board deliberately does not show these, so there has to be a door that
+    # does — otherwise the only way to find a decision is to already know its name,
+    # and a record nobody can browse stops the same proposal coming back only by
+    # luck.
+    with tempfile.TemporaryDirectory() as tmp:
+        v = _tree(tmp, "26-cut")
+        e = _epic(v, "an-epic")
+        _task(e / "queue", "dropped-one")
+        os.environ["WORK_DIR"] = tmp
+        buf = io.StringIO()
+        try:
+            version.cmd_archive({"name": "dropped-one", "why": "overtaken by events"})
+            with contextlib.redirect_stdout(buf):
+                assert report.cmd_list({"archived": "true"}) == 0
+        finally:
+            os.environ.pop("WORK_DIR")
+        out = buf.getvalue()
+        assert "dropped-one" in out, out
+        assert "overtaken by events" in out, out
+
+
+def test_the_readme_never_shows_an_archived_item():
+    # AC-03 read literally: off the board means off every derived table, and the
+    # README settles in BOTH directions — the row goes when it is archived and
+    # comes back when it is restored.
+    with tempfile.TemporaryDirectory() as tmp:
+        root = Path(tmp)
+        v = _tree(tmp, "26-cut")
+        e = _epic(v, "an-epic")
+        _task(e / "queue", "quietly-dropped")
+        os.environ["WORK_DIR"] = tmp
+        try:
+            generate._sync(root)
+            assert "quietly-dropped" in (root / "README.md").read_text()
+            version.cmd_archive({"name": "quietly-dropped", "why": "no longer wanted"})
+            assert "quietly-dropped" not in (root / "README.md").read_text()
+            task.cmd_place({"name": "quietly-dropped", "version": "26-cut",
+                            "epic": "an-epic"})
+            assert "quietly-dropped" in (root / "README.md").read_text()
+        finally:
+            os.environ.pop("WORK_DIR")
+
 if __name__ == "__main__":
     tests = [v for k, v in sorted(globals().items())
              if k.startswith("test_") and callable(v)]

package/harness/work.py

@@ -18,7 +18,9 @@ ledger: a durable rule lives in the domain or system that owns it, and
         │       └── {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
+        └── archive/                               taken off the board, not deleted
+            ├── <cut>/                             a cut left unreleased — nothing owed on it
+            └── <item>/                            ONE item we decided not to do
 
 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.
@@ -28,7 +30,14 @@ 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
 status is derived. Names are globally unique across all three tiers, so a name
-alone resolves anywhere — `place` dispatches on what the name IS.
+alone resolves anywhere — `place` and `archive` both dispatch on what the name IS.
+
+COMPLETE, RELEASED and ARCHIVED are three different words. `complete` is ONE item
+finished; `released` is a whole CUT that met its `outcome:`; `archived` is either
+tier taken OFF the board — a cut with nothing owed on it, or an item we decided not
+to do. Off the board is not gone: `list`, the README and every lint stop seeing it
+while `path` and `where` still resolve it. Deleting a task folder by hand is not a
+third way off the board; `archive <name> --why "…"` is, and it strips nothing.
 
 WHAT IS DERIVED, and therefore never written by hand: the `code:` region
 vocabulary (the union of what the systems declare) · work/README.md's table ·
@@ -50,12 +59,16 @@ Subcommands:
           <name> --backlog --epic <e>         anywhere, to anywhere
                                    an EPIC moves whole; a task needs --epic
     move <name> <queue|in-progress|complete>
+    archive <name> --why "…"       stop doing ONE item — off the board, not deleted.
+                                   Refused with no reason, on completed work, and on
+                                   anything another live item still depends_on
     handoff <name>                 plan <name> [--file <path>]
     session <name> [--id <uuid>]   the current session, or one this one STARTED
     kickoff <name> [--next "…"] [--watch "…"] [--prompt-only]
                                    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]
+    list --archived                what we decided not to do, and why
     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
@@ -481,7 +494,10 @@ def dispatch(cmd, pos, flags, cfg) -> int:
         return cmd_release({"name": pos[0]})
     if cmd == "archive":
         if not pos:
-            die("usage: jarvis work archive <v> [--dry-run]")
+            die("usage: jarvis work archive <cut> [--dry-run]   "
+                "(a whole cut off the board)\n"
+                "       or: jarvis work archive <item> --why \"…\"   "
+                "(stop doing one item — off the board, not deleted)")
         return cmd_archive({"name": pos[0], **flags})
     if cmd == "find":
         if not pos:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appchy/jarvis",
-  "version": "0.1.124",
+  "version": "0.1.126",
   "description": "Jarvis — local AI coding assistant CLI",
   "private": false,
   "type": "module",