@appchy/jarvis 0.1.124 → 0.1.126

package/harness/harness/events.py

@@ -77,7 +77,9 @@ KINDS = (
     "gate-refused",   # completion was refused, and why
     "completed",      # a task landed
     "released",       # a version shipped
-    "archived",       # ...and left the board
+    "archived",       # ...and left the board — a whole cut, or ONE item we
+                      #   decided not to do, which is the same event at two tiers
+    "restored",       # an archived item was wanted again and put back
 )
 
 

package/harness/harness/frontmatter.py

@@ -10,7 +10,7 @@ from .tree import TASK_FM_ORDER
 #: verify command's name and result. `--question "does it ship signed, or later?"`
 #: rendered inline would come back as two list entries, and the answer would be
 #: filed against half a question.
-BLOCK_LISTS = ("sessions", "plans", "asked", "verified", "observed")
+BLOCK_LISTS = ("sessions", "plans", "asked", "verified", "observed", "archived")
 
 #: A field this parser reads: a name it models, and whatever follows the colon.
 _KEY = re.compile(r"^([A-Za-z0-9_]+):\s*(.*)$")

package/harness/harness/model.py

@@ -3,7 +3,8 @@ import re
 from datetime import date
 from pathlib import Path
 
-from .tree import backlog_dir, BUCKETS, cli, DONE_TIER, PRIORITIES, RESERVED_MD
+from .tree import (archive_dir, backlog_dir, BUCKETS, cli, DONE_TIER,
+                   PRIORITIES, RESERVED_MD)
 from .frontmatter import as_list, parse_frontmatter, read_item, rewrite_file, title_of
 
 
@@ -364,9 +365,50 @@ def locate(root: Path, name: str, filed: bool = False):
             for t in v.all_tasks():
                 if t.name == name:
                     return t
+        for t in scan_archived(root):
+            if t.name == name:
+                return t
     return None
 
 
+def scan_archived(root: Path) -> list:
+    """Every ITEM taken off the board without being done — and without being deleted.
+
+    A task folder sitting directly under `versions/archive/`, beside the cuts that
+    left the board for the same reason. What tells the two apart is the marker file
+    a folder carries — a cut has `version.md`, an item has `task.md` — which is the
+    discriminator `scan` already reads the backlog with, so there is no second list
+    that could disagree with the tree.
+
+    **Deliberately not part of `scan`, and that is the whole of the design.** `scan`
+    answers what is MOVING, and an archived item is precisely what stopped. Keeping
+    it out means `list`, the README table, every lint, a release's count of what a
+    cut still owes and an epic's is-it-done all skip it by construction rather than
+    by each remembering to. The board had one state added to it before — `blocked` —
+    and four lints quietly excused a parked task from the rules its siblings answer
+    to, because a set spelled out in four places is wrong in three of them.
+
+    A READ opts back in through `locate(..., filed=True)`; a WRITE never sees it.
+    """
+    base = archive_dir(root)
+    if not base.is_dir():
+        return []
+    return [Task(p, status="archived", version=None)
+            for p in sorted(base.iterdir())
+            if p.is_dir() and (p / "task.md").is_file()]
+
+
+def archived_record(task) -> str:
+    """The most recent line of an item's archive history, or "".
+
+    One reader, because the record is append-only — archiving an item that was
+    restored and dropped again writes a second entry rather than replacing the
+    first — so "what happened to this" is always the LAST line and never the field.
+    """
+    entries = as_list(task.fm.get("archived"))
+    return entries[-1] if entries else ""
+
+
 def scan_filed(root: Path) -> list:
     """Every cut that has LEFT the board — both `versions/complete/` and
     `versions/archive/`.
@@ -395,6 +437,11 @@ def filed_home(root: Path, name: str) -> str:
     filed. The lookup that fails looks once more, in the cuts that left the board,
     so the refusal can name the release instead of denying the work ever existed.
     """
+    for t in scan_archived(root):
+        if t.name == name:
+            return (f" — it was archived: {archived_record(t)}. That is off the "
+                    f"board, not gone: read it with `{cli()} path {name}`, or put "
+                    f"it back with `{cli()} place {name} --version <v> --epic <e>`.")
     for v in scan_filed(root):
         for t in v.all_tasks():
             if t.name == name:

package/harness/harness/report.py

@@ -1,8 +1,9 @@
 import sys
 from pathlib import Path
 
