@appchy/jarvis 0.1.36 → 0.1.39

package/harness/harness/task.py

@@ -0,0 +1,507 @@
+import re
+import shutil
+import sys
+from datetime import date
+
+from . import peers, tree
+# `TASK_TAGS_OK` is deliberately NOT imported by name: `config.apply` binds it on
+# the `tree` module, and a `from … import` captures the value at import time, so
+# the name here would still hold the pre-config default. Read through the module.
+from .tree import BLOCKED, BUCKETS, die, find_work_root, rel
+from .frontmatter import as_list, parse_frontmatter, read_item, rewrite_file, split_frontmatter
+from .model import current_session_id, locate, locate_epic, locate_version, record_session, scan
+from .registry import code_vocabulary
+from .scaffold import _check_kebab, _check_owner_ref, _check_priority, _check_unused, _scaffold_handoff, _scaffold_task
+from .epic import _bucketed, cmd_epic_move, epic_for_task
+from .generate import _sync
+from .gate import delivery_gate, report_gate
+from .autonomy import derive_tier
+from . import events
+
+#: Where this repo keeps approved plan files, from `plans.dir` in config. None means
+#: the repo keeps none, and `plan` then requires an explicit `--file` rather than
+#: inventing a directory the repo deliberately does not have.
+PLANS_DIR = None
+
+
+def cmd_new(args) -> int:
+    root = find_work_root()
+    name = args["name"]
+    _check_kebab("task", name)
+    _check_unused(root, name)
+
+    priority = args.get("priority") or "P2"
+    # A bare `--priority` (no value) parses to "true" (see parse_argv); treat it
+    # as P1 ("next") — the natural meaning of flagging a task as a priority.
+    # Otherwise the check below rejects "true" and the whole `new` fails, a
+    # common scripted slip.
+    if priority == "true":
+        priority = "P1"
+    _check_priority(priority)
+    title = args.get("title") or name.replace("-", " ").capitalize()
+    depends = [d.strip() for d in (args.get("depends") or "").split(",") if d.strip()]
+    for d in depends:
+        _check_kebab("dependency", d)
+    tags = [t.strip() for t in (args.get("tags") or "").split(",") if t.strip()]
+    # An empty vocabulary means the repo configured none, so there is nothing to
+    # check against and every tag stands. Refusing here instead would make `tags:`
+    # unusable in any repo that had not opted in.
+    for t in tags:
+        if tree.TASK_TAGS_OK and t not in tree.TASK_TAGS_OK:
+            die(f"unknown tag '{t}' — area tags are: {', '.join(tree.TASK_TAGS_OK)} "
+                f"(set `tags.allowed` in .claude/work.config.json to change them)")
+    owner = (args.get("owner") or args.get("product") or "").strip()
+    if owner:
+        _check_owner_ref(owner)
+    code = [c.strip() for c in (args.get("code") or "").split(",") if c.strip()]
+    vocabulary = code_vocabulary(root)
+    for c in code:
+        if c not in vocabulary:
+            die(f"unknown code region '{c}' — regions are: "
+                f"{', '.join(vocabulary)}")
+    covers = [c.strip() for c in (args.get("covers") or "").split(",") if c.strip()]
+    for c in covers:
+        if not re.match(r"^AC-\d+$", c):
+            die(f"--covers entries must look like 'AC-01' (got '{c}')")
+    # Derived from the tree first, raisable by hand, never lowerable — so a task
+    # whose owner makes it tier 3 is tier 3 whether or not anyone remembered.
+    tier, tier_why = derive_tier(owner, code, args.get("tier"))
+    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})")
+
+    # Every task names an EPIC. A task is one goal end-to-end; an epic is the
+    # coherent goal it serves — work that belongs to no goal is exactly the
+    # scattered-task failure the epic tier was created to end, so this is a
+    # refusal, not a lint.
+    version_name = args.get("version")
+    epic, version_name = epic_for_task(root, args, version_name)
+    if not epic:
+        die(f"--epic is required: a task belongs to an epic, never loose in a "
+            f"version. Create one first — jarvis work epic-new <epic>"
+            + (f" --version {version_name}" if version_name else "")
+            + " (no --version puts it in the backlog)")
+    if version_name:
+        version = locate_version(root, version_name)
+        if version and version.released:
+            die(f"version '{version_name}' is released — pick a planned version")
+    folder = _bucketed(epic, name)
+    home = f"epic '{epic.name}' in " + (f"version '{version_name}'"
+                                        if version_name else "backlog")
+
+    _scaffold_task(folder, title, priority, depends)
+    md = folder / "task.md"
+
+    # `tier` is written unconditionally — it is the field an unattended run reads
+    # to decide whether the task is its to take, and an absent one would fall back
+    # to a derivation every reader would have to repeat.
+    def mutate(d):
+        d["tier"] = tier
+        if tags:
+            d["tags"] = tags
+        if owner:
+            d["owner"] = owner
+        if code:
+            d["code"] = code
+        if covers:
+            d["covers"] = covers
+        if start:
+            d["start"] = start
+        if end:
+            d["end"] = end
+
+    rewrite_file(md, mutate)
+    record_session(folder)
+    events.append(root, "created", name, tier=tier, priority=priority,
+                  epic=epic.name)
+    print(f"created {rel(folder / 'task.md', root)}  ({home})")
+    print(f"        tier {tier} — {tier_why}")
+    _sync(root)
+    return 0
+def cmd_place(args) -> int:
+    """Put work where it belongs — into a version, or back out into the backlog.
+
+    ONE verb, because there was never more than one intent. This was two commands:
+    `pull` moved work out of the backlog and `rehome` moved it between versions, so
+    which one you needed depended on where the work already WAS — a fact the caller
+    normally has to go and look up before it can even choose a command. The
+    destination is what a caller knows; the journey is the harness's business.
+
+    The NAME decides the tier, as it always did: an epic moves whole, a single task
+    needs `--epic` to say where it lands.
+    """
+    root = find_work_root()
+    name = args["name"]
+    to_backlog = str(args.get("backlog", "")).lower() == "true"
+    version_name = args.get("version")
+    if to_backlog and version_name:
+        die("--backlog and --version are two different destinations — pick one")
+    if not to_backlog and not version_name:
+        die("usage: jarvis work place <name> --version <v> [--epic <e>]   "
+            "(or --backlog --epic <e> to take it back out of a cut)")
+
+    if locate_epic(root, name):
+        return cmd_epic_move(args)
+    if to_backlog:
+        return _to_backlog(root, name, args)
+
+    version = locate_version(root, version_name)
+    if not version:
+        die(f"no version named '{version_name}' — create it with: "
+            f"jarvis work version-new {version_name} --outcome '…'")
+    if version.released:
+        die(f"version '{version_name}' is released — pick a planned version")
+
+    task = locate(root, name)
+    if not task:
+        die(f"no task or epic named '{name}' found")
+    if task.version == version.name:
+        die(f"'{name}' is already in version '{version_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.")
+    if task.status == "in-progress":
+        print(f"note: '{name}' is in progress — somebody may be working it right "
+              f"now, and this moves the ground under them.")
+
+    epic, _ = epic_for_task(root, args, version_name)
+    if not epic:
+        die(f"placing a single task needs --epic: it lands inside an epic of "
+            f"'{version_name}', never loose. Epics in that version: "
+            f"{', '.join(e.name for e in version.epics) or 'none yet'}")
+    dest = epic.folder / "queue" / name
+    if dest.exists():
+        die(f"{rel(dest, root)} already exists")
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    shutil.move(str(task.folder), str(dest))
+    md = dest / "task.md"
+    rewrite_file(
+        md,
+        lambda d: d.update({"updated": date.today().isoformat()}),
+    )
+    record_session(dest)
+    print(f"placed '{name}' -> {rel(dest, root)}")
+    _sync(root)
+    return 0
+
+
+def _to_backlog(root, name: str, args) -> int:
+    """Take work back OUT of a cut, into a backlog epic.
+
+    The return door, and it was missing until 2026-09-03. `pull` brought work into
+    a version and `rehome` moved it between versions; nothing took it out. So the
+    only legal answers to *this turned out not to belong in this release* were leave
+    it there or finish it, and a cut that can only grow can never be released —
+    measured here at 155 tasks in one version with 62 unstarted, which is the exact
+    failure `version_new`'s refusal was written to prevent from the other end.
+
+    **Only unstarted work leaves.** A completed task shipped in this cut and that is
+    the historical record; an in-progress one has somebody on it and moving the
+    ground under them is not a board operation. Both are refused rather than
+    silently skipped, because a demotion that quietly left half the work behind is
+    how a caller learns the wrong thing about what just happened.
+    """
+    epic_name = (args.get("epic") or "").strip()
+    if not epic_name:
+        die("taking work out of a cut needs --epic: it lands in a BACKLOG epic, "
+            "never loose. Make one first with `jarvis work epic-new <name>` (no "
+            "--version puts it in the backlog, which is what you want here).")
+    epic = locate_epic(root, epic_name)
+    if not epic:
+        die(f"no epic named '{epic_name}' found")
+    if not epic.in_backlog:
+        die(f"epic '{epic_name}' is in version '{epic.version}', not the backlog — "
+            f"moving work there is `rehome <name> --version {epic.version} "
+            f"--epic {epic_name}`")
+
+    task = locate(root, name)
+    if not task:
+        die(f"no task or epic named '{name}' found")
+    if task.in_backlog:
+        die(f"'{name}' is already in the backlog")
+    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.")
+    if task.status == "in-progress":
+        # A warning, not a refusal, and the same one the version-to-version path
+        # gives: the rule is about what SHIPPED, and taking unfinished work out of a
+        # cut is exactly what you do when it turns out not to belong there. A
+        # stricter guard here than there would only mean the way out is the one
+        # direction you cannot use.
+        print(f"note: '{name}' is in progress — somebody may be working it right "
+              f"now, and this moves the ground under them.")
+
+    dest = epic.folder / name
+    if dest.exists():
+        die(f"{rel(dest, root)} already exists")
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    shutil.move(str(task.folder), str(dest))
+    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)}")
+    _sync(root)
+    return 0
+
+
+def cmd_move(args) -> int:
+    root = find_work_root()
+    name = args["name"]
+    to = args["status"]
+    if to not in BUCKETS:
+        die(f"status must be one of {', '.join(BUCKETS)}")
+    if to == BLOCKED:
+        die(f"`move {name} blocked` is not how a task blocks — a blocked task "
+            f"without a recorded question is one nobody can unblock. Use "
+            f"`jarvis work ask {name} --question \"…\"`.")
+
+    task = locate(root, name)
+    if not task:
+        die(f"no task named '{name}' found")
+    if task.in_backlog:
+        die(f"'{name}' is in backlog — pull it into a version first "
+            f"(jarvis work place {name} --version <v>)")
+    if task.status == to:
+        print(f"'{name}' is already in {to}/")
+        return 0
+
+    # Somebody else is on this. It WARNS rather than refuses: `next` is the door
+    # that hands work out and it already declines a held task, whereas `move` is
+    # what a person uses when they have decided to take something over — and a
+    # harness that argued with that would just get worked around. What it owes is
+    # the fact, and who to talk to before the two of you collide.
+    from .shift import read_claim
+    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)
+
+    # The gate runs BEFORE the folder moves. It used to warn after — which meant
+    # the task was already sitting in `complete/` when the warning printed, and
+    # the board said done regardless of who read it.
+    delivered = (args.get("delivered") or "").strip()
+    not_included = (args.get("not-included") or args.get("not_included") or "").strip()
+    if to == "complete":
+        missing = delivery_gate(delivered, not_included)
+        if missing:
+            print(f"error: '{name}' cannot complete — the delivery line is "
+                  f"incomplete:", file=sys.stderr)
+            for m in missing:
+                print(f"       · {m}", file=sys.stderr)
+            events.append(root, "gate-refused", name, why="; ".join(missing)[:300])
+            return 1
+        if not report_gate(root, task, (args.get("accept") or "").strip(),
+                           (args.get("owner") or "").strip()):
+            return 1
+
+    # The task's container is the parent of its bucket — the EPIC folder for a
+    # task in the epic shape, the VERSION folder for a grandfathered loose one.
+    # Deriving it from the path rather than the tier means `move` works in both
+    # shapes without knowing which it is in.
+    container = task.folder.parent.parent
+    dest = container / to / name
+    if dest.exists():
+        die(f"{rel(dest, root)} already exists")
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    shutil.move(str(task.folder), str(dest))
+
+    def mutate(d):
+        d["updated"] = date.today().isoformat()
+        if to == "complete":
+            d["completed"] = date.today().isoformat()
+        else:
+            d.pop("completed", None)
+
+    md = dest / "task.md"
+    rewrite_file(md, mutate)
+    record_session(dest)
+    events.append(root, "moved", name, **{"from": task.status, "to": to})
+    print(f"moved '{name}': {task.status}/ -> {to}/")
+
+    # No handoff is scaffolded on pickup — `handoff.md` is created on demand via
+    # `jarvis work handoff` only when a task actually hands across conversations
+    # (a blank scaffold on every pickup was noise). Working checklists live in
+    # native TodoWrite, so completion strips nothing.
+    if to == "complete":
+        # The lease is the claim on WORK IN FLIGHT; finished work holds nothing.
+        # Leaving it would make `status` report a live instance on a done task.
+        claim = dest / ".claim"
+        if claim.is_file():
+            claim.unlink()
+        events.append(root, "completed", name, delivered=delivered or None,
+                      not_included=not_included or None)
+        # The forwardable line. `not_included` is asked for every time and never
+        # inferred: the failure it prevents is overpromising, and a field the
+        # harness fills in for you prevents nothing.
+        print(f"        delivered: {delivered}")
+        print(f"        NOT included: {not_included}")
+
+    _sync(root)
+    return 0
+def cmd_handoff(args) -> int:
+    root = find_work_root()
+    name = args["name"]
+    task = locate(root, name)
+    if not task:
+        die(f"no task named '{name}' found")
+    if task.in_backlog or task.status == "queue":
+        die(f"'{name}' is queued/backlog — handoff is for in-progress work "
+            f"(pick it up first: jarvis work move {name} in-progress)")
+    if _scaffold_handoff(task.folder, task.title):
+        print(f"scaffolded {rel(task.folder / 'handoff.md', root)}")
+    else:
+        print(f"'{name}' already has a handoff.md — edit it in place")
+    return 0
+def cmd_session(args) -> int:
+    """Record a session on a task. The current one by default; `--id` records one
+    this session STARTED, which is the wrap handing its successor to the board
+    rather than to a line of prose in the handoff."""
+    root = find_work_root()
+    task = locate(root, args["name"])
+    if not task:
+        die(f"no task named '{args['name']}' found")
+    given = (args.get("id") or "").strip()
+    label = None
+    if given:
+        # Refused rather than written. This value arrives from a tool's answer,
+        # lands in committed frontmatter, and is read back by anything that walks
+        # `sessions:` — so a truncated or error-shaped id is caught here, where it
+        # is one message, not later as a session nobody can resume.
+        if not re.fullmatch(r"[0-9a-fA-F-]{8,64}", given):
+            die(f"--id {given!r} is not a session id — expected the `sessionId` the "
+                f"start returned, e.g. 487e9271-c3d8-4f38-b42e-6716fe078506")
+        sid = given
+        # Only a session that is not this one is a successor. Passing your own id
+        # explicitly is legal and means what it says: record me.
+        if sid != current_session_id():
+            label = "successor"
+    else:
+        sid = current_session_id()
+        if not sid:
+            print("no CLAUDE_CODE_SESSION_ID in environment — nothing recorded")
+            return 0
+    if record_session(task.folder, sid, label):
+        print(f"recorded {label or 'session'} {sid} on '{task.name}'")
+    else:
+        print(f"session {sid} already recorded on '{task.name}'")
+    return 0
+def cmd_plan(args) -> int:
+    """Append a dated, deduped pointer to an approved plan file onto a task's
+    `plans:` frontmatter list (mirrors `sessions:`). The plan content is NOT
+    copied in — only a path, so the ref survives desktop<->cloud<->mobile hops
+    (E2). A fresh session walks `plans:` newest-first to the first ref that still
+    exists and re-enters plan mode from there.
+
+    The path is `--file`, else `<plans.dir>/<name>.md`. With `plans.dir` null the
+    harness REFUSES rather than defaulting: one consumer keeps a plans directory
+    and another deleted it on purpose, so a shipped default would silently
+    scaffold a pointer into a directory the repo does not have."""
+    root = find_work_root()
+    name = args["name"]
+    task = locate(root, name)
+    if not task:
+        die(f"no task named '{name}' found")
+    if not args.get("file") and not PLANS_DIR:
+        die("no `plans.dir` configured — pass `--file <path>`, or set "
+            "`plans.dir` in .claude/work.config.json if this repo keeps a "
+            "plans directory")
+    path = (args.get("file") or f"{PLANS_DIR.rstrip('/')}/{task.name}.md").strip()
+    md = task.folder / "task.md"
+    text = read_item(md)
+    plans = as_list(parse_frontmatter(text).get("plans"))
+    if any(path in entry for entry in plans):
+        print(f"plan '{path}' already recorded on '{task.name}'")
+        return 0
+    entry = f"{date.today().isoformat()}  {path}"
+
+    def mutate(d):
+        if any(path in existing for existing in as_list(d.get("plans"))):
+            return
+        d["plans"] = as_list(d.get("plans")) + [entry]
+        d["updated"] = date.today().isoformat()
+
+    rewrite_file(md, mutate)
+    print(f"recorded plan '{path}' on '{task.name}'")
+    return 0
+def cmd_path(args) -> int:
+    root = find_work_root()
+    name = args["name"]
+    task = locate(root, name)
+    if task:
+        print(task.folder)
+        return 0
+    epic = locate_epic(root, name)
+    if epic:
+        print(epic.folder)
+        return 0
+    version = locate_version(root, name)
+    if version:
+        print(version.folder)
+        return 0
+    die(f"no task, epic or version named '{name}' found")
+def cmd_code(args) -> int:
+    """Every task whose `code:` includes `<region>`, across all versions +
+    backlog, grouped by version -> bucket. The cross-version glue for reading
+    where a seam is already being touched before adding another task to it
+    (foundation-before-feature is an inference the brain draws over this)."""
+    root = find_work_root()
+    region = args["region"]
+    vocabulary = code_vocabulary(root)
+    if region not in vocabulary:
+        die(f"unknown code region '{region}' — regions are: "
+            f"{', '.join(vocabulary)}")
+
+    s = scan(root)
+    found = False
+
+    def _emit(tasks: list) -> bool:
+        for t in tasks:
+            print(f"    {t.name} — {t.title}  [owner: {t.owner or '—'}]")
+        return bool(tasks)
+
+    for v in sorted(s["versions"], key=lambda x: (x.order, x.name)):
+        for b in BUCKETS:
+            # Loose tasks first (the grandfathered shape), then per epic — the
+            # epic label is what makes "who else is already in this seam"
+            # answerable at the level the work is actually planned.
+            hits = [t for t in v.tasks[b] if region in t.code]
+            if hits:
+                found = True
+                print(f"\nVERSION {v.name} / {b}")
+                _emit(hits)
+            for e in v.epics:
+                hits = [t for t in e.tasks[b] if region in t.code]
+                if hits:
+                    found = True
+                    print(f"\nVERSION {v.name} / EPIC {e.name} / {b}")
+                    _emit(hits)
+
+    for e in s["backlog_epics"]:
+        hits = sorted((t for t in e.backlog_tasks if region in t.code),
+                      key=lambda x: (x.priority_rank(), x.name))
+        if hits:
+            found = True
+            print(f"\nBACKLOG / EPIC {e.name}")
+            _emit(hits)
+
+    loose = sorted((t for t in s["backlog"] if region in t.code and not t.epic),
+                   key=lambda x: (x.priority_rank(), x.name))
+    if loose:
+        found = True
+        print("\nBACKLOG")
+        _emit(loose)
+
+    if not found:
+        print(f"no tasks tagged code: {region}")
+    return 0