| summary | Task Management concept: log/board/tasks lifecycle, status enum, KIND-as-folder — the human-readable companion to AGENTS.md § Task Management. | ||
|---|---|---|---|
| type | guide | ||
| last_updated | 2026-10-24 | ||
| related |
|
Central task tracking from the bridge. Log activities, manage tasks,
archive weekly summaries. All data persists in work/ on your user branch.
(The system concept is Task Management; the directory name work/ stays.)
Two orthogonal axes. KIND is the folder a task lives in; status: is the
frontmatter field. They never collapse into one another:
work/tasks/<slug>/= FINITE task — reachesdone.work/streams/<slug>/= LONG-RUNNER — neverdone, excluded from WIP.work/done/YYYY-MM/<slug>/= closed.
Moving KIND = mv the directory; there is no kind: frontmatter field.
status: is the only state field.
work/
├── log.md Weekly log with daily blocks
├── board.md GENERATED task board (Doing / Review / Backlog / Streams / Done-YYYY-MM)
├── tasks/{slug}/ FINITE tasks with a STATUS.md (reaches done)
│ ├── STATUS.md Frontmatter + body; SoT for one task
│ ├── PLAN.md Implementation plan (from brainstorming/planning)
│ └── SPEC.md Design spec (from brainstorming/design)
├── streams/{slug}/ LONG-RUNNERS (same artifacts; never done, excluded from WIP)
├── done/YYYY-MM/ Closed tasks (status: done, folder moved here)
├── archive/ Weekly summaries
├── inbox/<id>/ Open items that need a person (item.yaml + events/); inbox.md is the generated view
├── imports/ Universal inbox (.gitignored)
├── import-rules.yaml File-pattern → action mapping
└── templates/ CORE skeletons:
├── week-skeleton.md Fresh weekly log.md (CW-wrapper + first day-block)
├── day.md One day-block (appended into the current week)
├── board.md Empty board
├── STATUS.md Per-task status + _schema.status.yaml
└── week-summary.md /archive weekly summary
backlog, doing, review, done are status values carried in each
STATUS.md — not folders. The folder encodes KIND, not status: work/tasks/
(finite) and work/streams/ (long-runner). There is no work/doing/,
work/queue/, work/review/, or per-status folder. Two moves relocate a folder:
the close move (→ work/done/YYYY-MM/<slug>/) and a KIND reclassification
(work/tasks/ ↔ work/streams/). The full STATUS.md schema (status enum, context
pattern, headline field, sync block) lives at work/templates/_schema.status.yaml.
Anything still open at the end of a unit of work goes into work/inbox/, not
into a sentence in the log. An item closes when its closes_when probe holds
against the live source, so a briefing reads the inbox instead of guessing from
the log what is still open. Model and CLI: docs/inbox.md.
status: is a closed enum — exactly {backlog, doing, review, done},
CI-validated against work/templates/_schema.status.yaml. No synonyms, no new
states without editing the schema.
backlog— captured, not started.doing— actively in flight.review— required hop beforedone; the human confirms the finaldone(no-direct-Done).reviewis also what the GitHub Projectsstate_mapexpects.done— completed. The human confirms the final transition.
Two things that are not statuses:
- Blocked is a FLAG, not a status. A blocked task stays
doing(orreview) and carries a free-textblocked_by: "<reason>". The enum never grows to absorb awaitingstate. - Declined is an OUTCOME, not a status. A task closed without completion is
status: done+outcome: declined. - Merged is an OUTCOME too. A task closed into another one is
status: done+outcome: merged+merged_into: <slug>, the task that took it in (task.py merge, below).merged_intostands only with that outcome.
waiting, building, in-progress, in_review, active, cancelled are all
invalid — they fail the schema.
board.md is generated from the task directories — never hand-curated. Its
sections map 1:1 to the enum (+ Streams + Done):
## Doing ← work/tasks/* with status: doing
## Review ← work/tasks/* with status: review
## Backlog ← work/tasks/* with status: backlog
## Streams ← work/streams/* (excluded from WIP)
## Done — YYYY-MM ← rolled from work/done/<current-month>/
Counts derive from ls over the task dirs, so they cannot drift. Humans edit
STATUS.md, never the board; the board is regenerated by
scripts/gen-board.py (run --check for a dry-run drift summary). A blocked
task shows its status with a 🚧 blocked marker, derived from its blocked_by:
field — not a separate section.
Regenerate trigger: at session-start and on every task move/close (3-step close
below). A board row that disagrees with the dirs is a regeneration artifact, not a
hand-edit to reconcile — fix the STATUS.md status: and regenerate.
The WIP cap is a warning, never a block. At session-start, when the count of
doing + review tasks in work/tasks/ exceeds bridge-config.yaml
work.max_active, the bridge surfaces a warning. New work is never auto-refused.
The remedy is to close, reprioritise, or reclassify a genuine long-runner to
work/streams/ — streams never count against WIP. (gen-board.py mirrors the
same threshold and flags ⚠️ WIP n > cap in the generated header.)
One number, one comparison. The cap applies when the count exceeds it (>),
never at equality. Unset means the default 10, held once as WIP_WARN in
scripts/gen-board.py; the template ships the same value, the pre-commit hook
falls back to it, and scripts/tests/test_gen_board.py fails when any of them
drifts. max_active: 0 switches the warning off.
Closing or reclassifying a task is three steps, in order:
mvthe directory —git mv work/tasks/<slug>/ work/done/$(date +%Y-%m)/<slug>/(orwork/tasks/ ↔ work/streams/for a KIND change).- Regenerate
board.mdfrom the dirs viascripts/gen-board.py(it is generated, never hand-edited). - Append a
log.mdrow with a timestamp.
python3 scripts/task.py close <slug> [--reason TEXT] [--declined] [--json] does
all three for a finite task: it sets status: done and closed: "YYYY-MM-DD"
(plus outcome: declined with --declined), drops blocked_by and
blocked_since, adds a dated note with the reason, moves the folder to
work/done/YYYY-MM/<slug>/ (a plain move: committing is yours), regenerates the
board and writes one row into today's day block. It refuses a stream (streams
never close), an unknown slug and a task already under work/done/. The
briefing dashboard's Done button runs it; task.py review recommends which
tasks are finished (bridge-cockpit.md § 3).
python3 scripts/task.py reopen <slug> [--as doing|backlog|review] [--note TEXT] [--json]
takes a close back: the newest work/done/*/<slug>/ moves to work/tasks/<slug>/,
status becomes doing (or backlog, for a task that only should still be done,
or review, for a task closed while in review),
closed: and outcome: go, a dated "Reopened" note joins the notes under the close
note, the board is regenerated and one log row is written. It refuses a slug that is
open. The dashboard's history and its undo run it. When the task was shelved (below), reopening
also closes the idea that shelve filed.
python3 scripts/task.py shelve <slug> [--until YYYY-MM-DD] [--reason TEXT] [--json] parks a finite
task nobody works on without losing it. It replaces the three hand steps (file an idea, close the task
as declined, defer the idea) with one command. In this order: it files an inbox item of kind idea
(gate only-you, urgency later, key shelve:<slug>, summary from the task's headline, detail naming
work/done/YYYY-MM/<slug>/STATUS.md and task.py reopen <slug>), defers it until --until (default
today + 90 days) so notifiers that announce new items stay quiet, then closes the task through the
normal close as declined with the reason shelved: <reason>. Every check runs before anything is
written, and when the close still fails the idea is closed again, so a task never disappears without
its idea. It refuses a stream (not finite), an unknown slug and a task already under work/done/.
Shelving a task again after a reopen brings its idea back, deferred again, also when a person dropped or
rejected it in between: a new shelve is a new decision. Only a mute rule on the shelve: family keeps the idea
dropped, and the shelve says so in a warning.
python3 scripts/task.py merge <keep> --from <slug> [--heading TEXT] [--json] folds one finite task
into another, one task per call. The task keep stays; slug closes as merged into it. In this order:
a section between the markers <!-- merged-from: <slug> --> and <!-- /merged-from: <slug> --> goes
into keep's STATUS.md, before its ## Notes (else at the end), with the merged task's headline, its
brief.goal when that says more, every line of its ## Notes (but the notes an earlier merge, its undo or a
reopen after it wrote) and every open step (- [ ]) as written,
and the paths of its STATUS.md and of up to 20 files of its deliverables/ at their new place under
work/done/YYYY-MM/<slug>/ (nothing is copied, the folder moves whole with the close). The same paths
join keep's related: as items tagged # merged-from: <slug>, after its last item in the list's own
style (indented or not); a related: in flow style or as a scalar, or a list the edit would not leave
reading as its items plus the paths, is left alone, with a warning. Keep gets the note "Merged in :
", then the merged task closes with task.py close <slug> --merged-into <keep> (outcome: merged, merged_into: <keep>, the note "Merged into "; unlike a plain close it keeps blocked_by
and blocked_since), and the board and the log follow. Both STATUS.md files as they were before and
after go to .bridge/task-merges.json for the undo. When the close fails, the section and the related
lines come out again, so nothing stays half merged. It refuses,
without writing, a slug equal to keep, a stream, a missing or closed task, a
work/done/<month>/<slug> that exists already, and a keep that already holds a section for that slug. What does not move: inbox items
that name the merged task, session links, sync:, priority, area, the rest of the brief, ticked steps.
python3 scripts/task.py unmerge <keep> --from <slug> [--as doing|backlog|review] [--json] takes one
merge back. Each of the two files that is still as the merge left it (a brief written since aside) comes
back byte for byte as it was before the merge, from .bridge/task-merges.json: no note, no new
last_updated, the status it had. A file changed since is edited instead: the section (markers
included), the tagged related: items (related: itself when no item is left) and the note "Merged in
" leave keep, and the merged task reopens as --as (default doing) without its "Merged into" note.
The undo writes no note of its own, only its log rows; --json says restored when both came back
whole. It refuses a slug that is not closed as merged into keep, and a keep whose section for it is gone.
reopen also drops merged_into. The cockpit's Merge in Work through runs both
(bridge-cockpit.md § 3).
python3 scripts/task.py next <slug> -- <text> keeps a task's next step as
next: {what: <text>} with last_updated: and a dated "Next step" note, so the step
carries the day it was set; --clear takes it away. The cockpit runs it only when the
person takes over a suggested step (bridge-cockpit.md § 3).
task.py shelve and the idea cleanup in task.py reopen are additive: nothing to migrate, every
existing call and every existing task or inbox item works unchanged (reopen --json gains a
closed_ideas list). Tasks you shelved by hand earlier (idea, close declined, defer) keep working; their
idea carries no shelve:<slug> key, so reopen leaves it alone. To move one onto the new behaviour:
task.py reopen <slug>, close the old idea with inbox.py close <id>, then task.py shelve <slug>.
task.py merge, task.py unmerge and close --merged-into are additive too. The schema's outcome
gains merged and the field merged_into; a reader that knows only declined sees a merged task as
done, which it is.
python3 scripts/work-find.py <words> [--json] searches every task, stream and closed
task, the log and its archive, and lists the files ranked: slug or title first, then a
hit in STATUS.md, then the rest. Plain words, never a pattern, the same answer with or
without rg; an open and a closed task of one slug are two files; video/ and
deliverables/ folders are never read. The cockpit's Files view runs the same search
(cockpit-files.md).
log.md holds one archive period at a time — by default one week. The
header # Week {CW} — {DATE_FROM} to {DATE_TO} plus an **Active Focus:**
line wrap a sequence of daily blocks. /archive rolls a finished period into
work/archive/{bucket}/ and resets log.md from
work/templates/week-skeleton.md.
A Bridge that runs on two machines appends rows to log.md on both. The root .gitattributes sets
work/log.md merge=union, so a rebase keeps both sides' rows instead of stopping on a conflict.
How often that roll happens is configurable:
| Value | Bucket | Directory |
|---|---|---|
weekly (default) |
ISO week | work/archive/weeks/ |
bi-weekly |
ISO week pair | work/archive/weeks/ |
monthly |
calendar month | work/archive/months/ |
quarterly |
calendar quarter | work/archive/quarters/ |
yearly |
calendar year | work/archive/years/ |
The same key drives /briefing's "archive overdue" warning, so the prompt and
the archiver can never disagree. Leaving it unset behaves exactly as before.
Choosing one is a context trade, not a filing preference. Session start
reads only the recent slice, but /briefing and /archive read log.md in
full, so the cadence sets how much history each of those runs loads. A rough
guide: at ~13 rows on an active day and ~250 bytes a row, a month of daily work
is ~16k tokens per full read, a year ~190k. Pick the longest cadence whose
loaded size you are willing to pay for on every briefing.
/archive runs on request, so a reminder that only prose carried went quiet once
nobody asked, and the log kept growing. The session start therefore names the
debt itself: python3 scripts/worklog.py --recent 3 leads with a > ⚠ line
whenever log.md still holds a period the cadence has closed, with the periods,
their rows and their size, on every session until it is archived.
python3 scripts/worklog.py --check reports the same and exits 1, for an audit.
Neither archives: /archive distils memory first and asks before it writes. The
period arithmetic is scripts/archive-buckets.py's, the plan /archive itself
follows, so the warning and the archiver cannot disagree.
--check-placement names rows filed under another day's block, with exit 1.
Every row carries its own date, so a Tuesday row under the Monday heading is
detectable. It stays apart from --check: a session past midnight files
tomorrow's rows under today, which is cosmetic and must not drown the archive
signal.
Nothing in the Bridge reads work/archive/. Session-start, /briefing
and bridge-curator all load log.md and the memory index, never an archived
summary. So archiving alone would discard working memory and keep only a
backup nobody opens.
/archive Phase 5 closes that gap: before the reset it distils the period's
rows into durable facts for the memory base, whose MEMORY.md index is
loaded every session. Bookkeeping (commits, PRs, status flips) is deliberately
dropped — git already holds it. Decisions-with-rationale, hard-won diagnoses
and discovered constraints are kept.
It proposes and never writes silently — accepted candidates become memory
files, deferred ones become work/_learning/proposals/ entries reviewable via
/bridge-learn (rules/learning-autonomy.md).
Each day-block (template: work/templates/day.md):
## Mon 18.05
<details open>
<summary>Worklog (1)</summary>
| YYYY-MM-DD HH:MM | Type | Context | What |
|------------------|------|---------|------|
| 2026-05-18 14:55 | 📋 | bridge | ... |
</details>Conventions:
- ONE log row format, frozen:
| YYYY-MM-DD HH:MM | Type | Context | What |— a full-ISOYYYY-MM-DD HH:MMtimestamp viadate '+%Y-%m-%d %H:%M', a glyph/name Type, a context, and the what. Every row self-dates (neverxx:xxplaceholders), so you can always tell which day a row belongs to without scrolling to the header — a stale or unarchived log is never ambiguous. The legacy time-only| HH:MM | ... |row is retired — do not emit it. - One write path:
python3 scripts/worklog.py --append --context <tag> --what "<what + why>"(optional--glyph,--at 'YYYY-MM-DD HH:MM') puts the row into the block of its own date and opens that block when it is missing, in the log's own order. The day ends at the next##heading, so a pinned section never takes the row, and pipes and line breaks in the text are folded. Inside the day it places rows with the codetask.pyand/briefinguse. - Header
## {Weekday} DD.MM(locale weekday name +DD.MM, no separators, no week suffix)./archiveand/briefingparse exactly this as^## \S+ DD.MMand derive any date/CW fromDD.MM, never from the weekday name —## 2026-05-21 — Thursdayis drift and is invisible to the archive parser. - Worklog rows carry a full
YYYY-MM-DD HH:MM— self-dating; the## {Weekday} DD.MMheader stays only a display anchor for the parsers. - Logging is mandatory + continuous — every substantive unit of work gets its own
row the moment it lands, not batched. The
worklog-drift-check.shStop hook is the deterministic backstop (it blocks end-of-turn when code changed without a log row for today, and when a STATUS.md body asserts completion while itsstatus:is notdone). - Log sits in a
<details>block with a(N)count in the<summary>. The current day ships<details open>(working memory stays visible); collapse it (dropopen) once the day closes so past days stay compact.
Automatic at the start of every session when Task Management is enabled:
- Read the recent slice of the log (
python3 scripts/worklog.py --recent 3) +work/board.md. - If
log.mdis missing, create it fromwork/templates/week-skeleton.md— never fail on a missing work file. - Open today's day-block from
work/templates/day.md; the header must match## {Weekday} DD.MM(e.g.## Mon 18.05) —/archiveand/briefingparse exactly that pattern. - Regenerate the board from the dirs (
scripts/gen-board.py) so its counts reflect reality. - Warn on WIP overflow — if
doing + reviewinwork/tasks/exceedswork.max_active(default 10, 0 = no cap), surface the warning (never block; see WIP cap above). - Name an overdue archive: the
> ⚠lineworklog.py --recentleads with when a closed period is still in the log (see Rollover detection). Offer/archive; never run it unasked. - Load standing orders with
scope: always.
Three-class rule from protocols/standing-orders/board-task-criteria.md:
- A: Board task (STATUS.md + board row): only when asked for, or work already exists (branch, draft, file, a sent request awaiting an answer) and continues in a later session, or a dated commitment to someone. An external recipient alone no longer qualifies; an assigned tracker issue stays in the tracker.
- B: Log-only, state changed and finished in the session. A mention with nothing started goes to the inbox as kind
idea. - C: Silent, read-only routine commands (
/briefing,/bridge-status,/archive).
Sub-items of an existing task are checked off in the parent STATUS.md, no own task. Cold ideas already collected in work/backlog.md stay there; new mentions go to the inbox as kind idea.
Single source: bridge-config.yaml (USER layer), work: block. Controls:
- Logging level (hybrid/auto/manual) — how aggressively to log
- Activity types — emoji × name list for log entries
- Limits:
max_active(WIP warning threshold for doing+review inwork/tasks/; warns when exceeded, never blocks; default 10, 0 = no cap), daily goals - Imports — directory + rules for the universal inbox
- Transcript retention:
transcript_retention_days, how long the harness keeps session transcripts, so how long a memory fact's session link resolves (memory.md§ Retention)
The legacy work/.config.yaml is obsolete (merged into bridge-config.yaml on 2026-04-11).
Say "set up task management" (or the legacy "set up work system") or enable during
/bridge-onboard. The toggle is work.enabled in bridge-config.yaml.
Each task directory can contain:
| File | Created by | Purpose |
|---|---|---|
STATUS.md |
Task creation | Status, description, log entries |
PLAN.md |
/brainstorm → planning |
Step-by-step implementation plan |
SPEC.md |
/brainstorm → design |
Design specification, architecture decisions |
*.md |
Any workflow | Additional notes, research, meeting notes |
Plans and specs belong to their task, not in a separate docs/ folder. When a task moves to done/, its artifacts travel with it — preserving the full decision context for future reference.
If you've been working for 30+ minutes without a log entry, log immediately. The bridge will remind you during active work sessions.
When a task folder needs navigation (plan + spec + research + meetings side by side),
write a README.md (industry standard). No bespoke _MOC.md / index.md convention —
see AGENTS.md → Documentation Navigation.
A stale doc is worse than none — update it on task switch, or delete it.