taskgate 0.1.0__tar.gz

taskgate-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 prachwal
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

taskgate-0.1.0/PKG-INFO

@@ -0,0 +1,156 @@
+Metadata-Version: 2.4
+Name: taskgate
+Version: 0.1.0
+Summary: Gated task registry with an MCP server: strict status flow, verification and review evidence, for Claude Code, Codex, VS Code Copilot and other MCP clients.
+Author: prachwal
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/prachwal/taskgate
+Project-URL: Repository, https://github.com/prachwal/taskgate
+Project-URL: Issues, https://github.com/prachwal/taskgate/issues
+Keywords: mcp,model-context-protocol,task-tracker,agents,workflow,claude-code,codex,copilot
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Requires-Dist: mypy>=1.11; extra == "dev"
+Dynamic: license-file
+
+# taskgate
+
+A task registry that makes "done" mean something. Tasks move through a strict status flow, and the
+transitions that matter are gated by evidence: a task enters review only with a green verification, and
+closes only with a review from a *different* identity that lists the commands it checked. It ships as a CLI
+and as an MCP server, so coding agents (Claude Code, Codex, VS Code Copilot, Cursor, Gemini CLI) and humans
+work from the same registry.
+
+- stdlib-only, no runtime dependencies; Python 3.11+; Linux, macOS and Windows
+- state is plain files you commit: `tasks.json` (source of truth), an append-only `tasks.log.jsonl` and a
+  generated `tasks.md`
+- one code path: every MCP tool calls the same CLI command a human would run
+
+## Quick start
+
+```sh
+cd your-project
+uvx taskgate init
+uvx taskgate add --id T-1 --title "Parse the header" --verification-cmd "pytest tests/test_header.py"
+uvx taskgate next              # which task may start now
+uvx taskgate claim T-1 --by dev
+```
+
+Add it to your agent (prints a ready-to-paste block; see [docs/clients.md](docs/clients.md)):
+
+```sh
+uvx taskgate config-snippet claude     # also: vscode, codex, cursor, gemini, generic
+```
+
+From a checkout instead of PyPI: `uvx --from /path/to/taskgate taskgate ...`, or
+`taskgate config-snippet claude --from /path/to/taskgate`.
+
+## The flow
+
+```
+draft -> planned -> in_progress -> in_review -> done
+                        |  ^           |
+                        v  |           +--> in_progress   (review rejected)
+                      blocked
+any non-terminal status -> cancelled
+```
+
+| Rule | What it enforces |
+| --- | --- |
+| order | `claim` works only on tasks whose predecessors in the registry are `done` or `cancelled` |
+| phase gate | a task in a later phase waits until every earlier phase is closed and the registry validates |
+| dependencies | `depends_on` tasks must be `done` before the task can start |
+| verification | `in_review` and `done` need a green `verification_result`; the tool stamps who recorded it and when |
+| review | `done` needs a green `review_result` from the reviewer identity, different from the verifier, listing `checks`, recorded after a delay, in the same call as the closing update |
+| fresh evidence | a new verification voids an earlier review; results are never accepted together in one call |
+| planning | adding, moving and re-linking tasks is limited to the `planners` identities; started work is never reordered |
+
+Identities (`--by`, or the `TASKGATE_BY` environment variable, default `human`) are *declared by the caller*.
+This is a process barrier that keeps roles apart and leaves a trail in the log; it is not authentication.
+
+## Configuration
+
+Optional `taskgate.toml` in the project root; every key has a default
+([examples/taskgate.toml](examples/taskgate.toml)).
+
+| Key | Default | Meaning |
+| --- | --- | --- |
+| `data_dir` | `.taskgate` | where `tasks.json`, `tasks.log.jsonl`, `tasks.md` live |
+| `title` | `Tasks` | heading of the Markdown view |
+| `id_pattern` | `^[A-Za-z][A-Za-z0-9]*-\d+$` | task id regex; a named group `(?P<phase>\d+)` ties the id to the phase |
+| `phase_names` | none | `{0 = "Foundations"}` labels for the view |
+| `planners` | `["human"]` | identities allowed to add, move and re-link tasks |
+| `reviewer` | `"reviewer"` | identity whose `review_result` closes a task |
+| `owners` | any | restrict `owner` values |
+| `require_review` | `true` | `false`: `done` needs only a green verification |
+| `review_delay_seconds` | `60` | minimum time between verification and review |
+| `[quality]` | none | named gates for the `quality_check` tool, each a list of argv arrays |
+
+The project root is `TASKGATE_ROOT` if set, otherwise the nearest ancestor of the working directory that has
+`taskgate.toml` or `.taskgate/`.
+[examples/embersail.toml](examples/embersail.toml) reproduces a stricter real-world setup (ids `P<phase>-NN`,
+architect/human planners) to show the engine is not tied to one convention.
+
+## Commands
+
+`init`, `validate`, `render [--check]`, `next`, `list [--status]`, `claim`, `update`, `add`, `sort`, `move`,
+`depends`, `mcp`, `config-snippet`. `taskgate <command> --help` lists the flags.
+
+Recording evidence, in separate calls:
+
+```sh
+taskgate update T-1 --verification-result '{"ok": true}' --by dev
+taskgate update T-1 --status in_review --by dev
+taskgate update T-1 --status done --by reviewer \
+  --review-result '{"ok": true, "by": "reviewer", "checks": ["pytest -q"]}'
+```
+
+## MCP tools
+
+`task_list`, `task_next`, `task_validate` (read-only, so clients can skip the approval prompt), `task_claim`,
+`task_update`, `task_add`, `task_move`, `task_depends`, `task_sort`, `task_render` and `quality_check`.
+Tool failures come back as `isError` results rather than protocol errors, so an agent sees the reason.
+
+The server speaks newline-delimited JSON-RPC 2.0 over stdio. Run it with `taskgate mcp` or `taskgate-mcp`.
+
+## Development
+
+```sh
+python -m pip install -e ".[dev]"
+ruff check . && mypy && pytest
+```
+
+## Releasing
+
+Pushing to `main` runs the tests on Linux, macOS and Windows and builds the package. If `version` in
+`pyproject.toml` has no `v<version>` tag yet, the workflow publishes to PyPI through trusted publishing and
+creates the tag and GitHub release. To release: bump `version` in `pyproject.toml` and
+`src/taskgate/__init__.py` (a test keeps them equal), add a changelog entry, merge to `main`.
+
+One-time setup, either way: a GitHub environment named `pypi`. Then either store a PyPI API token as the
+repository secret `PYPI_API_TOKEN` (the first release of a new project needs an account-wide token; narrow it
+to the project afterwards), or add a (pending) trusted publisher on PyPI for this repository, workflow
+`ci.yml`, environment `pypi`. With the secret set it is used; without it the workflow falls back to trusted
+publishing.
+
+## Status
+
+Alpha. Not included: synchronization with a forge (GitLab/GitHub issues). It originated in the Embersail
+project's task tooling.
+
+## License
+
+MIT

