Skip to main content

max / makenotwork

wam: bridge to the wam-overview wiki note and add a README (/dellm) Add a crate-level doc block with the greppable `<!-- wiki: wam-overview -->` marker, and a public README covering the painhours model, the TUI/CLI/API surfaces, and SQLite storage. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Author: Max Johnson <me@maxj.phd> · 2026-07-14 15:30 UTC
Commit: c4b600041b763c09ff60a570b8cca6b94868c578
Parent: 98fb53a
2 files changed, +57 insertions, -0 deletions
A wam/README.md +49
@@ -0,0 +1,49 @@
1 + # wam (Whack-a-Mole)
2 +
3 + A distributed ticket manager driven from the terminal. One binary exposes three
4 + surfaces over a single SQLite database: an interactive TUI, a CLI, and an HTTP
5 + API for programmatic ingest.
6 +
7 + ## Urgency without a priority field
8 +
9 + Tickets do not store a priority. Each ticket carries two 1-to-5 guesstimates,
10 + `pain` (how much it hurts a hit user) and `scale` (how broadly it hits), and wam
11 + computes a 0-to-100 painhours heat score from those two plus the ticket's age:
12 +
13 + ```text
14 + raw = pain^PAIN_EXP * scale^SCALE_EXP * age_weeks^AGE_EXP
15 + painhours = round(100 * (1 - e^(-raw / K)))
16 + ```
17 +
18 + Scale drives the ranking, pain gives severity a secondary pull, and age is the
19 + anti-starvation lever so a narrow bug still climbs over time. The Low/Medium/High/
20 + Critical band is derived from the score, not stored. The tuning constants and
21 + their calibration live in `src/types.rs`.
22 +
23 + ## Build and run
24 +
25 + ```
26 + cargo run -p wam # open the TUI (default)
27 + cargo run -p wam -- create -t "title" # create a ticket from the CLI
28 + cargo run -p wam -- list # list tickets
29 + ```
30 +
31 + Run without a subcommand for the TUI. Run with a subcommand for one-shot CLI use.
32 +
33 + ## Layout
34 +
35 + - `src/tui.rs` the ratatui interactive view.
36 + - `src/cli.rs` the clap subcommands and export formats.
37 + - `src/api.rs` the axum HTTP endpoints.
38 + - `src/db.rs` SQLite storage (bundled rusqlite, WAL mode). Each instance has a
39 + node id, the seam for future multi-user use.
40 + - `src/types.rs` the ticket model and the painhours scoring.
41 +
42 + ## Storage
43 +
44 + A single SQLite database in the platform data directory. WAL mode is on, so
45 + concurrent readers work today; multi-writer conflict resolution is a future item.
46 +
47 + ## License
48 +
49 + See the workspace `LICENSE`.
M wam/src/main.rs +8
@@ -1,3 +1,11 @@
1 + //! wam (Whack-a-Mole) — distributed ticket manager binary.
2 + //!
3 + //! # Design
4 + //!
5 + //! The painhours urgency model, the TUI/CLI/API surfaces, and the SQLite storage
6 + //! are described in the maintainer wiki.
7 + //! <!-- wiki: wam-overview -->
8 +
1 9 mod api;
2 10 mod cli;
3 11 mod db;