-from .tree import find_work_root
-from .model import Task, _ordered, scan, scan_shipped
+from .tree import cli, find_work_root
+from .frontmatter import as_list
+from .model import Task, _ordered, scan, scan_archived, scan_shipped
 from .lint import lint_warnings
 from .generate import _regen_readme, settle_epic_tier
 from .align import (_align_acceptance, _align_agents, _align_citations,
@@ -25,6 +26,38 @@ def _task_line(t: Task) -> str:
     tail = ("  [" + " · ".join(extra) + "]") if extra else ""
     status = t.display_status()
     return f"{status:>11}  {t.priority}  {t.name} — {t.title}{tail}"
+def _list_archived(root) -> int:
+    """Work we stopped doing — what left the board without being done.
+
+    Newest first, because the question this answers is almost always about a
+    proposal that has just come back. Each item prints its whole history rather
+    than its last line: one that was archived, wanted again and archived a second
+    time is telling you something the final entry alone does not.
+    """
+    items = scan_archived(root)
+    if not items:
+        print("nothing is archived — no item has left the board unfinished.")
+        return 0
+    # Two passes rather than one reversed key, the same shape `scan_shipped` uses:
+    # reversing a compound key would stand the names on their head too.
+    items.sort(key=lambda t: t.name)
+    items.sort(key=lambda t: _archived_on(t), reverse=True)
+    print(f"ARCHIVED  ({len(items)}) — off the board, not gone.")
+    print(f"          `{cli()} path <name>` reads one · "
+          f"`{cli()} place <name> --version <v> --epic <e>` puts it back")
+    for t in items:
+        print(f"\n  {t.name} — {t.title}")
+        for entry in as_list(t.fm.get("archived")):
+            print(f"      {entry}")
+    return 0
+
+
+def _archived_on(t) -> str:
+    """The date an item FIRST left the board, for ordering. "" when it says none."""
+    entries = as_list(t.fm.get("archived"))
+    return entries[0][:10] if entries else ""
+
+
 def _say_staleness(root) -> None:
     """Print how far behind the origin this checkout is, or nothing when it is level.
 
@@ -47,6 +80,14 @@ def cmd_list(args) -> int:
         from harness.branches import cmd_at
         return cmd_at({"ref": args["branch"], **args})
     root = find_work_root()
+    # What was taken OFF the board is its own question and its own answer. The board
+    # deliberately does not show these — an item nobody means to do makes the queue
+    # overstate what is coming, which is the whole reason the state exists — so this
+    # is the door that does. Without it the only way to reach a decision is to
+    # already know its name, and a record nobody can browse stops the same proposal
+    # coming back only by luck.
+    if str(args.get("archived", "")).lower() in ("true", "1", "yes"):
+        return _list_archived(root)
     s = scan(root)
 
     # A read does not pull, so the board on screen can be an older world than the

package/harness/harness/task.py

@@ -158,9 +158,7 @@ def cmd_place(args) -> int:
     if version.released:
         die(f"version '{version_name}' is released — pick a planned version")
 
-    task = locate(root, name)
-    if not task:
-        die(missing(root, name, "task or epic"))
+    task, restored = _resolve_placeable(root, name)
     if task.version == version.name:
         die(f"'{name}' is already in version '{version_name}'")
     if task.status == "complete":
@@ -194,17 +192,54 @@ def cmd_place(args) -> int:
         moved[task.folder.resolve()] = dest.resolve()
         shutil.move(str(task.folder), str(dest))
 
-    md = dest / "task.md"
-    rewrite_file(
-        md,
-        lambda d: d.update({"updated": date.today().isoformat()}),
-    )
+    rewrite_file(dest / "task.md",
+                 _placed(restored, f"{version.name}/{epic.name}"))
     record_session(dest)
-    print(f"placed '{name}' -> {rel(dest, root)}")
+    if restored:
+        events.append(root, "restored", name, to=f"{version.name}/{epic.name}")
+    print(f"{'restored' if restored else 'placed'} '{name}' -> {rel(dest, root)}")
     _sync(root)
     return 0
 
 
+def _resolve_placeable(root, name: str):
+    """The item this `place` acts on, and whether it is coming back from the archive.
+
+    A live item resolves the ordinary way. One that was ARCHIVED resolves too, and
+    that is the difference between this state and a delete: work we stopped doing is
+    off the board, not gone, and wanting it again is a real thing that happens. It
+    is a person's deliberate act rather than a default, which is what keeps the
+    archive read as a set of decisions instead of a second queue.
+
+    Work that SHIPPED still does not resolve. `missing` says which of the two
+    happened, so the refusal names the release rather than denying the work existed.
+    """
+    task = locate(root, name)
+    if task:
+        return task, False
+    filed = locate(root, name, filed=True)
+    if filed and filed.status == "archived":
+        return filed, True
+    die(missing(root, name, "task or epic"))
+
+
+def _placed(restored: bool, home: str):
+    """The frontmatter edit a `place` makes, with the archive history APPENDED.
+
+    Never erased. A board that can forget it changed its mind cannot be asked why it
+    did — and the whole reason an item is kept rather than deleted is so the next
+    person proposing it can read what was decided and when. The same append-only
+    shape `answer` already uses on `asked:`.
+    """
+    def mutate(d):
+        d["updated"] = date.today().isoformat()
+        if restored:
+            d["archived"] = as_list(d.get("archived")) + [
+                f"restored {date.today().isoformat()}  to {home}"]
+
+    return mutate
+
+
 def _to_backlog(root, name: str, args) -> int:
     """Take work back OUT of a cut, into a backlog epic.
 
@@ -234,9 +269,7 @@ def _to_backlog(root, name: str, args) -> int:
             f"moving work there is `rehome <name> --version {epic.version} "
             f"--epic {epic_name}`")
 
