taskops-cli 0.2.0__py3-none-any.whl

taskops/transports/mcp/protocol.py

@@ -0,0 +1,83 @@
+"""JSON-RPC, as a pure function: a message in, a response object out.
+
+No socket and no stdin, so every method is testable by calling it — the transport work is
+tested once, in `server`, instead of by every case that wants to know what `tools/call`
+answers.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ..._version import __version__
+from .answers import Answer, failure
+from .tools import listing
+
+__all__ = ["PROTOCOL", "INSTRUCTIONS", "respond"]
+
+PROTOCOL = "2024-11-05"
+
+# Returned by `initialize` and injected into the calling agent's context ONCE. With tool
+# search on, the SCHEMAS stay deferred until the agent goes looking, so this is the only
+# taskops text a session is guaranteed to see. What belongs here is the mental model and
+# the routing BETWEEN tools — never a restatement of each tool's own description — and it
+# must stay short, because it costs context in every session that loads this server.
+INSTRUCTIONS = """taskops is the shared task list for this repository. Tasks persist across sessions, machines and developers, so work you claim is work nobody else will start.
+
+The loop, and it is short:
+- taskops_next — claim work. Returns the spec, the branch to create, and a warning if another agent is editing the same files. Do this before coding, not after.
+- taskops_update — progress, a comment, or `status=done`. `mentions` sends a message to another actor's agent; they see it within one tool call.
+- taskops_ask — read a task in full before you touch a file you did not claim.
+
+Two rules the server enforces rather than suggests. A commit must be on the claimed task's branch (`tk/<id>/<slug>`) — the trailer is added for you. And `done` requires a commit bound to the task, so the board cannot say finished about work that does not exist.
+
+Your claim is a LEASE: every taskops call renews it, and if your process dies it expires and the task returns to the queue. If a write is refused for a missing lease, claim again — do not work around it."""
+
+
+def respond(message: dict[str, Any]) -> dict[str, Any] | None:
+    """The response to one message, or None if it deserves none.
+
+    A message without an id is a notification, and answering one is a protocol violation
+    some hosts read as a broken server. Returning before any work also means a notification
+    can never cost a database open.
+    """
+    mid = message.get("id")
+    if mid is None:
+        return None
+    return {"jsonrpc": "2.0", "id": mid, "result": _result(message)}
+
+
+def _result(message: dict[str, Any]) -> dict[str, Any]:
+    method = message.get("method", "")
+    if method == "initialize":
+        return {"protocolVersion": PROTOCOL, "capabilities": {"tools": {}},
+                "serverInfo": {"name": "taskops", "version": __version__},
+                "instructions": INSTRUCTIONS}
+    if method == "tools/list":
+        return {"tools": listing()}
+    if method == "tools/call":
+        params: dict[str, Any] = message.get("params") or {}
+        return _content(_call(params))
+    return {}
+
+
+def _call(params: dict[str, Any]) -> Answer:
+    """The engine is imported HERE, not at module scope.
+
+    A host lists the tools before it asks anything, and that handshake must not pay for a
+    sqlite connection or a git subprocess.
+    """
+    from .dispatch import call_tool
+
+    try:
+        return call_tool(str(params.get("name", "")),
+                         dict(params.get("arguments") or {}))
+    except Exception as err:                      # noqa: BLE001 — last resort
+        # `call_tool` handles every failure it can name; anything reaching here is a bug,
+        # and the agent still needs a sentence rather than a hang.
+        return failure(f"{type(err).__name__}: {err}")
+
+
+def _content(result: Answer) -> dict[str, Any]:
+    payload: dict[str, Any] = {"content": [{"type": "text", "text": result.text}]}
+    return {**payload, "isError": True} if result.failed else payload

taskops/transports/mcp/schema.py

@@ -0,0 +1,50 @@
+"""A params contract -> the JSON Schema a host validates against.
+
+Generated, never written twice. The alternative — a JSON literal beside the TypedDict — is
+two declarations of one thing, and the one that drifts is always the schema, because
+nothing type-checks it: the tool keeps advertising a parameter the dispatch stopped
+reading, and the agent keeps sending it.
+"""
+
+from __future__ import annotations
+
+from typing import Any, get_args, get_type_hints
+
+__all__ = ["json_schema"]
+
+_JSON_TYPES: dict[Any, str] = {str: "string", bool: "boolean", int: "integer",
+                               float: "number"}
+
+
+def json_schema(params: type[Any]) -> dict[str, Any]:
+    """One tool's `inputSchema`, derived from its TypedDict.
+
+    Required-ness comes from the TypedDict's own totality rather than a hand-written list,
+    so an optional key cannot be advertised as required by whoever forgot the second edit.
+    See `contracts/__init__` for why that totality has to be spelled with a class split.
+    """
+    required: frozenset[str] = getattr(params, "__required_keys__", frozenset())
+    hints = get_type_hints(params, include_extras=True)
+    return {"type": "object",
+            "properties": {name: _property(hint) for name, hint in hints.items()},
+            "required": sorted(required)}
+
+
+def _property(hint: Any) -> dict[str, Any]:
+    """One field: its JSON type, its allowed values, and what it is for."""
+    described = getattr(hint, "__metadata__", ())
+    annotation = getattr(hint, "__origin__", hint) if described else hint
+    schema: dict[str, Any] = {"description": " ".join(str(d) for d in described)}
+    if getattr(annotation, "__origin__", None) is list or annotation is list:
+        # An array of objects, with the ITEM shape left OPEN on purpose: `plan` accepts
+        # the habitual spellings a model reaches for (a bare `after` instead of a list, a
+        # comma-separated `files` string), and a schema that pinned the canonical forms
+        # would have the host reject the very inputs `_entry` goes out of its way to read.
+        return {**schema, "type": "array", "items": {"type": "object"}}
+    choices = list(get_args(annotation))
+    if choices and all(isinstance(c, (str, int, bool)) for c in choices):
+        # A Literal: the allowed values ARE the documentation. Rendered as a bare string,
+        # the agent can send anything and only finds out at dispatch.
+        return {**schema, "type": _JSON_TYPES.get(type(choices[0]), "string"),
+                "enum": choices}
+    return {**schema, "type": _JSON_TYPES.get(annotation, "string")}

taskops/transports/mcp/server.py

@@ -0,0 +1,49 @@
+"""The stdio loop: one JSON object per line in, one response per line out.
+
+Everything protocol-shaped happens in `protocol`; what is left here is the wire. Written
+against two streams rather than sys.stdin/sys.stdout directly, so the loop's real behaviour
+— a malformed line, a notification, the order of replies — is testable without a subprocess.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from typing import IO, Any, cast
+
+from .protocol import respond
+
+__all__ = ["serve", "main"]
+
+
+def serve(reader: IO[str], writer: IO[str]) -> None:
+    """Answer messages until the input ends.
+
+    A line that is not a JSON object is SKIPPED, not fatal: a host that writes one piece of
+    garbage should not lose the rest of the session, and there is no id to answer it with
+    anyway.
+    """
+    for raw in reader:
+        line = raw.strip()
+        if not line:
+            continue
+        message = _parse(line)
+        reply = respond(message) if message is not None else None
+        if reply is not None:
+            writer.write(json.dumps(reply) + "\n")
+            writer.flush()
+
+
+def _parse(line: str) -> dict[str, Any] | None:
+    try:
+        message: object = json.loads(line)
+    except json.JSONDecodeError:
+        return None
+    return cast("dict[str, Any]", message) if isinstance(message, dict) else None
+
+
+def main() -> int:
+    """`python -m taskops.transports.mcp`, and what a host registers:
+    `claude mcp add taskops -- python3 -m taskops.transports.mcp`."""
+    serve(sys.stdin, sys.stdout)
+    return 0

