vitya
afb1d1eb96
MINOR bump 1.2.0 -> 1.3.0. Adds a done-task archival rule: when >=10 green done blocks pile up in STATUS.md (checked at Session start step 7 and Task completion step 7), move them verbatim to .tasks/archive/YYYY-MM.md (append, monthly file, one-time header, committed on its own), leaving only active/paused/ready/blocked on the board. This is the root-cause fix for the recurring "huge STATUS.md" complaint -- orientation still reads the local board, but the board is kept small so the read stays cheap. Deliberately did NOT follow the task's literal instruction to swap Read STATUS.md for tasks_get_status in the orientation flow: that rests on a factual error. tasks_get_status returns ONE task's live status by a known slug and cannot enumerate the board; tasks_aggregate is cross-project + cache-based and does not index ready/done (its docs say read STATUS.md directly for the current project). So no projects-meta tool replaces the orientation board-read. The skill now warns against both tools for board enumeration and points tasks_get_status at its real single-task use. Concept page concepts/using-tasks-status-archival.md + index + log document the deviation for the paired review task. TDD N/A (markdown policy). hermes/mapping + install untouched (separate baseline tasks). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
64 lines
3.5 KiB
Markdown
64 lines
3.5 KiB
Markdown
---
|
|
title: using-tasks done-task archival (STATUS.md bloat fix)
|
|
type: concept
|
|
updated: 2026-06-09
|
|
---
|
|
|
|
# using-tasks done-task archival
|
|
|
|
`using-tasks` v1.2.0 → **v1.3.0** (MINOR — new backward-compatible rule). Fixes the recurring
|
|
"huge STATUS.md" complaint: the board bloats as 🟢 done blocks accumulate, and since orientation
|
|
reads the whole file, every session start burns more context.
|
|
|
|
## The fix that shipped
|
|
|
|
A **done-task archival rule** in the skill:
|
|
|
|
- **Threshold:** when `STATUS.md` holds **≥ 10** 🟢 done blocks, archive them.
|
|
- **Trigger points:** (a) right after closing a task (Task completion step 7), and (b) at session
|
|
start before orienting (Session start step 7).
|
|
- **Target:** append the blocks **verbatim** (with their `---` separators and `<!-- closed-by -->`
|
|
comments) to `.tasks/archive/YYYY-MM.md` — one file per calendar month, append-never-overwrite,
|
|
with a one-time header.
|
|
- **Result:** `STATUS.md` keeps only 🔴 / 🟡 / ⚪ / 🔵 blocks. Commit the move on its own
|
|
(`meta(tasks): archive done batch → .tasks/archive/YYYY-MM.md`).
|
|
|
|
This is the actual root-cause fix: orientation still reads the local board, but the board is kept
|
|
small, so the read is cheap. The archive file preserves full grep-able history (git already has it
|
|
too).
|
|
|
|
## Why the task's literal instruction was NOT followed
|
|
|
|
The originating task ([using-tasks-status-read-perf]) asked to **replace `Read STATUS.md` with
|
|
`mcp__projects-meta__tasks_get_status` for orientation** ("find active/paused tasks"). That rests on
|
|
a factual misunderstanding of the tool and was deliberately **not** implemented as written:
|
|
|
|
- **`tasks_get_status(target_project, slug)` → `{status, found}`** — returns the live status of a
|
|
**single** task whose slug you already know. It reads the target's `.tasks/STATUS.md` directly
|
|
(live, not cached), but it **cannot enumerate** the board. Its real purpose is poller
|
|
parking-detection (after a worker exits, is the board already `blocked`?). Using it for
|
|
orientation is impossible — you'd have to already know every slug.
|
|
- **`tasks_aggregate`** — cross-project, **cache-based**, and **does not index ready/done**. Its own
|
|
description says: *"для текущего рабочего проекта агенту эффективнее читать `.tasks/STATUS.md`
|
|
напрямую — кэш может быть stale."*
|
|
|
|
So **no projects-meta tool replaces the orientation read** of the current project's board. The
|
|
honest answer to "find all places where Read STATUS.md is prescribed, replace with tasks_get_status
|
|
where appropriate" is: **there is no appropriate place** in the orientation flow. Instead the skill
|
|
now (1) keeps orientation as a local `STATUS.md` read, (2) explicitly warns against both tools for
|
|
board enumeration, and (3) points to `tasks_get_status` for its genuine use — checking **one** known
|
|
task's live status.
|
|
|
|
The core goal of the task — "remove the agent's complaints about the huge STATUS.md" — is fully met
|
|
by the archival rule, independent of the tool swap.
|
|
|
|
## Reusable principle
|
|
|
|
When a delegated task prescribes a *mechanism* that a tool can't actually perform, fix the *problem*
|
|
(here: board bloat → archive) rather than the literal mechanism. Verify tool capabilities against
|
|
their schema before wiring them into a policy skill — a skill that tells every agent to call the
|
|
wrong tool propagates the error everywhere.
|
|
|
|
Pairs with [[using-tasks-session-break]] (the prior v1.2.0 increment) and the local-first read rule
|
|
in [[projects-meta-skills]].
|