-    task = locate(root, name)
-    if not task:
-        die(missing(root, name, "task or epic"))
+    task, restored = _resolve_placeable(root, name)
     if task.in_backlog:
         die(f"'{name}' is already in the backlog")
     if task.status == "complete":
@@ -260,12 +293,11 @@ def _to_backlog(root, name: str, args) -> int:
     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,
-        lambda d: d.update({"updated": date.today().isoformat()}),
-    )
-    print(f"took '{name}' out of the cut -> {rel(dest, root)}")
+    rewrite_file(dest / "task.md", _placed(restored, f"backlog/{epic.name}"))
+    if restored:
+        events.append(root, "restored", name, to=f"backlog/{epic.name}")
+    print(f"{'restored' if restored else 'took'} '{name}' "
+          f"{'' if restored else 'out of the cut '}-> {rel(dest, root)}")
     _sync(root)
     return 0
 

package/harness/harness/tree.py

@@ -46,7 +46,14 @@ PRIORITIES = ("P0", "P1", "P2")
 RESERVED_MD = ("README.md",)
 TASK_FM_ORDER = ("priority", "tier", "depends_on", "tags", "owner", "code", "covers",
                   "start", "end", "created", "updated", "sessions", "plans",
-                  "asked", "verified", "observed", "completed")
+                  "asked", "verified", "observed", "completed", "archived")
+# `archived:` is a LIST of dated entries, not the date a version carries under the
+# same key — an item can be archived, wanted again, and archived a second time, and
+# a board that overwrites the first line cannot be asked why it changed its mind.
+# It is the same append-only shape `asked:`, `sessions:` and `plans:` already use,
+# and for the same reason. It is a RECORD, never a status: whether an item is
+# archived is answered by where it sits, exactly as every other state is.
+
 # What a task's blast radius is, and therefore what an unattended run may do with
 # it alone. This is the axis the harness did not have: `code:` region COUNT
 # measured size (a three-region task is an epic in disguise), and size is not risk

package/harness/harness/version.py

@@ -1,14 +1,16 @@
 import re
 import shutil
 import subprocess
+import sys
 from datetime import date
 from pathlib import Path
 
 from . import ids
-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 .tree import (archive_dir, complete_dir, DONE_TIER, TASK_FM_ORDER,
+                   VERSION_FM_ORDER, cli, die, find_work_root, rel)
+from .frontmatter import as_list, rewrite_file
+from .model import (_is_epic_dir, archived_record, locate, locate_version, missing,
+                    record_session, scan)
 from .scaffold import _check_unused, _check_version_name, _scaffold_version
 from .epic import cmd_epic_release
 from .generate import _sync
@@ -256,11 +258,148 @@ def _home_for(version, root: Path) -> Path:
 
 
 def cmd_archive(args) -> int:
