taskgate 0.1.0__py3-none-any.whl

taskgate/__init__.py

@@ -0,0 +1,3 @@
+"""taskgate: a gated task registry with an MCP server."""
+
+__version__ = "0.1.0"

taskgate/__main__.py

@@ -0,0 +1,5 @@
+"""``python -m taskgate``."""
+
+from .cli import run
+
+run()

taskgate/cli.py

@@ -0,0 +1,133 @@
+"""CLI entrypoint: ``taskgate`` / ``python -m taskgate``."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from . import __version__, clients, model
+from .commands.flow import cmd_add, cmd_claim, cmd_list, cmd_next, cmd_update
+from .commands.plan import cmd_depends, cmd_move
+from .commands.registry import cmd_init, cmd_render, cmd_sort, cmd_validate
+
+BY_HELP = "identity (default TASKGATE_BY env / 'human')"
+
+
+def _cmd_snippet(args: argparse.Namespace) -> int:
+    try:
+        print(clients.snippet(args.client, source=args.source, root=args.root), end="")
+    except ValueError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+    return 0
+
+
+def _cmd_mcp(_args: argparse.Namespace) -> int:
+    from .mcp import server  # lazy: the server imports this module's main()
+
+    server.serve()
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Assemble the argparse tree."""
+    parser = argparse.ArgumentParser(
+        prog="taskgate",
+        description="Gated task registry: strict status flow with verification and review evidence.",
+    )
+    parser.add_argument("--version", action="version", version=f"taskgate {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p = sub.add_parser("init", help="create the registry in the current directory (or TASKGATE_ROOT)")
+    p.add_argument("--seed", help="path to seed JSON (tasks array)")
+    p.add_argument("--force", action="store_true", help="overwrite existing registry")
+    p.add_argument("--by", help=BY_HELP)
+    p.set_defaults(func=cmd_init)
+
+    p = sub.add_parser("validate", help="schema + flow-rule validation")
+    p.set_defaults(func=cmd_validate)
+
+    p = sub.add_parser("render", help="generate the Markdown view")
+    p.add_argument("--check", action="store_true", help="fail when the view drifted from tasks.json")
+    p.add_argument("--out", help="alternative output path (ignored with --check)")
+    p.set_defaults(func=cmd_render)
+
+    p = sub.add_parser("next", help="show the one task that may start now (queue head)")
+    p.add_argument("--owner", help="only tasks unowned or owned by this identity")
+    p.set_defaults(func=cmd_next)
+
+    p = sub.add_parser("list", help="list all tasks")
+    p.add_argument("--status", choices=model.STATUSES, help="filter by status")
+    p.set_defaults(func=cmd_list)
+
+    p = sub.add_parser("claim", help="claim a planned task (-> in_progress)")
+    p.add_argument("id")
+    p.add_argument("--by", help=BY_HELP)
+    p.add_argument("--force", action="store_true", help="steal from another owner")
+    p.set_defaults(func=cmd_claim)
+
+    p = sub.add_parser("update", help="change status / record verification or review")
+    p.add_argument("id")
+    p.add_argument("--status", choices=model.STATUSES)
+    p.add_argument("--reason", help="required by blocked; recorded for cancelled")
+    p.add_argument("--verification-result", help="JSON object, e.g. '{\"ok\": true}'")
+    p.add_argument(
+        "--review-result",
+        help="JSON object from the reviewer, e.g. '{\"ok\": true, \"by\": \"reviewer\", \"checks\": [\"cmd\"]}'",
+    )
+    p.add_argument("--by", help=BY_HELP)
+    p.set_defaults(func=cmd_update)
+
+    p = sub.add_parser("add", help="append a new task to the registry")
+    p.add_argument("--id", required=True, help="id matching the configured id_pattern")
+    p.add_argument("--title", required=True)
+    p.add_argument("--phase", type=int, help="phase (default: from the id's 'phase' group, else 0)")
+    p.add_argument("--verification-cmd", required=True, dest="verification_cmd")
+    p.add_argument("--spec", help="spec_source anchor (path + section)")
+    p.add_argument("--status", default="planned", choices=model.ADD_STATUSES)
+    p.add_argument("--owner")
+    p.add_argument("--depends", help="comma-separated task ids")
+    p.add_argument("--by", help=BY_HELP)
+    p.set_defaults(func=cmd_add)
+
+    p = sub.add_parser("sort", help="reset the execution order to phase, then id")
+    p.add_argument("--by", help=BY_HELP)
+    p.set_defaults(func=cmd_sort)
+
+    p = sub.add_parser("move", help="place a draft/planned task before or after another")
+    p.add_argument("id")
+    anchor = p.add_mutually_exclusive_group(required=True)
+    anchor.add_argument("--before", metavar="ID", help="place directly before this task")
+    anchor.add_argument("--after", metavar="ID", help="place directly after this task")
+    p.add_argument("--by", help=BY_HELP)
+    p.set_defaults(func=cmd_move)
+
+    p = sub.add_parser("depends", help="change the dependencies of a draft/planned task")
+    p.add_argument("id")
+    p.add_argument("--set", help="comma-separated ids replacing the dependencies ('' clears)")
+    p.add_argument("--add", help="comma-separated ids to add")
+    p.add_argument("--remove", help="comma-separated ids to remove")
+    p.add_argument("--by", help=BY_HELP)
+    p.set_defaults(func=cmd_depends)
+
+    p = sub.add_parser("mcp", help="start the MCP stdio server (JSON-RPC 2.0, newline-delimited)")
+    p.set_defaults(func=_cmd_mcp)
+
+    p = sub.add_parser("config-snippet", help="print MCP configuration for a client")
+    p.add_argument("client", choices=list(clients.CLIENTS), help="; ".join(f"{k}: {v}" for k, v in clients.CLIENTS.items()))
+    p.add_argument("--from", dest="source", help="uvx source (path, git URL or version spec); default: PyPI")
+    p.add_argument("--root", help="absolute project root, written as TASKGATE_ROOT")
+    p.set_defaults(func=_cmd_snippet)
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Program entry: dispatch commands, return the exit code."""
+    args = build_parser().parse_args(argv)
+    code: int = args.func(args)
+    return code
+
+
+def run() -> None:
+    """Console-script entry point."""
+    sys.exit(main())

taskgate/clients.py

@@ -0,0 +1,52 @@
+"""Ready-to-paste MCP server configuration for common clients (``taskgate config-snippet``)."""
+
+from __future__ import annotations
+
+import json
+
+CLIENTS = {
+    "claude": "Claude Code: .mcp.json in the project (or `claude mcp add`)",
+    "vscode": "VS Code (GitHub Copilot agent mode): .vscode/mcp.json",
+    "codex": "OpenAI Codex CLI: ~/.codex/config.toml",
+    "cursor": "Cursor: .cursor/mcp.json",
+    "gemini": "Gemini CLI: .gemini/settings.json",
+    "generic": "any client that takes a command and arguments",
+}
+
+
+def launch(source: str | None) -> tuple[str, list[str]]:
+    """Command and arguments that start the stdio server through ``uvx``."""
+    args = ["--from", source, "taskgate", "mcp"] if source else ["taskgate", "mcp"]
+    return "uvx", args
+
+
+def snippet(client: str, *, source: str | None = None, root: str | None = None) -> str:
+    """The configuration text for ``client``; raises ``ValueError`` for an unknown client."""
+    if client not in CLIENTS:
+        raise ValueError(f"unknown client {client!r}; choose one of {', '.join(CLIENTS)}")
+    command, args = launch(source)
+    env = {"TASKGATE_ROOT": root} if root else {}
+    if client == "codex":
+        lines = ["[mcp_servers.taskgate]", f"command = {json.dumps(command)}", f"args = {json.dumps(args)}"]
+        if env:
+            lines += ["", "[mcp_servers.taskgate.env]", f"TASKGATE_ROOT = {json.dumps(root)}"]
+        return "\n".join(lines) + "\n"
+    if client == "claude":
+        add = ["claude", "mcp", "add", "taskgate"]
+        if root:
+            add += ["-e", f"TASKGATE_ROOT={root}"]
+        add += ["--", command, *args]
+        entry: dict[str, object] = {"type": "stdio", "command": command, "args": args}
+        if env:
+            entry["env"] = env
+        text = json.dumps({"mcpServers": {"taskgate": entry}}, indent=2)
+        return f"# one command:\n{' '.join(add)}\n\n# or .mcp.json:\n{text}\n"
+    if client == "vscode":
+        entry = {"type": "stdio", "command": command, "args": args}
+        if env:
+            entry["env"] = env
+        return json.dumps({"servers": {"taskgate": entry}}, indent=2) + "\n"
+    entry = {"command": command, "args": args}
+    if env:
+        entry["env"] = env
+    return json.dumps({"mcpServers": {"taskgate": entry}}, indent=2) + "\n"

taskgate/commands/__init__.py

@@ -0,0 +1 @@
+"""CLI commands."""

taskgate/commands/common.py

@@ -0,0 +1,25 @@
+"""Helpers shared by the CLI commands."""
+
+from __future__ import annotations
+
+import argparse
+import os
+from typing import Any
+
+EMPTY_REGISTRY: dict[str, Any] = {"version": 1, "tasks": []}
+
+VERIFICATION_STATUSES = ("in_review", "done")
+
+
+def identity(args: argparse.Namespace) -> str:
+    """Declared caller identity: ``--by``, else ``TASKGATE_BY``, else ``human``."""
+    by: str | None = getattr(args, "by", None)
+    return by or os.environ.get("TASKGATE_BY", "human")
+
+
+def find(data: dict[str, Any], task_id: str) -> tuple[dict[str, Any], bool]:
+    """The task with this id and whether it exists."""
+    for task in data.get("tasks", []):
+        if task.get("id") == task_id:
+            return task, True
+    return {}, False

taskgate/commands/flow.py

@@ -0,0 +1,307 @@
+"""Task flow commands: next, list, claim, update, add."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from datetime import datetime
+from typing import Any
+
+from .. import model, ordering, store
+from ..config import Config
+from .common import VERIFICATION_STATUSES, find, identity
+
+
+def cmd_next(args: argparse.Namespace) -> int:
+    project = store.open_project()
+    data = store.load(project)
+    head = ordering.queue_head(data.get("tasks", []))
+    if head is None:
+        print("no open tasks (every task is done or cancelled)")
+        return 2
+    if head.get("status") != "planned":
+        print(f"nothing to claim: {head['id']} is next in order and is {head.get('status')!r}")
+        return 2
+    blockers = ordering.claim_blockers(data, head, project.config)
+    if blockers:
+        print(f"{head['id']} is next in order but cannot start:", file=sys.stderr)
+        for reason in blockers:
+            print(f"  - {reason}", file=sys.stderr)
+        return 2
+    if args.owner and head.get("owner") not in (None, args.owner):
+        print(f"nothing to claim: {head['id']} is owned by {head['owner']!r}")
+        return 2
+    owner = head.get("owner") or "unowned"
+    print(f"{head['id']}  [{owner}]  {head['title']}  // verify: {head.get('verification_cmd')}")
+    return 0
+
+
+def cmd_list(args: argparse.Namespace) -> int:
+    project = store.open_project()
+    rows = store.load(project).get("tasks", [])
+    for t in rows:
+        if args.status and t.get("status") != args.status:
+            continue
+        info = f"  // blocked: {t.get('blocked_reason')}" if t.get("status") == "blocked" else ""
+        if t.get("depends_on"):
+            info += f"  <- {','.join(t['depends_on'])}"
+        print(f"{t['id']}  {t.get('status'):12}  {t.get('owner') or '-':12}  {t.get('title')}{info}")
+    print(f"-- {len(rows)} task(s)")
+    return 0
+
+
+def cmd_claim(args: argparse.Namespace) -> int:
+    project = store.open_project()
+    by = identity(args)
+    with store.locked(project):
+        data = store.load(project)
+        task, found = find(data, args.id)
+        if not found:
+            print(f"error: unknown task {args.id}", file=sys.stderr)
+            return 1
+        current = task.get("status")
+        if current != "planned":
+            print(f"error: {args.id} is {current!r}, claim requires 'planned'", file=sys.stderr)
+            return 1
+        blockers = ordering.claim_blockers(data, task, project.config)
+        if blockers:
+            print(f"error: {args.id} cannot start:", file=sys.stderr)
+            for reason in blockers:
+                print(f"  - {reason}", file=sys.stderr)
+            return 1
+        if task.get("owner") and task["owner"] != by and not args.force:
+            print(f"error: {args.id} already owned by {task['owner']!r} (--force to steal)", file=sys.stderr)
+            return 1
+        task.update({"status": "in_progress", "owner": by, "started": store.now()})
+        store.save(project, data)
+        store.append_log(project, "claim", args.id, by, {"status": "in_progress"})
+    print(f"{args.id} claimed by {by} -> in_progress")
+    return 0
+
+
+def _parse_result(raw: str, flag: str) -> dict[str, Any] | None:
+    """Parse a ``--*-result`` JSON object; ``None`` means the payload was refused."""
+    try:
+        result = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        print(f"error: {flag} is not valid JSON: {exc}", file=sys.stderr)
+        return None
+    if not isinstance(result, dict):
+        print(f"error: {flag} must be a JSON object", file=sys.stderr)
+        return None
+    return result
+
+
+def _parse_instant(value: Any) -> datetime | None:
+    """Parse a stored timestamp as a timezone-aware instant (``Z`` or offset)."""
+    if not isinstance(value, str):
+        return None
+    try:
+        parsed = datetime.fromisoformat(value)
+    except ValueError:
+        return None
+    return parsed if parsed.tzinfo is not None else None
+
+
+def _review_problem(task: dict[str, Any], review: dict[str, Any], by: str, config: Config) -> str | None:
+    """Check the review write preconditions, in the order the contract fixes them."""
+    reviewer = config.reviewer
+    if by != reviewer or review.get("by") != reviewer:
+        return f"review_result.by and caller identity must both be {reviewer!r}"
+    verification = task.get("verification_result")
+    if not isinstance(verification, dict) or not model.is_green(verification):
+        return "recording review_result requires a green verification_result"
+    verifier = verification.get("by")
+    if not isinstance(verifier, str) or not verifier.strip():
+        return "verification_result.by is required; record fresh verification before review"
+    if verifier == reviewer:
+        return "reviewer must differ from verification_result.by"
+    checks = review.get("checks")
+    if not isinstance(checks, list) or not checks or not all(isinstance(c, str) and c.strip() for c in checks):
+        return "review_result.checks must be a non-empty list of non-blank command strings"
+    verified_at = _parse_instant(verification.get("at"))
+    if verified_at is None:
+        return (
+            "verification_result.at must be a timezone-aware ISO-8601 datetime; "
+            "record fresh verification before review"
+        )
+    current = _parse_instant(store.now())
+    elapsed = None if current is None else (current - verified_at).total_seconds()
+    if elapsed is None or elapsed < config.review_delay_seconds:
+        return f"review_result requires at least {config.review_delay_seconds} seconds after verification_result.at"
+    return None
+
+
+def cmd_update(args: argparse.Namespace) -> int:
+    project = store.open_project()
+    config = project.config
+    by = identity(args)
+    with store.locked(project):
+        data = store.load(project)
+        task, found = find(data, args.id)
+        if not found:
+            print(f"error: unknown task {args.id}", file=sys.stderr)
+            return 1
+        if args.verification_result is not None and args.review_result is not None:
+            print(
+                "error: verification_result and review_result must be recorded in separate update calls",
+                file=sys.stderr,
+            )
+            return 1
+        current = task.get("status") or "draft"
+        if current in model.TERMINAL and (
+            args.verification_result is not None or args.review_result is not None or args.status is not None
+        ):
+            print("error: terminal tasks cannot receive result writes or be closed again", file=sys.stderr)
+            return 1
+        verification: dict[str, Any] | None = None
+        if args.verification_result is not None:
+            verification = _parse_result(args.verification_result, "--verification-result")
+            if verification is None:
+                return 1
+            claimed_by = verification.get("by")
+            if claimed_by is not None and claimed_by != by:
+                print("error: verification_result.by must match the caller identity", file=sys.stderr)
+                return 1
+            verification["by"] = by
+            # tool-owned timestamp: a caller-supplied 'at' cannot backdate evidence
+            verification["at"] = store.now()
+            verification.setdefault("cmd", task.get("verification_cmd"))
+        review: dict[str, Any] | None = None
+        if args.review_result is not None:
+            review = _parse_result(args.review_result, "--review-result")
+            if review is None:
+                return 1
+            problem = _review_problem(task, review, by, config)
+            if problem is not None:
+                print(f"error: {problem}", file=sys.stderr)
+                return 1
+            review["at"] = store.now()
+        if review is not None and current != "in_review":
+            print("error: review_result can only be recorded while the task is 'in_review'", file=sys.stderr)
+            return 1
+        if args.status == "done" and review is None and config.require_review:
+            print("error: --status done requires a fresh --review-result in the same update", file=sys.stderr)
+            return 1
+        detail: dict[str, Any] = {}
+        if verification is not None:
+            # a fresh verification voids the earlier approval
+            task.pop("review_result", None)
+            task["verification_result"] = verification
+            detail["verification_result"] = True
+        if args.status == "in_progress" and current != args.status:
+            task.pop("review_result", None)
+        if review is not None:
+            task["review_result"] = review
+            detail["review_result"] = True
+        if args.status is not None:
+            if current != args.status and not model.can_transition(current, args.status):
+                allowed = sorted(model.TRANSITIONS.get(current, frozenset()))
+                print(
+                    f"error: {args.id}: {current!r} -> {args.status!r} not allowed (allowed: {allowed})",
+                    file=sys.stderr,
+                )
+                return 1
+            if current == "planned" and args.status == "in_progress":
+                print(
+                    f"error: {args.id}: start work with 'claim' "
+                    "(it enforces order, dependencies and the phase gate)",
+                    file=sys.stderr,
+                )
+                return 1
+            if args.status == "blocked":
+                reason = args.reason or task.get("blocked_reason")
+                if not reason:
+                    print("error: --status blocked requires --reason", file=sys.stderr)
+                    return 1
+                task["blocked_reason"] = reason
+                detail["blocked_reason"] = reason
+            elif current == "blocked":
+                task.pop("blocked_reason", None)
+                detail["blocked_reason"] = None
+            if args.status == "in_progress" and not task.get("started"):
+                task["started"] = store.now()
+            if args.status in model.TERMINAL:
+                task["finished"] = store.now()
+                if args.status == "cancelled" and args.reason:
+                    task.setdefault("notes", []).append(
+                        {"at": store.now(), "by": by, "text": f"cancelled: {args.reason}"}
+                    )
+            task["status"] = args.status
+            detail["status"] = args.status
+        if args.status in VERIFICATION_STATUSES and not model.is_green(task.get("verification_result")):
+            print(
+                f"error: --status {args.status} requires a green verification_result "
+                "(pass --verification-result '{\"ok\": true, ...}')",
+                file=sys.stderr,
+            )
+            return 1
+        if args.status == "done" and config.require_review and not model.is_review(
+            task.get("review_result"), config.reviewer
+        ):
+            print(
+                "error: --status done requires a green review_result with the reviewer identity "
+                f"(pass --review-result '{{\"ok\": true, \"by\": \"{config.reviewer}\", \"checks\": [...]}}')",
+                file=sys.stderr,
+            )
+            return 1
+        store.save(project, data)
+        store.append_log(project, "update", args.id, by, detail or {"no-op": True})
+    print(f"{args.id} updated ({', '.join(f'{k}={v!r}' for k, v in detail.items()) or 'no-op'})")
+    return 0
+
+
+def cmd_add(args: argparse.Namespace) -> int:
+    project = store.open_project()
+    config = project.config
+    by = identity(args)
+    if by not in config.planners:
+        print(
+            f"error: only {', '.join(config.planners)} may add tasks (got {by!r}); pass --by with a planner identity",
+            file=sys.stderr,
+        )
+        return 1
+    match = config.id_regex.fullmatch(args.id)
+    phase = args.phase
+    if phase is None:
+        phase = int(match.group("phase")) if match and "phase" in match.groupdict() and match.group("phase") else 0
+    task: dict[str, Any] = {
+        "id": args.id,
+        "title": args.title,
+        "phase": phase,
+        "status": args.status,
+        "verification_cmd": args.verification_cmd,
+    }
+    if args.spec:
+        task["spec_source"] = args.spec
+    if args.owner:
+        task["owner"] = args.owner
+    if args.depends:
+        task["depends_on"] = [d for d in args.depends.split(",") if d]
+    with store.locked(project):
+        data = store.load(project)
+        if find(data, args.id)[1]:
+            print(f"error: task {args.id} already exists", file=sys.stderr)
+            return 1
+        phase_now = ordering.current_phase(data["tasks"])
+        if phase < phase_now:
+            print(
+                f"error: phase {phase} is already closed (current phase is {phase_now}); "
+                f"add the task to phase {phase_now} or later",
+                file=sys.stderr,
+            )
+            return 1
+        # appended after the last task of its phase; 'move' places it elsewhere
+        position = ordering.insert_position(data["tasks"], phase)
+        data["tasks"] = [*data["tasks"][:position], task, *data["tasks"][position:]]
+        errors = model.validate(data, config)
+        if errors:
+            for error in errors:
+                print(f"ERROR: {error}", file=sys.stderr)
+            return 1
+        task["created"] = store.now()
+        store.save(project, data)
+        store.append_log(project, "add", args.id, by, {"status": task["status"]})
+    print(f"{args.id} added ({task['status']})")
+    return 0

taskgate/commands/plan.py

@@ -0,0 +1,101 @@
+"""Planning commands: move (execution order) and depends (dependencies)."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from typing import Any
+
+from .. import model, ordering, store
+from ..config import Config
+from .common import find, identity
+
+
+def _planner(args: argparse.Namespace, config: Config) -> str | None:
+    """The caller identity when it may plan, otherwise ``None`` after printing the refusal."""
+    by = identity(args)
+    if by not in config.planners:
+        print(
+            f"error: only {', '.join(config.planners)} may change the plan (got {by!r}); "
+            f"pass --by with a planner identity",
+            file=sys.stderr,
+        )
+        return None
+    return by
+
+
+def _valid(data: dict[str, Any], config: Config) -> bool:
+    errors = model.validate(data, config)
+    for error in errors:
+        print(f"ERROR: {error}", file=sys.stderr)
+    return not errors
+
+
+def cmd_move(args: argparse.Namespace) -> int:
+    project = store.open_project()
+    by = _planner(args, project.config)
+    if by is None:
+        return 1
+    anchor = args.before or args.after
+    with store.locked(project):
+        data = store.load(project)
+        blockers = ordering.move_blockers(data.get("tasks", []), args.id, anchor, after=bool(args.after))
+        if blockers:
+            for reason in blockers:
+                print(f"error: {reason}", file=sys.stderr)
+            return 1
+        data["tasks"] = ordering.moved(data["tasks"], args.id, anchor, after=bool(args.after))
+        if not _valid(data, project.config):
+            return 1
+        place = "after" if args.after else "before"
+        store.save(project, data)
+        store.append_log(project, "move", args.id, by, {place: anchor})
+    print(f"{args.id} moved {place} {anchor}")
+    return 0
+
+
+def _ids(raw: str | None) -> list[str]:
+    return [part.strip() for part in raw.split(",") if part.strip()] if raw else []
+
+
+def cmd_depends(args: argparse.Namespace) -> int:
+    project = store.open_project()
+    by = _planner(args, project.config)
+    if by is None:
+        return 1
+    if args.set is None and not args.add and not args.remove:
+        print("error: pass --set, --add or --remove", file=sys.stderr)
+        return 1
+    if args.set is not None and (args.add or args.remove):
+        print("error: --set cannot be combined with --add or --remove", file=sys.stderr)
+        return 1
+    with store.locked(project):
+        data = store.load(project)
+        task, found = find(data, args.id)
+        if not found:
+            print(f"error: unknown task {args.id}", file=sys.stderr)
+            return 1
+        if task.get("status") not in ordering.MOVABLE:
+            print(
+                f"error: {args.id} is {task.get('status')!r}; dependencies can only change "
+                "while a task is draft or planned",
+                file=sys.stderr,
+            )
+            return 1
+        current = list(task.get("depends_on") or [])
+        wanted = _ids(args.set) if args.set is not None else [*current, *_ids(args.add)]
+        removed = set(_ids(args.remove))
+        result = list(dict.fromkeys(dep for dep in wanted if dep not in removed))
+        if args.id in result:
+            print(f"error: {args.id} cannot depend on itself", file=sys.stderr)
+            return 1
+        if result:
+            task["depends_on"] = result
+        else:
+            task.pop("depends_on", None)
+        if not _valid(data, project.config):
+            return 1
+        store.save(project, data)
+        store.append_log(project, "depends", args.id, by, {"depends_on": result})
+    print(f"{args.id} depends on {', '.join(result) if result else 'nothing'}")
+    return 0