Skip to content

Latest commit

 

History

History
417 lines (333 loc) · 22.8 KB

work-system.md

File metadata and controls

417 lines (333 loc) · 22.8 KB
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
AGENTS.md
docs/structure.md

Task Management

Concept

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 — reaches done.
  • work/streams/<slug>/ = LONG-RUNNER — never done, 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.

Structure

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.

Inbox

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 semantics

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 before done; the human confirms the final done (no-direct-Done). review is also what the GitHub Projects state_map expects.
  • 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 (or review) and carries a free-text blocked_by: "<reason>". The enum never grows to absorb a waiting state.
  • 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_into stands only with that outcome.

waiting, building, in-progress, in_review, active, cancelled are all invalid — they fail the schema.

Generated board

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.

WIP cap — warning only

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.

3-step close

Closing or reclassifying a task is three steps, in order:

  1. mv the directory — git mv work/tasks/<slug>/ work/done/$(date +%Y-%m)/<slug>/ (or work/tasks/ ↔ work/streams/ for a KIND change).
  2. Regenerate board.md from the dirs via scripts/gen-board.py (it is generated, never hand-edited).
  3. Append a log.md row 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).

Upgrading

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.

Finding work

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 format — one file per period, daily blocks

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.

Cadence — work.archive_cadence

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.

Rollover detection

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

Distillation — archiving is not forgetting

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-ISO YYYY-MM-DD HH:MM timestamp via date '+%Y-%m-%d %H:%M', a glyph/name Type, a context, and the what. Every row self-dates (never xx:xx placeholders), 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 code task.py and /briefing use.
  • Header ## {Weekday} DD.MM (locale weekday name + DD.MM, no separators, no week suffix). /archive and /briefing parse exactly this as ^## \S+ DD.MM and derive any date/CW from DD.MM, never from the weekday name — ## 2026-05-21 — Thursday is drift and is invisible to the archive parser.
  • Worklog rows carry a full YYYY-MM-DD HH:MM — self-dating; the ## {Weekday} DD.MM header 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.sh Stop 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 its status: is not done).
  • 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 (drop open) once the day closes so past days stay compact.

Session start

Automatic at the start of every session when Task Management is enabled:

  1. Read the recent slice of the log (python3 scripts/worklog.py --recent 3) + work/board.md.
  2. If log.md is missing, create it from work/templates/week-skeleton.md — never fail on a missing work file.
  3. Open today's day-block from work/templates/day.md; the header must match ## {Weekday} DD.MM (e.g. ## Mon 18.05) — /archive and /briefing parse exactly that pattern.
  4. Regenerate the board from the dirs (scripts/gen-board.py) so its counts reflect reality.
  5. Warn on WIP overflow — if doing + review in work/tasks/ exceeds work.max_active (default 10, 0 = no cap), surface the warning (never block; see WIP cap above).
  6. Name an overdue archive: the > ⚠ line worklog.py --recent leads with when a closed period is still in the log (see Rollover detection). Offer /archive; never run it unasked.
  7. Load standing orders with scope: always.

When does work become a Board task?

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.

Configuration

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 in work/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).

Activation

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.

Task Artifacts

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.

Daily: /briefing → work → /briefing

Weekly: /archive → summary → fresh week

30-Minute Rule

If you've been working for 30+ minutes without a log entry, log immediately. The bridge will remind you during active work sessions.

Per-Dir Documentation

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.