@appchy/jarvis 0.1.37 → 0.1.39

package/harness/harness/tree.py

@@ -0,0 +1,258 @@
+import os
+import sys
+from pathlib import Path
+
+
+# This module sits at <payload>/harness/tree.py, and the payload is the directory
+# that ships inside the CLI. The anchor is derived from that ONE fact and named,
+# because the split from a single work.py to this package moved every relative path
+# up a level and broke `assets_dir()` silently — the scaffold templates simply
+# stopped being found.
+PAYLOAD_DIR = Path(__file__).resolve().parents[1]
+
+
+BUCKETS = ("queue", "in-progress", "blocked", "complete")
+# `blocked/` is where a task waits on a HUMAN, and it exists because the harness
+# now runs unattended. Under a person the third state was unnecessary — a question
+# was asked and answered in the same conversation. With nobody in the chair the
+# same question has exactly two bad answers: block the run forever, or decide it
+# silently and leave no trace that a call the founder owned was made without them.
+#
+# So a question is an artifact. `ask` writes it, moves the task here and EXITS 0 —
+# the instance takes other work rather than stalling. `needs` lists every open one,
+# `answer` unblocks. Blocked is a bucket rather than a frontmatter flag for the
+# same reason status is: two writers for one fact is how they drift apart.
+BLOCKED = "blocked"
+# Buckets holding work that is still MOVING — everything a lint should hold to the
+# live rules. Named once because it was spelled out as a literal in four lints, and
+# adding `blocked` to `BUCKETS` would otherwise have left all four quietly excusing
+# a parked task from the rules its siblings answer to. A set that has to be updated
+# in four places is a set that is wrong in three of them.
+ACTIVE = ("queue", "in-progress", BLOCKED)
+# Where a version parks an epic whose every task is done. It is deliberately the
+# same word as the task bucket — an epic and a task mean the same thing by it —
+# and it lives at the version's top level, so a finished goal drops out of the
+# board without leaving the cut. Derived, never declared: `_settle_epic_tier`
+# puts an epic here when its tasks say so and takes it straight back out when one
+# reopens, exactly as a task's own status is the bucket it sits in.
+DONE_TIER = "complete"
+PRIORITIES = ("P0", "P1", "P2")
+# A spec is a FILE, never a folder holding one file: `product/<feature>.md` and
+# `architecture/<system>.md`. So a domain directory holds its specs alongside the
+# ONE doc that describes the domain itself, and "every .md here is a spec" holds
+# except for that one. It is `README.md` — the name every reader, tool and folder
+# view already knows — and it is where a generated index lands too, in a marked
+# block, so a domain never grows a second landing doc to disagree with the first.
+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")
+# 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
+# — renaming a variable across three regions is safe, rewriting auth in one is not.
+#
+# Deliberately four levels, not a score. A number invites arithmetic; a level
+# invites a decision.
+TIERS = (0, 1, 2, 3)
+TIER_MEANING = {
+    0: "reversible and local — a typo, a comment, a test name",
+    1: "ordinary change behind existing tests",
+    2: "new behaviour, a new seam, or a migration that is reversible",
+    3: "irreversible, or it touches money, secrets, personal data or the law",
+}
+# Owners that FLOOR a task at tier 3 whatever it was given. Derived from the
+# domain that owns the work, because that is a fact the tree already holds — and
+# a derived floor cannot be forgotten the way a hand-set field can.
+TIER3_OWNERS = ("security", "legal", "commercial")
+# Above this an unattended run does not act alone: it asks. The default is 2, so a
+# scheduled shift does ordinary work and stops at the irreversible. `autonomy.ceiling`
+# in config moves it; 3 means "decide everything", which is a repo's call to make
+# explicitly and never the shipped default.
+DEFAULT_AUTONOMY_CEILING = 2
+# Area tags a task may carry — `tags:` groups the NOW board by capability or
+# market without a per-project board split. BOUND FROM `tags.allowed`; empty
+# means no vocabulary is configured, and then any tag is accepted.
+#
+# This was a shipped tuple carrying one consumer's product names, which is the
+# worst shape a default can take: every other repo inherited a vocabulary that
+# described none of its work AND had its own tags refused against it. An area
+# vocabulary is not derivable the way `code:` is (see `code_vocabulary()`), so it
+# is stated in config or not at all.
+TASK_TAGS_OK = ()
+# The code-locality vocabulary a task's `code:` field draws from is DERIVED —
+# see `code_vocabulary()`. It is the union of the `code:` regions the systems in
+# `work/architecture/*.md` declare, so a region exists because a system
+# owns it. There is deliberately no hand-curated tuple here: this list and the
+# systems could disagree, and a fact that can be derived is never written.
+VERSION_FM_ORDER = ("created", "updated", "order", "outcome", "start", "end",
+                     "target", "released", "archived")
+EPIC_FM_ORDER = ("created", "updated", "covers", "continues")
+# A version is a RELEASE, so it cannot open while an earlier one is still open,
+# and it must state what a user can newly DO when it ships. An EPIC is the
+# temporary folder inside it that holds its tasks and owns the plan-it-together
+# doc; it is removed at release, because how the work was planned stops being
+# true the moment it ships. A TASK is ONE goal, end-to-end, internally phased.
+#
+# The measured shape of the failure, not taste: at the reshape (2026-08-01) 44
+# of 106 tasks spanned ≥3 code regions, and a task touching three systems is a
+# version wearing a task costume — which is how "we missed it, now we refactor"
+# keeps happening.
+#
+# A `TASK_LINE_BUDGET` of 30 sat beside this and is GONE (founder call,
+# 2026-08-02). Length was never the failure it was blamed for: a brief is read
+# by a session starting cold, and the findings, dead ends and warnings that make
+# that cheap are exactly what a line budget deletes. What actually goes wrong —
+# a brief quietly becoming a competing plan — is caught by the artifact lint,
+# which looks for the FILES, not the size.
+TASK_REGION_CAP = 3
+# The other end of the same rule, added 2026-08-02 (founder call), and it names a
+# measured failure too: the backlog had reached 14 epics of which NINE held two
+# tasks or fewer — one of them zero — so the board read as a pile of topics rather
+# than a set of goals, and "plan it once for the whole goal" had nothing to plan.
+# An epic is the unit you think about TOGETHER; at one or two tasks there is no
+# together, and its epic.md degenerates into a second copy of the task brief.
+#
+# Below the floor, the FIRST move is to fold the tasks into an existing epic that
+# already makes sense — not to invent a wrapper around them. A new epic is right
+# only when more work is genuinely anticipated (its Plan can name the slices it
+# has not cut yet), which is why this warns rather than blocks: an epic that is
+# planned deep and cut shallow is legitimate, and says so in its own §Plan.
+EPIC_TASK_FLOOR = 3
+# A feature's lifecycle, product-language not engineering-status.
+PRODUCT_STATES = ("idea", "defined", "building", "shipped", "retired")
+BACKLOG_START = "<!-- BACKLOG:START -->"
+BACKLOG_END = "<!-- BACKLOG:END -->"
+# The generated system index lives INSIDE architecture/README.md, which is
+# also the domain's hand-written landing doc — one file per folder.
+SYSTEMS_START = "<!-- SYSTEMS:START -->"
+SYSTEMS_END = "<!-- SYSTEMS:END -->"
+# Files a task folder may legitimately carry (top-level). Anything else — in
+# particular suffix variants like plan-foo.md / state.md / research-bar.md — is
+# flagged by the lint. `research/` is the one allowed subdirectory. Working
+# checklists (/code-review, /simplify findings) are NOT task files — they live
+# in native TodoWrite.
+TASK_FILES_OK = {
+    "task.md", "plan.md", "handoff.md", "research.md", "ui.md",
+}
+HANDOFF_CAP = 80
+def cli() -> str:
+    """How to name this tool back to the user.
+
+    One name, because there is now one way in: the payload ships inside the CLI and
+    is reached through it. Nobody can run `work.py` without knowing where the
+    payload landed, and that is the CLI's business rather than the caller's — so a
+    message naming the script was telling somebody to run a path they cannot
+    resolve, on the turn they hit an error.
+    """
+    return "jarvis work"
+
+
+def find_work_root() -> Path:
+    """Locate the work/ directory. FAILS CLOSED — it never guesses a path.
+
+    Precedence: `WORK_DIR` (the tree directly) → `CLAUDE_PROJECT_DIR` → a walk up
+    from the cwd for a `work/` holding `versions/` or `backlog/` (so the payload's
+    own directory is never mistaken for it).
+
+    **There is no script-relative fallback, and removing it is a bug fix, not a
+    tightening.** It used to resolve `work/` beside the payload's OWN modules, so a
+    command run in a repo with no work tree wrote into the payload. Measured:
+    `version-new` in a fresh repo printed "<payload>/work/README.md not found",
+    created `<payload>/work/versions/v1/`, and exited 1. The consumer got nothing,
+    the payload got a version folder, and the exit code said failure while a
+    mutation had already landed.
+
+    Inside an installed package that fallback cannot be right by construction: the
+    payload is read-only shipped code and the tree belongs to the consumer. So an
+    unresolvable root exits non-zero naming what was looked for and what to run,
+    which is the one answer that cannot corrupt anything.
+    """
+    root, tried, cur = locate_work_root()
+    if root:
+        return root
+    die("no work/ tree found — looked for "
+        + (", ".join(tried) + ", and " if tried else "")
+        + f"a work/ holding versions/ or backlog/ in {cur} or any parent.\n"
+        + f"       Run `{cli()} init` to create one, or pass --project <dir>.")
+def locate_work_root() -> tuple:
+    """The same search, reporting rather than exiting: `(root|None, tried, cwd)`.
+
+    Separate from `find_work_root` so that a caller which must NOT die on a missing
+    tree — `init`, which is about to create one, and the git seam, which has nothing
+    to commit without one — asks the same question and gets the same answer. Two
+    searches would be two answers about which repo this is.
+    """
+    env = os.environ.get("WORK_DIR")
+    cur = Path.cwd().resolve()
+    if env:
+        return Path(env).resolve(), [], cur
+    tried = []
+    project = os.environ.get("CLAUDE_PROJECT_DIR")
+    if project:
+        cand = Path(project).resolve() / "work"
+        if cand.is_dir():
+            return cand, tried, cur
+        tried.append(str(cand))
+    for d in (cur, *cur.parents):
+        cand = d / "work"
+        if cand.is_dir() and any((cand / sub).is_dir()
+                                 for sub in ("versions", "backlog")):
+            return cand, tried, cur
+    return None, tried, cur
+def assets_dir() -> Path:
+    return PAYLOAD_DIR / "assets"
+def rel(p: Path, root: Path) -> str:
+    try:
+        return str(p.relative_to(root.parent))
+    except ValueError:
+        return str(p)
+def die(msg: str):
+    print(f"error: {msg}", file=sys.stderr)
+    sys.exit(1)
+#: Build output and vendored code — the non-dot generated directories. A repo adds
+#: its own through config rather than editing this.
+#: What the harness skips before any repo says anything. Kept apart from the live
+#: value because `apply` rebuilds that from here on every call: unioning into the
+#: live set instead made each config inherit the last one's additions, with nothing
+#: anywhere able to undo them.
+SHIPPED_SKIP_DIRS = {"node_modules", "dist", "build", "out", "coverage", "__out__",
+                     "__pycache__", "vendor"}
+
+#: The set in force — the shipped names plus whatever this repo's config adds.
+SKIP_DIRS = set(SHIPPED_SKIP_DIRS)
+
+#: A dot-directory that IS content, not cache. Everything else beginning with `.`
+#: is skipped by rule, which is what makes this generic: `.next`, `.turbo`, `.git`,
+#: `.venv`, `.work`, `.pytest_cache` and every tool cache a repo will invent are
+#: covered without naming one of them.
+#:
+#: Naming caches individually is not a style preference — it is a correctness bug
+#: with a measured instance. A graph engine's own snapshot directory held 1,521
+#: generated files echoing real source, and scanning it minted a phantom test
+#: binding for a criterion no test actually claimed: the report said a promise was
+#: proven because a cache quoted the id. A skip list that must be told each cache's
+#: name is a skip list that is wrong until someone notices.
+KEEP_DOT_DIRS = {".claude"}
+
+
+def _skipped(p: Path, repo: Path) -> bool:
+    """Whether a path lies inside a generated or vendored directory."""
+    try:
+        parts = p.relative_to(repo).parts
+    except ValueError:
+        parts = p.parts
+    return any(part in SKIP_DIRS
+               or (part.startswith(".") and part not in KEEP_DOT_DIRS)
+               for part in parts[:-1] or parts)
+TEXT_SUFFIXES = {".md", ".ts", ".tsx", ".py", ".mjs", ".js", ".json", ".sql",
+                 ".yml", ".yaml"}
+def _repo_files(repo: Path) -> list:
+    out = []
+    for p in repo.rglob("*"):
+        if p.suffix not in TEXT_SUFFIXES or not p.is_file():
+            continue
+        if _skipped(p, repo):
+            continue
+        out.append(p)
+    return out