taskops/transports/mcp/tools.py

@@ -0,0 +1,66 @@
+"""The tools an agent can see — five, and each one earns its slot.
+
+Every tool costs the calling agent context and a routing decision, so the surface carries
+only what taskops alone can do: turn a plan into a persistent graph (`plan`), hand out work
+without two agents taking the same piece (`next`), record what happened and tell somebody
+(`update`), read a task's whole context (`ask`), and generate the report nobody wants to
+write (`report`).
+
+There is deliberately no sixth tool for messaging. Sending is `update` with `mentions`,
+because a message about a task belongs in that task's thread — a separate chat tool would
+produce conversations nobody can find later. Receiving is not a tool at all: the inbox rides
+along with `next` and `ask`, and hooks deliver it between calls.
+
+The description text lives in `_descriptions`, for the same reason the SQL lives in
+`storage/_ddl` — reviewing a change here should not mean re-reading sixty lines of prose.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from ...contracts.tools import (
+    AskParams,
+    DispatchParams,
+    NextParams,
+    PlanParams,
+    RecoverParams,
+    ReportParams,
+    UpdateParams,
+)
+from . import _descriptions as text
+from .schema import json_schema
+
+__all__ = ["Tool", "TOOLS", "listing"]
+
+
+@dataclass(frozen=True, slots=True)
+class Tool:
+    """A name, what it is for, and the contract its arguments satisfy."""
+
+    name: str
+    description: str
+    params: type[Any]
+
+
+TOOLS: tuple[Tool, ...] = (
+    Tool("taskops_next", text.NEXT, NextParams),
+    Tool("taskops_update", text.UPDATE, UpdateParams),
+    Tool("taskops_ask", text.ASK, AskParams),
+    Tool("taskops_plan", text.PLAN, PlanParams),
+    Tool("taskops_dispatch", text.DISPATCH, DispatchParams),
+    Tool("taskops_recover", text.RECOVER, RecoverParams),
+    Tool("taskops_report", text.REPORT, ReportParams),
+)
+"""Ordered by how often an agent needs them, not alphabetically.
+
+With tool search on, a host may surface only the first few names, so `next` and `update` —
+the two that carry every session — must not sit below the planning tool a session uses once.
+"""
+
+
+def listing() -> list[dict[str, Any]]:
+    """The `tools/list` payload: description and schema, generated together."""
+    return [{"name": tool.name, "description": tool.description,
+             "inputSchema": json_schema(tool.params)} for tool in TOOLS]

taskops/usecases/__init__.py

@@ -0,0 +1,56 @@
+"""Layer 5 — one module per verb, sync, returning contracts.
+
+Every transport calls THESE, so a behaviour is implemented once and three surfaces
+cannot drift apart. `tests/architecture` enforces the other half of that: a transport
+may not import `storage` or `engine` directly, which is what stops a fourth place where
+a decision lives.
+
+Sync all the way down. taskops is sqlite and a state machine; the http edge may be
+async and calls in from a threadpool, but there is no async twin of the engine.
+"""
+
+from __future__ import annotations
+
+from . import narration
+from ._project import locate
+from ._range import Selector, parse_date
+from .ask import ask, search
+from .claim import next_task
+from .dispatch import DispatchResult, dispatch
+from .dossier import digest, read_report, report_path, write_report
+from .edit import edit
+from .exchange import MAX_BATCH, MAX_PAGE, accept_events, pull_events
+from .feed import follow, is_wire
+from .guard import Verdict, check_command, check_commit
+from .index import report_index
+from .ingest import ingest_branch, ingest_commit
+from .log import session_log
+from .plan import plan
+from .pushpull import Exchange, pull, push
+from .recover import Recovered, recover
+from .remote import add_remote, read_remote, remove_remote, require_remote
+from .report import activity, board, day, fleet, period, standup
+from .reportfile import read_report_file, write_report_file
+from .session import Brief, brief, checkout, inbox, track
+from .setup import InitReport, init
+from .sync import rebuild, sync
+from .update import update
+
+__all__ = [
+    # the five MCP tools
+    "plan", "next_task", "update", "edit", "ask", "search", "board", "standup", "fleet", "activity",
+    "day", "period", "Selector",
+    "dispatch", "DispatchResult", "write_report", "read_report", "digest", "report_path",
+    "report_index", "recover", "Recovered",
+    # the remote exchange: events and report files over HTTP
+    "accept_events", "pull_events", "MAX_BATCH", "MAX_PAGE",
+    "read_report_file", "write_report_file",
+    # the CLI verbs the hooks call
+    "init", "InitReport", "check_commit", "check_command", "Verdict",
+    "ingest_commit", "ingest_branch",
+    "brief", "Brief", "inbox", "checkout", "track", "sync", "rebuild", "follow", "locate", "session_log",
+    # the remote: one server, and the two verbs that converge with it
+    "add_remote", "read_remote", "require_remote", "remove_remote", "push", "pull", "Exchange",
+    # the live narration: started in the background, watched on the wire
+    "narration", "is_wire", "parse_date",
+]

taskops/usecases/_entry.py

@@ -0,0 +1,84 @@
+"""Reading one plan entry — the fields, as a model actually writes them.
+
+Split from `plan` by what the reader has to know: that module builds a graph, this one
+decides what a caller meant when it packaged a field the way the schema did not name.
+Every tolerance here is a habit observed in the field, not a defensive reflex — and each
+one is the difference between rejecting a correct plan over a bracket and accepting it.
+
+Nothing here guesses at a MEANING. A title is required and stays required; what gets
+tolerated is only shape: a string where a list was declared, one value where a list of
+one was.
+"""
+
+from __future__ import annotations
+
+from typing import Any, cast
+
+__all__ = ["title_of", "priority_of", "optional", "strings", "references", "blocked_ids"]
+
+DEFAULT_PRIORITY = 2
+"""The middle of the 0-3 band. A caller with no opinion about urgency has not said
+"urgent", and defaulting to 0 would make every unconsidered task jump the queue."""
+
+
+def title_of(entry: dict[str, Any]) -> str:
+    return str(entry.get("title", "")).strip()
+
+
+def priority_of(entry: dict[str, Any]) -> int:
+    """`bool` is excluded explicitly: `True == 1` in Python, so a caller that sent
+    `priority: true` would silently get an urgent task."""
+    found = entry.get("priority")
+    if isinstance(found, bool) or not isinstance(found, int):
+        return DEFAULT_PRIORITY
+    return found
+
+
+def optional(entry: dict[str, Any], key: str) -> str | None:
+    found = entry.get(key)
+    return str(found) if isinstance(found, str) and found.strip() else None
+
+
+def strings(entry: dict[str, Any], key: str) -> list[str]:
+    """A list field, tolerating the comma-separated string a model reaches for anyway."""
+    found: object = entry.get(key)
+    if isinstance(found, str):
+        return [part.strip() for part in found.split(",") if part.strip()]
+    if isinstance(found, list):
+        items = cast("list[object]", found)
+        return [str(item).strip() for item in items if str(item).strip()]
+    return []
+
+
+def blocked_ids(entry: dict[str, Any]) -> list[str]:
+    """`blocks` — the EXISTING tasks this new card must finish before.
+
+    The inverse of `after`, and it exists for one flow: an agent mid-task discovers a prerequisite
+    and needs "create this card AND make my current task wait for it" to be ONE call. Two calls meant
+    two chances to do only the first, and the missing half is always the edge — leaving a card nobody
+    is waiting for and a task that looks ready and is not.
+
+    Ids only, never indexes: a card cannot block one created after it in the same batch without a
+    cycle, so accepting an index here would only ever be a mistake worth rejecting.
+    """
+    found: object = entry.get("blocks")
+    if isinstance(found, str):
+        return [part.strip() for part in found.split(",") if part.strip()]
+    if isinstance(found, list):
+        items = cast("list[object]", found)
+        return [str(item).strip() for item in items if str(item).strip()]
+    return []
+
+
+def references(entry: dict[str, Any]) -> list[object]:
+    """The `after` field, however it was packaged.
+
+    A bare value is wrapped: a model with one dependency writes `after: 0` about as
+    often as `after: [0]`, and refusing the first rejects a correct plan over a bracket.
+    Returned as `object` on purpose — an index and a task id are both legal, and
+    telling them apart is `plan`'s decision, not this module's.
+    """
+    found: object = entry.get("after")
+    if found is None or found == "":
+        return []
+    return list(cast("list[object]", found)) if isinstance(found, list) else [found]

taskops/usecases/_facts.py

@@ -0,0 +1,49 @@
+"""Gathering what the state machine is allowed to know.
+
+`engine.machine` holds guards that are pure functions of `Facts`, which is what lets every rule be
+tested from literals with no database. Something still has to READ those facts, and this is it — the
+one place that turns a task plus a store plus git into the record the machine decides on.
+
+Its own module because the reading is not the deciding. `update` orchestrates; the machine judges;
+this fetches. When a guard needs a new fact, the change is one function here and one line there.
+"""
+
+from __future__ import annotations
+
+from .._clock import now
+from ..contracts import Task
+from ..engine import Facts, branch_state, open_children
+from ..storage import Store
+
+__all__ = ["facts_for", "unpushed_on"]
+
+
+def facts_for(store: Store, task: Task, actor: str, *, no_code: bool,
+              justification: str) -> Facts:
+    """Everything the guards may ask about, read once."""
+    lease = store.leases.get(task["id"])
+    return Facts(
+        task=task, actor=actor,
+        has_live_lease=store.leases.held_by(task["id"], actor, now()),
+        commits=len(store.events.of_task(task["id"], kinds=("commit",))),
+        open_children=open_children(store, task["id"]),
+        no_code=no_code, justification=justification,
+        unpushed=unpushed_on(store, lease["branch"] if lease else ""))
+
+
+def unpushed_on(store: Store, branch: str) -> int:
+    """Commits on this branch that no remote has. 0 when there is no branch or no remote.
+
+    Read at CLOSE time rather than stored: it changes every time anybody pushes, so a cached answer
+    would be wrong more often than right.
+
+    A branch with no upstream returns 0 and not "everything", deliberately. Git has nothing to
+    compare against there, so any number would be invented — and a solo developer with no remote at
+    all would otherwise see every task reported as unpushed forever.
+    """
+    if not branch:
+        return 0
+    state = branch_state(store.root, branch)
+    if not state["exists"] or not state["upstream"]:
+        return 0
+    return state["ahead"]

taskops/usecases/_freeing.py

@@ -0,0 +1,93 @@
+"""Freeing one stuck card, and writing down what its worker left behind.
+
+Split from `recover` because that module DECIDES what is stuck and this one does the freeing. The note
+each of these writes is the part that matters most: a card that comes back with no explanation looks
+like a card nobody ever started, and the next agent rewrites from zero the file sitting in a directory
+two levels down. It names the PATH — "partial work exists" sends an agent looking, a path sends it
+reading.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from .._clock import now
+from ..contracts import Lease
+from ..engine import record
+from ..engine.gitstate import porcelain
+from ..engine.worker import worktree_for
+from ..storage import Store
+
+__all__ = ["release_lease", "unassign", "Stuck"]
+
+
+class Stuck:
+    """One card that was recovered, and what was left behind in its worktree."""
+
+    def __init__(self, *, task: str, actor: str, silent_for: float, commits: int,
+                 leftovers: list[str], tree: Path) -> None:
+        self.task = task
+        self.actor = actor
+        self.silent_for = silent_for
+        self.commits = commits
+        """Commits already bound to the card. These SURVIVE — they are in git."""
+
+        self.leftovers = leftovers
+        """Uncommitted paths in the worker's worktree. The part that is easy to lose."""
+
+        self.tree = tree
+
+
+def release_lease(store: Store, lease: Lease, who: str, quiet: float) -> Stuck:
+    """Hand one card back, and write down what its worker left in the tree.
+
+    The comment is the whole point of doing this here rather than leaving it to the lease timer: a
+    card that came back with no explanation looks like a card nobody ever started, and the next agent
+    rewrites from zero the file that is sitting in a directory two levels down.
+    """
+    tree = worktree_for(store.root, store.tasks.need(lease["task"]))
+    leftovers = porcelain(tree)
+    commits = len(store.events.of_task(lease["task"], kinds=("commit",)))
+    store.leases.release(lease["task"])
+    store.tasks.set_status(lease["task"], "ready", when=now())
+    store.tasks.set_assignee(lease["task"], "", when=now())
+    record(store, task=lease["task"], actor=who, kind="released",
+           body={"text": _note(lease, quiet, commits, leftovers, tree),
+                 "recovered_from": lease["actor"], "leftovers": leftovers})
+    return Stuck(task=lease["task"], actor=lease["actor"], silent_for=quiet,
+                 commits=commits, leftovers=leftovers, tree=tree)
+
+
+def unassign(store: Store, task_id: str, assignee: str, who: str) -> Stuck:
+    """Free a card whose worker was never started. Same bookkeeping, different reason."""
+    tree = worktree_for(store.root, store.tasks.need(task_id))
+    leftovers = porcelain(tree)
+    commits = len(store.events.of_task(task_id, kinds=("commit",)))
+    store.tasks.set_assignee(task_id, "", when=now())
+    record(store, task=task_id, actor=who, kind="released",
+           body={"text": f"Recovered: assigned to {assignee}, which never started. "
+                         f"Back in the open pool."
+                         + (f" UNCOMMITTED work survives in {tree}: {', '.join(leftovers)}."
+                            if leftovers else ""),
+                 "recovered_from": assignee, "leftovers": leftovers, "never_started": True})
+    return Stuck(task=task_id, actor=assignee, silent_for=0.0, commits=commits,
+                 leftovers=leftovers, tree=tree)
+
+
+def _note(lease: Lease, quiet: float, commits: int, leftovers: list[str],
+          tree: Path) -> str:
+    """The comment left on the card. Written for whoever picks it up next.
+
+    It names the PATH, not just the fact that something is there: "partial work exists" sends the
+    next agent looking, and a path sends it reading.
+    """
+    lines = [f"Recovered: {lease['actor']} went silent for {int(quiet // 60)}m and the card was "
+             f"handed back."]
+    if commits:
+        lines.append(f"{commits} commit(s) are already bound to it and are safe in git.")
+    if leftovers:
+        lines.append(f"UNCOMMITTED work survives in {tree}: {', '.join(leftovers)}. "
+                     f"Read it before starting from scratch.")
+    else:
+        lines.append("Nothing uncommitted was left behind.")
+    return " ".join(lines)