taskgate-0.1.0/README.md

@@ -0,0 +1,128 @@
+# taskgate
+
+A task registry that makes "done" mean something. Tasks move through a strict status flow, and the
+transitions that matter are gated by evidence: a task enters review only with a green verification, and
+closes only with a review from a *different* identity that lists the commands it checked. It ships as a CLI
+and as an MCP server, so coding agents (Claude Code, Codex, VS Code Copilot, Cursor, Gemini CLI) and humans
+work from the same registry.
+
+- stdlib-only, no runtime dependencies; Python 3.11+; Linux, macOS and Windows
+- state is plain files you commit: `tasks.json` (source of truth), an append-only `tasks.log.jsonl` and a
+  generated `tasks.md`
+- one code path: every MCP tool calls the same CLI command a human would run
+
+## Quick start
+
+```sh
+cd your-project
+uvx taskgate init
+uvx taskgate add --id T-1 --title "Parse the header" --verification-cmd "pytest tests/test_header.py"
+uvx taskgate next              # which task may start now
+uvx taskgate claim T-1 --by dev
+```
+
+Add it to your agent (prints a ready-to-paste block; see [docs/clients.md](docs/clients.md)):
+
+```sh
+uvx taskgate config-snippet claude     # also: vscode, codex, cursor, gemini, generic
+```
+
+From a checkout instead of PyPI: `uvx --from /path/to/taskgate taskgate ...`, or
+`taskgate config-snippet claude --from /path/to/taskgate`.
+
+## The flow
+
+```
+draft -> planned -> in_progress -> in_review -> done
+                        |  ^           |
+                        v  |           +--> in_progress   (review rejected)
+                      blocked
+any non-terminal status -> cancelled
+```
+
+| Rule | What it enforces |
+| --- | --- |
+| order | `claim` works only on tasks whose predecessors in the registry are `done` or `cancelled` |
+| phase gate | a task in a later phase waits until every earlier phase is closed and the registry validates |
+| dependencies | `depends_on` tasks must be `done` before the task can start |
+| verification | `in_review` and `done` need a green `verification_result`; the tool stamps who recorded it and when |
+| review | `done` needs a green `review_result` from the reviewer identity, different from the verifier, listing `checks`, recorded after a delay, in the same call as the closing update |
+| fresh evidence | a new verification voids an earlier review; results are never accepted together in one call |
+| planning | adding, moving and re-linking tasks is limited to the `planners` identities; started work is never reordered |
+
+Identities (`--by`, or the `TASKGATE_BY` environment variable, default `human`) are *declared by the caller*.
+This is a process barrier that keeps roles apart and leaves a trail in the log; it is not authentication.
+
+## Configuration
+
+Optional `taskgate.toml` in the project root; every key has a default
+([examples/taskgate.toml](examples/taskgate.toml)).
+
+| Key | Default | Meaning |
+| --- | --- | --- |
+| `data_dir` | `.taskgate` | where `tasks.json`, `tasks.log.jsonl`, `tasks.md` live |
+| `title` | `Tasks` | heading of the Markdown view |
+| `id_pattern` | `^[A-Za-z][A-Za-z0-9]*-\d+$` | task id regex; a named group `(?P<phase>\d+)` ties the id to the phase |
+| `phase_names` | none | `{0 = "Foundations"}` labels for the view |
+| `planners` | `["human"]` | identities allowed to add, move and re-link tasks |
+| `reviewer` | `"reviewer"` | identity whose `review_result` closes a task |
+| `owners` | any | restrict `owner` values |
+| `require_review` | `true` | `false`: `done` needs only a green verification |
+| `review_delay_seconds` | `60` | minimum time between verification and review |
+| `[quality]` | none | named gates for the `quality_check` tool, each a list of argv arrays |
+
+The project root is `TASKGATE_ROOT` if set, otherwise the nearest ancestor of the working directory that has
+`taskgate.toml` or `.taskgate/`.
+[examples/embersail.toml](examples/embersail.toml) reproduces a stricter real-world setup (ids `P<phase>-NN`,
+architect/human planners) to show the engine is not tied to one convention.
+
+## Commands
+
+`init`, `validate`, `render [--check]`, `next`, `list [--status]`, `claim`, `update`, `add`, `sort`, `move`,
+`depends`, `mcp`, `config-snippet`. `taskgate <command> --help` lists the flags.
+
+Recording evidence, in separate calls:
+
+```sh
+taskgate update T-1 --verification-result '{"ok": true}' --by dev
+taskgate update T-1 --status in_review --by dev
+taskgate update T-1 --status done --by reviewer \
+  --review-result '{"ok": true, "by": "reviewer", "checks": ["pytest -q"]}'
+```
+
+## MCP tools
+
+`task_list`, `task_next`, `task_validate` (read-only, so clients can skip the approval prompt), `task_claim`,
+`task_update`, `task_add`, `task_move`, `task_depends`, `task_sort`, `task_render` and `quality_check`.
+Tool failures come back as `isError` results rather than protocol errors, so an agent sees the reason.
+
+The server speaks newline-delimited JSON-RPC 2.0 over stdio. Run it with `taskgate mcp` or `taskgate-mcp`.
+
+## Development
+
+```sh
+python -m pip install -e ".[dev]"
+ruff check . && mypy && pytest
+```
+
+## Releasing
+
+Pushing to `main` runs the tests on Linux, macOS and Windows and builds the package. If `version` in
+`pyproject.toml` has no `v<version>` tag yet, the workflow publishes to PyPI through trusted publishing and
+creates the tag and GitHub release. To release: bump `version` in `pyproject.toml` and
+`src/taskgate/__init__.py` (a test keeps them equal), add a changelog entry, merge to `main`.
+
+One-time setup, either way: a GitHub environment named `pypi`. Then either store a PyPI API token as the
+repository secret `PYPI_API_TOKEN` (the first release of a new project needs an account-wide token; narrow it
+to the project afterwards), or add a (pending) trusted publisher on PyPI for this repository, workflow
+`ci.yml`, environment `pypi`. With the secret set it is used; without it the workflow falls back to trusted
+publishing.
+
+## Status
+
+Alpha. Not included: synchronization with a forge (GitLab/GitHub issues). It originated in the Embersail
+project's task tooling.
+
+## License
+
+MIT

