Close a period (YYYYQn) and record its retrospective — call when its work is over.

Refuses while any task is still todo or in_progress. Stores `result_markdown` as the
period's `result` and marks its milestone, if it has one, done.

The retrospective is written in the user's language, stays under ~30 lines and holds
judgment and reasons only — summary vs goal, what landed and what did not, carried-over tasks
(old id -> new id), lessons.
Calling it again on a closed period rewrites the retrospective and changes nothing else.

Register a new project — once per codebase, before any planning happens.

`key` is the task-id prefix (2-5 uppercase letters, e.g. DLY); `description` is one
line saying what the project is, in the user's language (shown on the dashboard cards);
`repo` is where its code lives (owner/name or a URL). Status starts as active.

A fresh project takes tasks at once: create_task opens the current quarter. The plan
(set_overview, upsert_milestone) is optional and written with the user.

Create a task — one issue/branch-sized unit of work — with status todo.

The id is assigned from the project-global sequence and never reused. `period` is
YYYYQn: the current quarter (in the server's time zone) opens by itself if it is not
open yet, and the answer then carries `opened`; any other quarter must already be open
(open_period). Nothing else — no overview, no milestone — has to exist first.

`title` is a short English imperative ("Add multi-select status filter") — it is what
every reader sees, so it has to say the whole thing.

`content` is optional: one line, at most 300 characters, English. It answers **why this
task exists** — the pressure that made it necessary, or the scope you deliberately left
out. It is written now, before the work, so it cannot describe the approach or the
result: the approach you choose, and why, goes in the commit; what proves the work done
is `check`, which transition_task takes when you finish. Do not restate the title here:
a note that only rephrases it tells the next agent nothing. Line breaks are folded into
spaces; a longer text is rejected, not cut.

`tags` are free-form labels ("frontend", "bug", "infra"): up to 8 per task, 24
characters each, no commas. Reuse the wording already in use on the project
(list_tasks shows it) instead of coining a new spelling for the same thing.

`depends_on` lists the task ids this one builds on — the *earlier* work whose result it
needs, or the task that handed it this scope. Full ids, other projects allowed. It
points backwards only: there is no forward list, so a task never has to be updated
because a later one appeared. It is a pointer, not a lock — nothing is blocked, and
`list_tasks` / `get_status` merely flag the entries not yet done as `waiting_on`.

Read a closed period's (YYYYQn) retrospective — the `result` markdown close_period
wrote. Errors while the period is still open; get_status says which ones are closed.

Read a project's plan as written: yearly overviews (goal, now, target, checklist),
quarterly milestones, and the names of its periods.

Goals only, no counts — get_status for progress and the current period, list_tasks for
the tasks themselves. Timestamps (`meta`) are left out unless `include_meta` is set.

The resume: everything an agent needs to pick a project up cold, in one call. The
latest year's overview (goal / now / target / checklist); per period its milestone goal
and status (a period without a milestone has no goal and reports active while open, done
once closed), task counts by status, whether it is closed, and `open_tasks` — every
todo / blocked / in_progress task with its title, tags, branch, one-line content and
`waiting_on`; and `recent_done` — the ten most recently finished tasks across every period, newest
first, each with its content, its `check` and when it completed. Closed periods are
included.

`recent_done` is what the project already has, in the words of whoever built it, and
`check` is what they said proves it. Both are claims: confirm against the code before
building on one. Older finished work and cancelled tasks are list_tasks; the plan as
written is get_roadmap.

Call it once at the start of a session; there is nothing to poll for afterwards.

Read one task in full by id (DLY-042) — the project comes from the prefix, so no key
is needed. Returns the record with its period. Use this instead of list_tasks whenever
you already know the id; search_tasks when you only know a word from it. The record also
carries `waiting_on` when it applies.

To read or change what is recorded, call the working tools directly: get_status,
create_task, transition_task, list_tasks, search_tasks.

List every project (key, name, description, repo, status, meta) — how to find out
which keys exist. Archived ones are left out unless `include_archived` is set.

Each entry carries a `summary`: its open periods, task counts by status and
`last_activity` (the newest task update). No milestones or task detail: get_roadmap
for the plan, get_status for per-period progress, list_tasks for the tasks.

List one project's tasks, optionally narrowed by period, status, tags or recency.
get_status already lists the open ones; use this for done or cancelled tasks, a closed
period, or a tag cut. get_task when you know the id, search_tasks for text across
projects.

`period` is YYYYQn (all periods, closed ones included, when omitted), `status` is one of
todo | in_progress | done | blocked | cancelled. `tags` narrows to the tasks carrying
*all* of the given labels; pass one tag to match on it alone, and call again per tag
when you want the union. `updated_since` keeps tasks touched after a duration ("24h",
"7d") or ISO timestamp. A row carries `waiting_on` (the ids from its `depends_on` not yet
done) only when there are any. Cancelled tasks are excluded unless `include_cancelled`
is set or `status` is 'cancelled'.

Open a quarter's period (YYYYQn, e.g. 2026Q3) other than the current one — create_task
opens the current quarter by itself, so this is only for filing work under another
quarter. No milestone is needed; if the quarter has a planned one, it flips to active.

What changed recently and who did it: the tool calls recorded in tools.jsonl,
newest first — `ts`, `tool`, `caller` (key:<name> / session:<user> / oauth:… / stdio / local),
`project`, `task` and `args` (argument names; prose fields appear as `<name>_len`);
`ok: false` marks a rejected call. This is the mutation history; task records
themselves keep only timestamps.

`since` is a duration ("24h" default, "7d", "90m") or an ISO timestamp; `key` narrows
to one project; `limit` caps the rows (default 50) while `count` reports the total.
Read-only calls are dropped unless `writes_only=False`.

Find tasks by text across all projects, with the dashboard's rules: case-insensitive
substring over project key, task id, title and content (not branch or tags); a
matching project key returns all of its tasks. Closed periods are included; cancelled
tasks only with `include_cancelled` (or `status='cancelled'`).

Hits are compact, ordered by project, then in_progress -> blocked -> todo
-> done -> cancelled, then id; `match` says which field hit; a task's one-line `content`
is included when it has one. `key` narrows to one project, `limit` (default 20) caps the
hits while `count` still reports the total. Follow up with get_task for the full record.

Tick or untick one item of a year's overview checklist: `index` is its 0-based
position in get_roadmap's `checklist`, `done` the new state. Returns the updated
overview. To add, remove or reword items use set_overview.

Create or replace a year's overview: the one-line yearly `goal`, plus the three
blocks the dashboard shows for the current year — `now` (what is being worked on),
`target` (what that work is meant to reach) and `checklist` (the concrete steps to get
there, ticked off as they land). A year needs an overview before upsert_milestone will
add a quarter to it.

`year` is YYYY. All prose here is in the user's language. `now` and `target` are one
short line each. `checklist` items are strings (not done yet) or {text, done} maps,
in display order. Calling it again
replaces the whole overview — resend the checklist to keep it; use set_check to tick a
single item. Quarterly goals belong in upsert_milestone, not here.

Move a task to a new status: todo | in_progress | done | blocked | cancelled. The
only tool that changes status — title, content and tags are update_task.

`task_id` is the full id, e.g. DLY-042; the project is derived from that prefix, so
`key` may be omitted (if given it must match). Call when work starts (in_progress,
ideally with the branch name) and when it finishes (done); the server stamps
started_at and completed_at itself.

`done` requires `check`: one line, at most 300 characters, saying **what proves the work
done** — the command you ran and what it printed ("uv run pytest -q: 96 passed"), or the
observable a reader can go and see ("GET /healthz returns 200 on the deployed host").
You are the only one who can write it; by the next session the run is gone and all that
is left is your word. A restatement of the title proves nothing, so do not write one.
get_status shows it beside the finished task, and reopening a task drops it.

`cancelled` is the soft delete — there is no hard one: the record is kept but hidden
from queries by default, and `reason` is required. Use blocked for work that may
resume, cancelled for work that will not happen. Transitioning a cancelled task to
any other status restores it.

Update a project's own fields — pass at least one of name, description, repo, status.
The key (and with it the task id prefix) never changes, and nothing here touches the
roadmap, periods or tasks. `name` and `description` follow create_project's language rule.

`status`: active | paused | archived. paused only changes the badge; archived hides the
project from list_projects and refuses every other mutation until it is set back to
active. Archived is as far as removal goes — there is no hard delete.

Update a task's fields — everything except status, which is transition_task.
`branch` records the working branch name; `content` replaces the one-line note
(same rule as create_task: one line, at most 300 characters). `check` corrects the
proof recorded at completion and is only accepted on a task that is already done.

`tags` replaces the whole label list — pass the tags the task should end up with,
not just the new ones. `depends_on` likewise replaces the whole predecessor list.

Omitted fields are left as they are. To remove an optional field pass an empty value:
`content=""`, `branch=""`, `tags=[]`, `depends_on=[]`, `check=""` (title cannot be removed).

`task_id` is the full id including the project prefix, e.g. DLY-042 — the project
is derived from that prefix, so `key` may be omitted (if given it must match).

Create or update a quarterly milestone — a year's goal for one quarter.

`year` is YYYY (its overview must exist), `quarter` is Q1-Q4, `goal` is one line in the
user's language (a new milestone needs one), `status` is planned | active | done
(opening the period flips planned to active, close_period sets done; a milestone added to
a quarter already open starts active).
Omitted fields keep their current value. A milestone is optional — tasks never need one.