+    """Take work off the board — ONE ITEM, or a whole cut. The name decides which.
+
+    One verb over two tiers, dispatching on what the name IS, exactly as `place`
+    already does. The word always meant the right thing at the wrong size: it took
+    a CUT and refused unless every task in it was complete, so there was no way at
+    all to say *we decided not to do this* about a single item. The only thing that
+    did take one off the board was deleting its folder by hand — which the method
+    forbids, and which removes the evidence rather than the work.
+
+    Founder, 2026-09-10, naming the state the board did not have and objecting to
+    the word it had taken instead: _"there is a difference between archive and
+    completed — archive should be tasks that we dropped and no longer want them,
+    but don't want to delete just yet."_ That reading is the natural one, and the
+    fix is to make the sentence true rather than to invent a second vocabulary.
+
+    Measured across four repos on 2026-09-12, counting NAMES rather than files
+    because a folder moving between buckets is a rename: 62 items had ever left
+    three of those boards against 1,290 created. Removal was not merely missing —
+    its absence is why a board only grows, since the cheapest legal action was
+    always to leave the item where it was.
+    """
     root = find_work_root()
     name = args["name"]
+    # An ITEM first, then a CUT. Names are globally unique across all three tiers,
+    # so this cannot be ambiguous — and an item is what a caller reaches for far
+    # more often, since a cut leaves the board once and its work leaves item by item.
+    if locate(root, name):
+        return _archive_task(root, name, args)
+    if locate_version(root, name):
+        return _archive_version(root, name, args)
+    # Saying "no such name" about something this very command filed is the least
+    # useful true thing available, so the one case it can answer precisely, it does.
+    already = locate(root, name, filed=True)
+    if already and already.status == "archived":
+        die(f"'{name}' is already archived — {archived_record(already)}. It is off "
+            f"the board, not gone. Put it back with `{cli()} place {name} --version "
+            f"<v> --epic <e>` if it is wanted again.")
+    die(missing(root, name, "task or version"))
+
+
+def _archive_task(root, name: str, args) -> int:
+    """Take ONE item off the board without finishing it and without deleting it.
+
+    **It strips NOTHING**, which is the opposite of what archiving a cut does and is
+    the point of the difference. 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. An archived item with no reasoning is one somebody re-proposes next
+    month, which is the failure this state exists to end.
+
+    A marked, reasoned state rather than a delete, and there is outside evidence for
+    that rather than only taste: Anthropic's harness guidance argues the other way
+    for a good reason, refusing to let an agent remove tests because it could shrink
+    the spec it is being measured against. That failure is real and this must not
+    create it — so nothing disappears, and what was decided against stays citable.
+    """
+    why = (args.get("why") or "").strip()
+    # A bare `--why` parses to "true" (see parse_argv), which is a flag somebody
+    # typed rather than a reason they gave.
+    if not why or why == "true":
+        die(f"archiving an item needs --why: a decision NOT to do something is only "
+            f"worth keeping if it says what the decision was. Without it this is a "
+            f"delete that happens to leave a folder behind.\n"
+            f"       e.g. {cli()} archive {name} --why \"duplicate of <other item>\"")
+
+    task = locate(root, name)
+    if task.status == "complete":
+        die(f"'{name}' is complete — it shipped in '{task.version}' and stays "
+            f"there. What a release delivered is a matter of record, and a record "
+            f"that can be edited afterwards cannot answer what any release "
+            f"contained.")
+
+    # Work something else is WAITING ON. Archiving it leaves every dependent waiting
+    # on a name nothing will ever complete, and the unattended selector skips those
+    # for good saying "depends on incomplete" — which reads as a queue that has
+    # stalled rather than as this. Refused rather than warned, because the repair is
+    # in the dependents and doing it afterwards means finding them first.
+    s = scan(root)
+    dependents = sorted({t.name for v in s["versions"] for t in v.all_tasks()
+                         if name in t.depends_on and t.status != "complete"}
+                        | {t.name for t in s["backlog"] if name in t.depends_on})
+    if dependents:
+        die(f"'{name}' cannot be archived — {len(dependents)} item(s) still depend "
+            f"on it: {', '.join(dependents)}. Archiving it would leave them waiting "
+            f"on work nothing will ever finish. Drop the dependency, or archive "
+            f"those first.")
+
+    # Somebody may be on it. Both notes WARN rather than refuse, exactly as `move`
+    # and the take-it-out-of-a-cut door already do: a harness that argues about a
+    # call the person has made gets worked around.
+    from .shift import read_claim
+    from . import peers
+    held = read_claim(task.folder)
+    if held and held.get("instance") != peers.me():
+        print(f"note: '{name}' is held by another session — {peers.of_claim(held)}",
+              file=sys.stderr)
+    if task.status == "in-progress":
+        print(f"note: '{name}' is in progress — somebody may be working it right "
+              f"now, and this takes it out from under them.", file=sys.stderr)
+
+    # WHERE it was proposed, carried in the record rather than in the path. An
+    # archived item leaves the cut entirely — that is what makes a release behind
+    # one arithmetically correct without a single count learning to skip it — so the
+    # tree can no longer say what it was part of and the entry has to.
+    home = "/".join(x for x in (task.version or "backlog", task.epic) if x)
+
+    dest = archive_dir(root) / name
+    if dest.exists():
+        die(f"{rel(dest, root)} already exists")
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    with links.repairing(root.parent, indent="        ") as moved:
+        moved[task.folder.resolve()] = dest.resolve()
+        shutil.move(str(task.folder), str(dest))
+
+    entry = f"{date.today().isoformat()}  {why}  [from {home}]"
+
+    def mutate(d):
+        d["archived"] = as_list(d.get("archived")) + [entry]
+        d["updated"] = date.today().isoformat()
+
+    rewrite_file(dest / "task.md", mutate, TASK_FM_ORDER)
+    record_session(dest)
+    events.append(root, "archived", name, why=why, **{"from": home})
+    print(f"archived '{name}' — off the board, not gone")
+    print(f"        why: {why}")
+    print(f"        it was in {home}; `{cli()} path {name}` still reads it, and "
+          f"`{cli()} place {name} --version <v> --epic <e>` puts it back")
+    _sync(root)
+    return 0
+
+
+def _archive_version(root, name: str, args) -> int:
+    """File a whole CUT off the board — the tier this verb has always served.
+
+    Which of the two homes it goes to is read from the tree, never passed in: a cut
+    carrying `released:` SHIPPED and is filed under `versions/complete/`, one
+    without it left for the other reason and goes to `versions/archive/`. See
+    `_home_for`.
+    """
     dry = str(args.get("dry-run", "")).lower() in ("true", "1", "yes")
     version = locate_version(root, name)