taskgate-0.1.0/pyproject.toml

@@ -0,0 +1,57 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "taskgate"
+version = "0.1.0"
+description = "Gated task registry with an MCP server: strict status flow, verification and review evidence, for Claude Code, Codex, VS Code Copilot and other MCP clients."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+authors = [{ name = "prachwal" }]
+keywords = ["mcp", "model-context-protocol", "task-tracker", "agents", "workflow", "claude-code", "codex", "copilot"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Software Development :: Quality Assurance",
+]
+dependencies = []
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "ruff>=0.6", "mypy>=1.11"]
+
+[project.urls]
+Homepage = "https://github.com/prachwal/taskgate"
+Repository = "https://github.com/prachwal/taskgate"
+Issues = "https://github.com/prachwal/taskgate/issues"
+
+[project.scripts]
+taskgate = "taskgate.cli:run"
+taskgate-mcp = "taskgate.mcp.server:run"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"
+
+[tool.ruff]
+line-length = 130
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+files = ["src"]

taskgate-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

taskgate-0.1.0/src/taskgate/__init__.py

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

taskgate-0.1.0/src/taskgate/__main__.py

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

taskgate-0.1.0/src/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-0.1.0/src/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-0.1.0/src/taskgate/commands/__init__.py

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

taskgate-0.1.0/src/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