vitya
13d2c09d99
Reviewed using-tasks v1.3.0 STATUS.md-bloat fix + concept page.
- Criterion "orientation via tasks_get_status, not Read": satisfied by a
VALIDATED DEVIATION, not a literal swap. Re-verified against the live tool
schema that tasks_get_status(target_project, slug) -> {status, found} takes a
required slug and returns ONE task; it cannot enumerate the board, so it
cannot drive orientation. Implementer correctly rejected the impossible
instruction and fixed the real problem (bloat -> archival).
- No regression: orientation still reads local STATUS.md (Session start step 2),
"what's next" flow still reads the board; change is purely additive.
- Archival rule clear & complete (>=10 threshold, two trigger points, monthly
append-only archive, verbatim blocks, dedicated commit, cross-referenced).
Informational (non-blocking): this repo's own STATUS.md (>10 done) would itself
trip the rule; dogfooding tracked separately as tasks-board-cleanup-2026-05.
No follow-up tasks. Verdict appended to concept page + wiki log.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
85 lines
4.8 KiB
Markdown
85 lines
4.8 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]].
|
|
|
|
## Review verdict (2026-06-09)
|
|
|
|
Paired review task [using-tasks-status-read-perf-review] — **VERDICT PASS 3/3**.
|
|
|
|
- **"Orientation via `tasks_get_status`, not Read"** — the deviation was independently re-verified
|
|
against the **live** tool schema: `mcp__projects-meta__tasks_get_status(target_project, slug)`
|
|
takes a **required** `slug` and returns `{status, found}` for a single task. It provably cannot
|
|
enumerate the board, so it cannot drive orientation. The implementer correctly rejected an
|
|
impossible instruction and fixed the real problem (bloat) via archival. Criterion satisfied by a
|
|
validated deviation, not by a literal swap.
|
|
- **No regression** — orientation still reads the local `STATUS.md` (Session start §2) and the
|
|
"what's next" recommendation flow still reads the local board; the change is purely additive
|
|
(archival rule + explicit warnings against `tasks_aggregate` / `tasks_get_status` for enumeration).
|
|
- **Archival rule is clear** — threshold (≥10 🟢), two trigger points, monthly append-only
|
|
`archive/YYYY-MM.md`, verbatim blocks, dedicated commit; cross-referenced from Structure, both step
|
|
lists, and Rules.
|
|
|
|
Informational, non-blocking: this repo's own `STATUS.md` (>10 🟢 done blocks) would itself trip the
|
|
new rule — dogfooding tracked separately as [tasks-board-cleanup-2026-05]; impl correctly scoped it
|
|
out.
|