FronyBoard

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 the milestone 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 holds nothing yet: set_overview (year) -> upsert_milestone (quarter) -> open_period must run before create_task will accept a task.

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 and must be open; nothing else 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, the reading you chose where the spec allowed several, or the scope you deliberately left out. It is written now, before the work, so it cannot describe the result; 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. Rationale beyond one line goes in the commit. `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, 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.

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'.

Start working in a quarter: opens its period and flips a planned milestone to active. Required before create_task will accept that period. `period` is YYYYQn (e.g. 2026Q3) and its roadmap milestone must already exist — upsert_milestone first.

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, `status` is planned | active | done (open_period flips planned to active, close_period sets done). Omitted fields keep their current value.

Check a project's stored data against the FronyBoard schema and rules, returning errors and warnings. Rarely needed on its own — every mutation runs this same gate and refuses to write when it fails. Use it after the store was edited outside these tools.