package/harness/harness/version.py

@@ -0,0 +1,305 @@
+import re
+import shutil
+import subprocess
+from datetime import date
+from pathlib import Path
+
+from . import ids
+from .tree import 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
+from .epic import cmd_epic_release
+from .generate import _sync
+from . import events
+
+
+def cmd_version_new(args) -> int:
+    """Scaffold a version — behind ONE refusal, because a version is a RELEASE.
+
+    It must state a user-visible `outcome:`: if you cannot say what someone can
+    newly DO when it ships, it is not a release, and the work belongs in an epic
+    until it is. That refusal stays, and it is the one that makes a version mean
+    something.
+
+    **The second refusal is gone (founder, 2026-09-03).** A version used to be
+    unable to open while an earlier one was unreleased, aimed at how "nothing ever
+    closes and the list only grows" happened — measured at the reshape as 4
+    complete-but-unreleased versions, one of them 29 tasks and already in
+    production. But that is a failure to RELEASE, and it was guarded by refusing to
+    CREATE, which turns out to cost the thing it was meant to protect: with one cut
+    the only container available, everything that did not fit still had nowhere to
+    go, so it stayed. Measured here the same day: 155 tasks in one version, 62 of
+    them never started, and no way to lay out what comes next.
+
+    So the ladder is allowed and the sequencing is the person's: _"i might want to
+    work in parallel, just need it way more organized … it's my decision, not
+    something to enforce yet."_ What replaces the refusal is a NOTICE — the same
+    move the board already makes when somebody else holds an item, for the same
+    reason: a harness that argues gets worked around, and a refusal people routinely
+    override teaches them to override without reading."""
+    root = find_work_root()
+    name = args["name"]
+    _check_version_name(name)
+    _check_unused(root, name)
+
+    outcome = (args.get("outcome") or "").strip()
+    if not outcome or outcome == "true":
+        die("--outcome is required: state in ONE line what a user can newly DO "
+            "when this ships (e.g. --outcome 'a teacher can publish a lesson "
+            "under their own name'). A version is a release, not a container.")
+
+    open_versions = [v for v in scan(root)["versions"] if not v.released]
+
+    title = args.get("title") or name
+    target = (args.get("target") or "").strip()
+    if target and not re.match(r"^\d{4}-\d{2}-\d{2}$", target):
+        die("--target must be YYYY-MM-DD")
+
+    start = (args.get("start") or "").strip()
+    end = (args.get("end") or "").strip()
+    if start and not re.match(r"^\d{4}-\d{2}-\d{2}$", start):
+        die("--start must be YYYY-MM-DD")
+    if end and not re.match(r"^\d{4}-\d{2}-\d{2}$", end):
+        die("--end must be YYYY-MM-DD")
+    if start and end and start > end:
+        die(f"--start ({start}) must be <= --end ({end})")
+
+    # `order:` — explicit --order wins; a `NN-slug` name prefix must AGREE with
+    # an explicit --order (else die, catching a stale/typo'd flag); with no
+    # --order, a name prefix is the order (mirrors `_version_order`'s read-side
+    # derivation so a fresh scaffold is never silently un-ordered).
+    order_arg = (args.get("order") or "").strip()
+    if order_arg and not re.match(r"^\d+$", order_arg):
+        die("--order must be a non-negative integer")
+    order = order_arg
+    prefix_m = re.match(r"^(\d+)-", name)
+    if prefix_m:
+        prefix = prefix_m.group(1)
+        if order and int(order) != int(prefix):
+            die(f"--order {order} disagrees with the name's numeric prefix "
+                f"'{prefix}-' in '{name}' — drop --order or make them agree")
+        if not order:
+            order = prefix
+
+    with_design = str(args.get("design", "")).lower() in ("true", "1", "yes")
+    with_architecture = str(args.get("architecture", "")).lower() in ("true", "1", "yes")
+    folder = root / "versions" / name
+    if folder.exists():
+        die(f"{rel(folder, root)} already exists")
+    _scaffold_version(folder, title, target, with_design, with_architecture,
+                       order=order, start=start, end=end, outcome=outcome)
+    print(f"created {rel(folder / 'version.md', root)}")
+    # What the old refusal used to prevent, said instead of enforced. Working two
+    # cuts at once is a real choice with a real cost, and it is the person's to
+    # make — but making it by accident, because nothing mentioned the other cut, is
+    # not a choice at all.
+    if open_versions:
+        names = ", ".join(v.name for v in open_versions)
+        print(f"        note: {len(open_versions)} other version(s) not yet "
+              f"released ({names}). Nothing stops you working both — but a cut "
+              f"only closes when every task in it is complete.")
+    if with_design:
+        print(f"        {rel(folder / 'design.md', root)}  (paste at claude.ai/design)")
+    if with_architecture:
+        print(f"        {rel(folder / 'architecture.md', root)}  (the cross-task technical brief)")
+    _sync(root)
+    return 0
+def _flatten_done_tier(version) -> 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
+    cut ships nothing in it is moving, so the distinction stops meaning anything and
+    would only add a level for `path`/`where` to walk through forever.
+
+    **EPICS ONLY.** `<v>/complete/` names two different things, told apart by the
+    marker file: a completed *epic*, and — in a flat version that never adopted the
+    tier — the completed-*task* bucket. Moving every subdir treated a grandfathered
+    version's finished tasks as epics and lifted them out of their bucket, and a
+    task's bucket IS its status, so releasing a flat cut silently un-completed
+    everything in it. `_is_epic_dir` is the same predicate the model reads both
+    tiers with, so there is one answer to "is this an epic" and not two.
+    """
+    tier = version.folder / DONE_TIER
+    if not tier.is_dir():
+        return
+    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))
+    if not any(tier.iterdir()):
+        tier.rmdir()
+
+
+def cmd_release(args) -> int:
+    root = find_work_root()
+    name = args["name"]
+    version = locate_version(root, name)
+    if not version:
+        die(f"no version named '{name}'")
+    if version.released:
+        die(f"version '{name}' is already released ({version.released})")
+    if not version.all_tasks():
+        die(f"version '{name}' has no tasks — add at least one before releasing")
+    incomplete = [t for t in version.all_tasks() if t.status != "complete"]
+    if incomplete:
+        die(f"version '{name}' has {len(incomplete)} task(s) not complete — "
+            f"finish or move them first")
+    if not version.outcome:
+        die(f"version '{name}' states no `outcome:` — a release says what a user "
+            f"can newly DO. Add one line to {rel(version.md, root)} first.")
+
+    # FLATTEN THE DONE TIER FIRST, while the version is still unreleased and
+    # `settle_epic_tier` will still act on it. At release every epic is complete by
+    # 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)
+    # THE FLATTEN MOVED FOLDERS, so every path hanging off `version` is now stale.
+    # Re-locate before anything else touches the tree.
+    #
+    # Skipping this is what broke `release` on its ONLY normal path: a version can
+    # be released only when every task is complete, which is exactly the condition
+    # that parks each epic in `<v>/complete/` — so every well-formed release hit it.
+    # `cmd_epic_release` walked the pre-move model and raised FileNotFoundError on
+    # `<v>/complete/<epic>/epic.md`, *after* `released:` had already been stamped:
+    # a traceback, a half-applied release, and `epic.md` — the one file release
+    # exists to remove — left in place for `align` to report.
+    version = locate_version(root, name)
+    if not version:                                   # pragma: no cover — defensive
+        die(f"version '{name}' vanished mid-release — the tree moved underneath it")
+
+    md = version.md
+    rewrite_file(
+        md,
+        lambda d: d.update({
+            "released": date.today().isoformat(),
+            "updated": date.today().isoformat(),
+        }),
+        VERSION_FM_ORDER,
+    )
+    events.append(root, "released", name, outcome=version.outcome)
+    print(f"released '{name}' ({date.today().isoformat()})")
+    print(f"        {version.outcome}")
+    # An epic is temporary BY DEFINITION — it is the plan-it-together doc, and
+    # how the work was planned stops being true once it ships.
+    cmd_epic_release(root, version)
+    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)")
+    _sync(root)
+    return 0
+def _short_sha() -> str:
+    try:
+        out = subprocess.run(
+            ["git", "rev-parse", "--short", "HEAD"],
+            capture_output=True, text=True, timeout=5,
+        )
+        return out.stdout.strip() if out.returncode == 0 else ""
+    except Exception:
+        return ""
+
+
+def _contained(p: Path, root: Path) -> Path:
+    """`p`, proven to sit inside `root` — or a hard stop.
+
+    `archive` is the only command that deletes recursively, and centralising the
+    harness means its blast radius becomes *every installed repo* rather than one.
+    So every path it touches is checked against the tree root before anything is
+    removed, and the check is on the RESOLVED path: `resolve()` collapses `..` and
+    follows symlinks, so a task folder that is a symlink out of the tree, or a name
+    carrying traversal, both land outside `root` and stop here.
+
+    `strict=False` on purpose — a path being deleted may already be gone, and that
+    is not a containment failure.
+    """
+    rp, rr = p.resolve(strict=False), root.resolve(strict=False)
+    if rp != rr and rr not in rp.parents:
+        die(f"refusing to touch {rp} — it resolves outside the work tree at {rr}. "
+            f"A symlink or a '..' in a folder name will do this.")
+    return rp
+
+
+def cmd_archive(args) -> int:
+    root = find_work_root()
+    name = args["name"]
+    dry = str(args.get("dry-run", "")).lower() in ("true", "1", "yes")
+    version = locate_version(root, name)
+    if not version:
+        die(f"no version named '{name}'")
+    if not version.released:
+        die(f"version '{name}' is not released — release it before archiving")
+    if version.fm.get("archived"):
+        die(f"version '{name}' is already archived ({version.fm['archived']})")
+
+    if dry:
+        print(f"DRY RUN — nothing will be written. `archive {name}` would:")
+
+    removed = 0
+    for t in version.all_tasks():
+        _contained(t.folder, root)
+        for p in sorted(t.folder.iterdir()):
+            if p.name == "task.md":
+                continue
+            _contained(p, root)
+            if dry:
+                print(f"  strip   {rel(p, root)}")
+            elif p.is_dir():
+                shutil.rmtree(p)
+            else:
+                p.unlink()
+            removed += 1
+
+    # Version-level scratch beyond the mandatory spine goes too.
+    keep = {"version.md", "stories.md", "design.md", "architecture.md"}
+    for p in sorted(version.folder.iterdir()):
+        if p.is_file() and p.name not in keep:
+            _contained(p, root)
+            if dry:
+                print(f"  strip   {rel(p, root)}")
+            else:
+                print(f"        removed version scratch {p.name}")
+                p.unlink()
+            removed += 1
+
+    if dry:
+        dest = root / "archive" / "versions" / 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. "
+              f"Re-run without --dry-run to do it.")
+        return 0
+
+    sha = _short_sha()
+    note = f"{date.today().isoformat()}"
+    md = version.md
+    rewrite_file(
+        md,
+        lambda d: d.update({
+            "archived": note,
+            "updated": date.today().isoformat(),
+        }),
+        VERSION_FM_ORDER,
+    )
+
+    # …and OFF the board. An archived version is a permanent record, not live
+    # work, and leaving it in `versions/` is why `jarvis work list` had to be read
+    # 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(root / "archive" / "versions" / name, root)
+    if dest.exists():
+        die(f"{rel(dest, root)} already exists")
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    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)
+    print(f"archived '{name}': stripped {removed} file(s) to task.md, "
+          f"moved to {rel(dest, root)}{where}")
+    _sync(root)
+    return 0