backburner 0.1.0

Private project memory for work worth coming back to.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158

# Backburner

Private project memory for work worth coming back to.

> Not everything belongs today.
>
> Put it on the backburner.

Backburner stores tasks locally inside a git repository. It is intentionally
small. Every task lives in one of three places: **Today**, **Backburner**, or
**Archive**.

Backburner is named after the kitchen. When you're busy on the line, you move
something to the back burner—not because it isn't important, but because
something else needs your attention first. It'll still be there when you're
ready.

## The Model

Backburner has three states.

- **Today** — your active working memory.
- **Backburner** — deferred work waiting to become relevant again.
- **Archive** — resolved work that is no longer on the docket.

```text
Today ─────► Archive
   │
   ▼
Backburner ─────► Today
```

New tasks enter Today by default. Use `--backburner` to park work without
making it active.

`bb finish-session` reconciles your working memory.

- Completed tasks move to Archive.
- Unfinished Today tasks return to the Backburner.

Tomorrow starts with a clean Today.

## Install

```sh
cargo install backburner
```

The installed binary is named `bb`.

For a faster end-user install, Backburner can also be distributed as prebuilt
release binaries:

```sh
curl -fsSL https://raw.githubusercontent.com/rollingstorms/backburner/main/install.sh | sh
```

That installer path should be backed by release artifacts generated with
`cargo-dist`: GitHub Releases, checksums, tarballs, and shell/PowerShell
installers. Rust users can then also install the prebuilt binary with:

```sh
cargo binstall backburner
```

### Developer Build

Build from source when working on Backburner itself:

```sh
git clone https://github.com/rollingstorms/backburner.git
cd backburner
cargo build --release
```

## Initialize a Repository

```sh
bb init
```

This creates `.backburner/backburner.db` and adds `.backburner/` to
`.git/info/exclude`, keeping your project memory private to your local checkout.

## Commands

### Capture

```sh
bb add "Fix flaky login redirect"
bb add "Park this for later" --backburner
```

### View

```sh
bb today
bb backburner
bb archive
bb show 1
```

### Update

```sh
bb done 1
bb undone 1
bb move 1 today
bb plan 1 tomorrow
bb note 1 "Only fails after token expiry."
```

### Sessions

Sessions scope the Today list.

`bb session start <name>` creates or resumes a working session. New tasks are
added to that session's Today list.

`bb finish-session` reconciles the active session. When no session is active,
it reconciles every Today task.

Use `bb finish-session <name>` to reconcile a specific session regardless of
which session is currently active.

```sh
bb session start refactor-auth
bb session end
bb finish-session
bb finish-session refactor-auth
```

## Context

Tasks can carry context that makes them easier to resume later.

```sh
bb add "Fix auth redirect regression" \
  --file src/auth.rs:42 \
  --cmd "cargo test auth" \
  --note "Fails after token expiry." \
  --source agent
```

Machine-readable context is also available:

```sh
bb context --json
```

`bb context` includes Today and Backburner tasks.

## Test

```sh
cargo test
cargo clippy -- -D warnings
```