taskops/usecases/_gitignore.py

@@ -0,0 +1,94 @@
+"""The block `taskops init` writes into `.gitignore`, and how it grows without being rewritten.
+
+Its own module because it stopped being a detail of init the moment it started guarding a
+SECRET. The rule this file encodes is: everything under `.taskops/` is ignored except the
+event log — which is the whole replication story — and the list is written out path by path
+rather than as `.taskops/*` plus exceptions, so that a person reading it can see what each
+line is for.
+
+That explicitness has a cost the token found first: a new file under `.taskops/` is TRACKED
+by default. `remote.json` holds a bearer, and a token in git history is still a token after
+somebody deletes the file. Hence `_UPGRADES` — a project initialised by an older taskops must
+gain that line the next time init runs, or upgrading in place is one `git add .` from a leak.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from ..storage import PROJECT_DIR
+
+__all__ = ["ignore"]
+
+MARKER = "# taskops"
+
+REPORTS_NOTE = f"# {PROJECT_DIR}/reports/ is COMMITTED — a written dossier is not derived state"
+"""A COMMENT, not a rule, and that is the point.
+
+`reports/` is tracked, so the correct entry here is no entry at all — but "no entry" is
+indistinguishable from an oversight, and the next person tidying this block would add
+`{PROJECT_DIR}/*` and untrack every report in the project. The line says why the hole exists.
+"""
+
+REMOTE_RULE = f"{PROJECT_DIR}/remote.json"
+"""The remote's URL and its BEARER TOKEN. The one line here that guards a secret.
+
+Everything else is ignored because committing it would be noise; this one because committing
+it would be a leak that outlives the commit. The file is also written 0600
+(`usecases/remote.py`) — belt and braces, on purpose, because the two failures are different:
+the mode stops another account on this machine, the ignore stops the whole internet.
+"""
+
+GUIDE_NOTE = f"{PROJECT_DIR}/GUIDE.md"
+"""Ignored rather than committed, which looks wrong at first.
+
+It is GENERATED: it ships inside the package and init rewrites it every run, so it always
+describes the version of taskops actually installed. Tracking a file that a command overwrites
+would leave `git status` dirty after every init, and two developers on different versions would
+fight over its contents forever. It also removed a real merge conflict — two clones that each
+ran `taskops init` could not pull from one another, because the incoming commit carried files
+both sides had independently created untracked.
+"""
+
+BLOCK = f"""
+{MARKER} — commit events.jsonl and NOTHING else under {PROJECT_DIR}/
+{PROJECT_DIR}/db.sqlite
+{PROJECT_DIR}/db.sqlite-wal
+{PROJECT_DIR}/db.sqlite-shm
+{GUIDE_NOTE}
+{PROJECT_DIR}/workers/
+{PROJECT_DIR}/trees/
+{REMOTE_RULE}
+{REPORTS_NOTE}
+"""
+
+_UPGRADES = (REPORTS_NOTE, REMOTE_RULE)
+"""Lines added to the block AFTER projects existed with it. Order is the order they land in."""
+
+
+def ignore(root: Path) -> None:
+    """Write the block, once. Matched on the MARKER rather than on the paths.
+
+    A developer may reformat those lines, and appending a duplicate block on every init is
+    how a `.gitignore` becomes forty lines of the same thing.
+    """
+    path = root / ".gitignore"
+    current = path.read_text(encoding="utf-8") if path.is_file() else ""
+    if MARKER in current:
+        _upgrade(path, current)
+        return
+    separator = "" if current.endswith("\n") or not current else "\n"
+    path.write_text(current + separator + BLOCK, encoding="utf-8")
+
+
+def _upgrade(path: Path, current: str) -> None:
+    """Append whatever this taskops adds to a block an older one wrote. Idempotent.
+
+    Appending rather than rewriting the block: the developer may have edited those lines, and
+    a tool that replaces a file it does not own loses whatever they added.
+    """
+    missing = [line for line in _UPGRADES if line not in current]
+    if not missing:
+        return
+    separator = "" if current.endswith("\n") else "\n"
+    path.write_text(current + separator + "\n".join(missing) + "\n", encoding="utf-8")