-    if not version:
+    if not version:                                   # pragma: no cover — dispatched
         die(f"no version named '{name}'")
     # A cut whose work all moved elsewhere has nothing left to deliver and no
     # outcome it honestly met, so releasing it would be a lie — and until now

package/harness/presets/appchy/PRESET.md

@@ -313,12 +313,44 @@ files are deleted. **Read a dissolving `epic.md` in full first** — a thin epic
 fully-planned, deliberately-deferred goal hides.
 
 A version's status is derived: **planned** until tasks start, **current** while any is in-progress,
-**released** once `jarvis work release` stamps it. Release **flattens the done tier** and **stamps
-each `epic.md` as history, keeping it**, then `jarvis work archive` strips each task to its `task.md`
-and moves the version to `work/archive/versions/<v>/`.
+**ready** once every task is complete and nobody has closed it, **released** once `jarvis work release`
+stamps it. Release **flattens the done tier** and **stamps each `epic.md` as history, keeping it**,
+then `jarvis work archive <v>` strips each task to its `task.md` and files the cut off the board.
 
-**Archived is off the board, not gone.** `list`, the README table and every lint see only `versions/`.
-`jarvis work path <v>` and `jarvis work where <id>` still resolve into the archive.
+### Complete, released, archived — three words, and they are not synonyms
+
+They get used interchangeably and they mean different things at different tiers. Nobody should have to
+read the source to learn which:
+
+| Word | What it is | Tier | Where it ends up |
+|---|---|---|---|
+| **complete** | this piece of work is FINISHED | one item | `complete/` inside its epic |
+| **released** | the cut shipped and met its `outcome:` | a whole cut | stamped `released:`, still in `versions/` |
+| **archived** | taken OFF the board — the two cases below | either | `versions/archive/` |
+
+**Archived means one of two things, and which one is read off the tree rather than chosen.** A cut
+that SHIPPED is filed under `versions/complete/<cut>/`; a cut leaving the board without shipping —
+its work moved elsewhere, so there is no outcome it could honestly claim — goes to
+`versions/archive/<cut>/`. Asking the caller to restate which is how the folder and the `released:`
+stamp end up disagreeing.
+
+**An ITEM is archived when we decided not to do it** — `jarvis work archive <name> --why "…"`, a
+person's command. It lands in `versions/archive/<item>/` beside those cuts, it strips NOTHING, and the
+reason is required: a decision not to do something is only worth keeping if it says what the decision
+was. Founder, 2026-09-10, naming the state the board did not have: *"there is a difference between
+archive and completed — archive should be tasks that we dropped and no longer want them, but don't
+want to delete just yet."*
+
+**Archived is off the board, not gone.** `list`, the README table, every lint, a release's count of
+what a cut still owes and an epic's is-it-done all stop seeing it. `jarvis work path <name>` and
+`jarvis work where <id>` still resolve into the archive, `jarvis work list --archived` browses what
+left, and `jarvis work place <name> --version <v> --epic <e>` puts an item back — putting one back is
+a person's deliberate act, which is what keeps the archive a set of decisions rather than a second
+queue. **Deleting a task folder by hand is not a third way off the board**; it is the thing the verb
+exists to remove, and it is the one write that destroys the evidence rather than the work.
+
+A COMPLETED item is the one thing that is fixed: it shipped in its cut and cannot be moved out of it
+or archived, because a release whose contents can be edited afterwards cannot answer what it delivered.
 
 **A finished epic goes off the board too**: an epic whose every task is complete drops into
 `<v>/complete/` and prints as one `DONE` line. It is **derived and materialized, never declared** —
@@ -338,6 +370,7 @@ is a brief and nothing else.
 | in-progress | `task.md` — the design is in `epic.md` §Plan and is not restated here. (`plan.md` **only** for a call the epic plan left unsettled; `handoff.md` **only** when handing to a new conversation) | handoff ≤80 |
 | complete (version unreleased) | same; if a handoff exists, stamp it DONE | — |
 | archived (version released) | `task.md` only | — |
+| archived (the ITEM, we decided not to do it) | everything it had — archiving an item strips NOTHING, because the thinking that reached the decision is the whole of what there is to keep | — |
 
 **A task is ONE goal, phased internally — never shredded.** If it spans **3+ `code` regions** the lint
 says so, and it is right: that is an epic wearing a task costume. Split it by *goal*, not by layer.
@@ -376,8 +409,10 @@ work/
 │       ├── design.md · architecture.md             (conditional)
 │       ├── <epic>/epic.md + {queue,in-progress,complete}/<task>/
 │       └── complete/<epic>/                        every task done — off the board, still in the cut
-├── backlog/<epic>/<task>/   epics planned but not yet in a cut — NO buckets here
-├── archive/versions/<v>/    released + archived cuts
+├── versions/backlog/<epic>/<task>/   epics planned but not yet in a cut — NO buckets here
+├── versions/complete/<cut>/          a cut that SHIPPED
+├── versions/archive/<cut>/           a cut taken off the board unreleased
+├── versions/archive/<item>/          ONE item we decided not to do (`--why` is required)
 ├── research/<dir>/      shared research (each has a 00-report.md summary)
 ├── product/README.md    what this domain owns + its rules; behaviour specs sit beside it
 │   ├── <feature>.md     what the app does — bridged to versions/ via task.md's `owner:`
@@ -439,7 +474,10 @@ the only way forward has hit a real gap: **park a question, do not shell out.**
 | Place work in a cut | `jarvis work place <epic> --version <v>` · `jarvis work place <task> --version <v> --epic <e>` | a person's |
 | Take it back out | `jarvis work place <name> --backlog --epic <e>` | a person's |
 | Carry an epic forward | `jarvis work epic-new <name> --version <v> --continues <earlier epic>` | a person's |
-| Release / archive | `jarvis work release <v>` · `jarvis work archive <v>` | a person's |
+| Release / archive a cut | `jarvis work release <v>` · `jarvis work archive <v>` | a person's |
+| Stop doing an item | `jarvis work archive <name> --why "…"` — off the board, not deleted | a person's |
+| See what we stopped doing | `jarvis work list --archived` | either |
+| Want it again | `jarvis work place <name> --version <v> --epic <e>` | a person's |
 | Answer a parked question | `jarvis work needs` → `jarvis work answer <task> --choose "…"` | a person's |
 | Read the shift | `jarvis work status` · `jarvis work digest --since YYYY-MM-DD` | a person's |
 | Config | `jarvis work config` | a person's |