@titan-design/active-work 0.1.0 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@titan-design/active-work",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "type": "module",
   "description": "Durable workspace state for engineering work — CLI, MCP, and Claude skill for tracking initiatives across sessions",
   "license": "MIT",
@@ -21,7 +21,8 @@
     "dist",
     "skill",
     "claude-commands",
-    "scripts"
+    "scripts",
+    "docs/cli-reference.md"
   ],
   "engines": {
     "node": ">=22"
@@ -33,6 +34,16 @@
     "build:cli": "tsup",
     "build:dashboard": "vite build --config src/dashboard/vite.config.ts",
     "gen:cli-reference": "pnpm build:cli && node scripts/gen-cli-reference.mjs",
+    "mine:session": "node tools/mine-session-signals.mjs",
+    "index:session": "node tools/build-session-index.mjs",
+    "mine:files": "node tools/mine-file-history.mjs",
+    "mine:drain": "node tools/mine-drain.mjs",
+    "mine:drain-eval": "node tools/eval-drain.mjs",
+    "export:aw-data": "node tools/export-aw-data.mjs",
+    "cost:rollup": "node tools/cost-rollup.mjs",
+    "eval:miner": "node tools/eval-miner.mjs",
+    "index:eval": "node tools/eval-session-index.mjs",
+    "check:tools": "for f in tools/*.mjs; do node --check \"$f\" || exit 1; done && node -e \"JSON.parse(require('fs').readFileSync('tools/pricing/models.json','utf8'))\"",
     "postinstall": "node scripts/postinstall.js",
     "preuninstall": "node scripts/preuninstall.js",
     "test": "vitest run",
@@ -46,14 +57,14 @@
     "format:check": "prettier --check \"src/**/*.ts\" \"__tests__/**/*.ts\""
   },
   "devDependencies": {
-    "@changesets/cli": "^2.31.0",
     "@eslint/js": "^9.39.4",
+    "@types/better-sqlite3": "^7.6.13",
     "@types/node": "^22.10.5",
     "@types/proper-lockfile": "^4.1.4",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
     "@vitejs/plugin-react": "^6.0.1",
-    "@vitest/coverage-v8": "^3.0.5",
+    "@vitest/coverage-v8": "^3.2.7",
     "eslint": "^9.20.0",
     "prettier": "^3.4.2",
     "react": "^19.2.6",
@@ -65,7 +76,7 @@
     "typescript-eslint": "^8.24.1",
     "vite": "^8.0.12",
     "vite-plugin-singlefile": "^2.3.3",
-    "vitest": "^3.0.5"
+    "vitest": "^3.2.7"
   },
   "publishConfig": {
     "access": "public"
@@ -74,6 +85,13 @@
     "@clack/prompts": "^1.4.0",
     "@hono/node-server": "^2.0.2",
     "@modelcontextprotocol/sdk": "^1.29.0",
+    "@titan-design/cluster": "^0.1.0",
+    "@titan-design/daemon": "^0.1.2",
+    "@titan-design/locator": "^0.1.0",
+    "@titan-design/registry": "^0.1.0",
+    "@titan-design/session-graph": "^0.3.1",
+    "@titan-design/session-read": "^0.2.0",
+    "better-sqlite3": "^13.0.2",
     "commander": "^14.0.3",
     "env-paths": "^4.0.0",
     "gray-matter": "^4.0.3",
@@ -84,5 +102,10 @@
     "proper-lockfile": "^4.1.2",
     "yaml": "^2.9.0",
     "zod": "^4.4.3"
+  },
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "better-sqlite3"
+    ]
   }
 }

package/scripts/gen-cli-reference.mjs

@@ -10,20 +10,41 @@
  * Requires `pnpm build` to have run so `dist/cli.js` exists.
  */
 import { spawnSync } from 'node:child_process';
-import { writeFileSync, existsSync } from 'node:fs';
+import { writeFileSync, existsSync, statSync, readdirSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
-import { dirname, resolve } from 'node:path';
+import { dirname, resolve, join } from 'node:path';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const REPO_ROOT = resolve(__dirname, '..');
 const CLI = resolve(REPO_ROOT, 'dist/cli.js');
 const OUT = resolve(REPO_ROOT, 'docs/cli-reference.md');
+const SRC = resolve(REPO_ROOT, 'src');
 
 if (!existsSync(CLI)) {
   console.error(`error: ${CLI} not found. Run \`pnpm build\` first.`);
   process.exit(1);
 }
 
+/** Recursively find the most recent mtime among files under `dir`. */
+function newestMtime(dir) {
+  let newest = 0;
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const path = join(dir, entry.name);
+    const mtime = entry.isDirectory() ? newestMtime(path) : statSync(path).mtimeMs;
+    if (mtime > newest) newest = mtime;
+  }
+  return newest;
+}
+
+const distMtime = statSync(CLI).mtimeMs;
+const srcMtime = newestMtime(SRC);
+if (srcMtime > distMtime) {
+  console.error(
+    `error: ${CLI} is older than src/ (dist stale). Run \`pnpm build:cli\` before regenerating docs.`,
+  );
+  process.exit(1);
+}
+
 /** Run the built CLI and return its stdout (help is written to stdout by commander). */
 function runHelp(args) {
   const result = spawnSync(process.execPath, [CLI, ...args, '--help'], {

package/skill/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: active-work
 description: |
-  Maintain durable per-initiative workspace state (brief, handoff, tasks, sessions, artifacts) so engineering work picks up cleanly across Claude Code sessions. Use when the user mentions: "active work", "what am I working on", "bootstrap session", "new initiative", "record this session", "update handoff", "archive initiative", "check active", "audit my workstreams", "find untracked work", "set up active-work", "add a task", "mark X done", "what's blocking me", "wrap up", "I'm done", or types /active-work.
+  Maintain durable per-initiative workspace state (brief, tasks, sessions, notes, artifacts) so engineering work picks up cleanly across Claude Code sessions. Use when the user mentions: "active work", "what am I working on", "bootstrap session", "new initiative", "record this session", "update handoff", "archive initiative", "check active", "audit my workstreams", "find untracked work", "set up active-work", "add a task", "mark X done", "what's blocking me", "wrap up", "I'm done", or types /active-work.
 ---
 
 # active-work — durable workspace state across Claude sessions
 
-`active-work` keeps a small filesystem-backed record for every engineering initiative the user has in flight. Files live under `$XDG_DATA_HOME/active-work/<slug>/` and include `brief.md` (frontmatter + prose), `handoff.md` (free prose), `tasks/*.yml`, `sessions/*.md`, `artifacts.yml`, and `sources/`. The CLI is `active-work`; `aw <slug>` is a thin launcher that bootstraps a Claude session for an initiative. A long-running daemon, `active-work mcp serve`, exposes MCP tools to Claude Code over HTTP and serves a read-only dashboard at `http://127.0.0.1:7400/ui`.
+`active-work` keeps a small filesystem-backed record for every engineering initiative the user has in flight. Files live under the active root (`~/Library/Application Support/active-work/<slug>/` on macOS — resolved via `env-paths`, which ignores `XDG_DATA_HOME`) and include `brief.md` (frontmatter + prose), `tasks/*.yml`, `sessions/*.md`, `artifacts.yml`, and `sources/` (including `sources/notes/` for durable notes). There is no `handoff.md`: current state is *derived* from the open-loop ledger in the session files, so it cannot go stale. The CLI is `active-work`; `aw <slug>` is a thin launcher that bootstraps a Claude session for an initiative. A long-running daemon, `active-work mcp serve`, exposes MCP tools to Claude Code over HTTP and serves a read-only dashboard at `http://127.0.0.1:7400/ui`.
 
 ## When to engage
 
@@ -16,7 +16,7 @@ Engage whenever the user signals they want to inspect, mutate, or hand off persi
 - "bootstrap session" / `/active-work` — load the bootstrap prompt for an initiative
 - "new initiative" — scaffold a slug with `active-work new`
 - "add a task" / "mark X done" / "what's blocking me" — task ops via `active-work task`
-- "record this session" / "update handoff" / "wrap up" / "I'm done" — session capture + handoff
+- "record this session" / "update handoff" / "wrap up" / "I'm done" — session capture via `active-work wrap` (there is no handoff file; the phrase still means wrap)
 - "archive initiative" — move a slug to the archived state
 - "check active" / "audit my workstreams" — `active-work audit` health check
 - "find untracked work" — `active-work discover` across configured sources
@@ -24,26 +24,62 @@ Engage whenever the user signals they want to inspect, mutate, or hand off persi
 
 ## Core rules
 
-1. **Edits route through the CLI.** Use `active-work new`, `active-work set`, `active-work task add`, `active-work task done`, `active-work artifact add`, etc. Direct `Edit`/`Write` on `tasks/*.yml`, `artifacts.yml`, or the frontmatter of `brief.md` bypasses validation and corrupts the schema. Prose bodies (`brief.md` body, `handoff.md`, session summaries) can be edited directly, but prefer `active-work edit` for `brief.md` because it re-validates frontmatter on save.
+1. **Edits route through the CLI.** Use `active-work new`, `active-work set`, `active-work task add`, `active-work task done`, `active-work artifact add`, etc. Direct `Edit`/`Write` on `tasks/*.yml`, `artifacts.yml`, or the frontmatter of `brief.md` bypasses validation and corrupts the schema. Prose bodies (`brief.md` body, session summaries, note bodies) can be edited directly, but prefer `active-work edit` for `brief.md` because it re-validates frontmatter on save.
 2. **LLM writes prose; CLI handles structure.** Task ordering, session filenames, frontmatter dates, slug normalization, and rank reflow are CLI primitives. Don't compute them yourself.
 3. **`active-work --help` is the canonical command reference.** This skill intentionally doesn't duplicate the surface; run `active-work --help` or `active-work <command> --help` when you need flags.
-4. **Session capture at end.** When wrapping up, run `active-work session record <slug>` with a 3-5 bullet summary of what happened, what changed, and what's next. Auto-prompt this when you detect the user winding down ("I'm done", "let's stop", "wrap up", inactivity after a chunk of work).
+4. **Wrap is the end of the world.** See "Wrapping a session" below. This is the rule agents most often get wrong, and getting it wrong loses the user's work.
 5. **`active-work mcp status` first.** If MCP tools aren't responding, the daemon may not be running. Start it with `active-work mcp serve --detach` before retrying.
 
+## Wrapping a session
+
+**Assume the process exits the instant `wrap` returns, and that everything not written to disk is lost.** Not summarized in chat — *written*. The user will very likely start a fresh session immediately; the only thing that survives is what is on disk. Chat scrollback does not carry over.
+
+The failure this is designed to prevent: an agent posts its session summary, then follows it with two to four "oh, by the way" items — a task that should be filed, a gotcha worth remembering, an uncommitted worktree — each of which then has to be captured before the session can actually end. **Do that sweep before calling `wrap`, not after.** If you find yourself about to write "one more thing" after wrapping, you wrapped too early.
+
+Run `active-work preflight <slug>` first. It is read-only and returns the live git state plus the checklist of categories you must answer.
+
+Then sweep your own session for everything durable and file it:
+
+| What you have | Where it goes |
+|---|---|
+| Unfinished work, open PRs, unanswered questions | `--next-steps` (the open-loop ledger) |
+| Prior loops this session closed | `--resolves` with `outcome: done` |
+| A thread you're deliberately dropping | `--resolves` with `outcome: abandoned` **and a note saying why** — the note is required, and it surfaces in the bootstrap for 14 days so nobody proposes the dropped thing again |
+| Anything actionable | `active-work task add` before wrapping, then `--tasks-filed` |
+| Process improvements, gotchas, "avoid this next time", non-actionable FYIs | `--notes` (lands in `sources/notes/`, indexed in every future bootstrap) |
+| Uncommitted work, unpushed branches, stashes, worktree state | recorded automatically by `wrap`; add `holding` context if the bare fact isn't enough |
+
+Write `--next-steps` text that does **not** restate the task or PR the loop targets — put the id in the step's `ref` field and let the text open with the action. The bootstrap prefixes the ref itself, so text of "AW-28 drain the miner backlog" filed against `ref: AW-28` renders as "AW-28 AW-28 drain the miner backlog" in every future session (AW-71).
+
+Every category needs an **explicit** answer. Omitting a flag is an error, not a shortcut — the assert-nothing forms (`--no-loops`, `--no-notes`, `--no-tasks`) exist so that "there was nothing here" is a claim you make deliberately rather than by forgetting. Use them only when they are actually true.
+
+**active-work is the source of truth — not `~/.claude` memory, not `CLAUDE.md`.** A process lesson written to memory is invisible to the next session on this initiative and to every other surface. File it as a note.
+
+Then report back plainly: the counts of what was filed and updated, and that you are ready to end. `wrap` returns exactly that receipt — relay it rather than re-deriving it.
+
+Check `ready_to_end` before you say you are done. It is `false` when a `--resolves` ref closed no loop; `resolves_rejected[]` names each bad ref and why. The session file and `brief.updated` are already written, so **do not re-run `wrap`** — that would duplicate the narrative. Report the rejected refs to the user; they get re-filed from a later session.
+
+Auto-prompt the wrap when you detect the user winding down ("I'm done", "let's stop", "wrap up", inactivity after a chunk of work).
+
 ## Bootstrap flow (`aw <slug>` / `active-work open <slug>`)
 
-`aw <slug>` is the operator-facing launcher: it assembles the bootstrap prompt and execs `claude` with the initiative's worktree as cwd. Omit the slug and it resolves the initiative from the caller's cwd (matching against each brief's registered worktrees), falling back to the interactive picker when nothing matches uniquely; `aw --pick` forces the picker. (Register a worktree so this resolution works with `active-work worktree set <slug> <path>`, or at creation via `new --worktree` / `track --worktree`.) `active-work open <slug>` is the same assembly logic, but prints the prompt to stdout instead of spawning Claude — use it from MCP / scripts / any caller that wants to handle the spawn itself (pass `--cwd <dir>` when the caller's process cwd isn't the user's shell cwd, e.g. the daemon). The bootstrap prompt inlines:
+`aw <slug>` is the operator-facing launcher: it assembles the bootstrap prompt and execs `claude` with the initiative's worktree as cwd. Omit the slug and it resolves the initiative from the caller's cwd (matching against each initiative's **registered** worktrees — the entries in `artifacts.yml` that carry a `name`, not the ones `wrap` merely swept), falling back to the interactive picker when nothing matches uniquely; `aw --pick` forces the picker. (Register a worktree so this resolution works with `active-work worktree set <slug> <path>`, or at creation via `new --worktree` / `track --worktree`.) `active-work open <slug>` is the same assembly logic, but prints the prompt to stdout instead of spawning Claude — use it from MCP / scripts / any caller that wants to handle the spawn itself (pass `--cwd <dir>` when the caller's process cwd isn't the user's shell cwd, e.g. the daemon). The bootstrap prompt inlines:
 
-- The full `handoff.md` text
-- A brief excerpt (frontmatter summary + first prose paragraph)
+- A brief excerpt (the brief's prose body, truncated to 40 lines)
+- **Open loops** — unresolved `next_steps` from prior sessions, with the age of each hang
+- **Abandoned loops** from the last 14 days, each with the reason it was dropped (`active-work loops <slug> --state abandoned` for the full history)
 - The most recent session summary
 - The top N open tasks (rank-sorted)
+- Recently-done tasks from the last 14 days, if any
+- **Durable notes** — newest first, capped by count and never expired by age
 - Open artifacts with status
-- Time since the last session
+- A context block with today's date, bootstrap time, and time since the last session
 
 To re-seed context **mid-session** (a session that wasn't started via `aw`, or one that has drifted), run `active-work prompt` — it prints the same bootstrap prompt to stdout, cwd-resolved and side-effect-free (no auto-archive). The bundled `/aw-prompt` slash command wraps it and injects the output straight into the session.
 
-Because handoff and brief excerpt are already in your context, **do not re-read `brief.md` or `handoff.md`** at the top of the session. Jump straight to the highest-rank open task unless the user redirects you. If the user opens a slug without further instruction, ask "continue with `<top task title>`?" and proceed on confirmation.
+The brief excerpt is already in your context, so **do not re-read `brief.md`** at the top of the session. Current state needs no separate file — it is the open-loop section, derived fresh at every bootstrap from the session ledger. Jump straight to the highest-rank open task unless the user redirects you. If the user opens a slug without further instruction, ask "continue with `<top task title>`?" and proceed on confirmation.
+
+**Sibling sessions** (`# Another session may already be live on this initiative`): each bootstrap records a lease under `<active root>/.sessions/<slug>/` and warns when another session still holds one. A session launched via `aw` is reported as a live process — its pid is actually checked — while one bootstrapped through `open`/MCP is a 90-minute guess and is worded as one, because that path leaves no process to confirm. When the section appears, **ask the user which session owns the top task before starting it**. If yours is the second session, take distinct scope and record it with `active-work wrap --track adhoc`: a `canonical` wrap here buries the other session's mainline thread in the next bootstrap. When the initiative carries an agent-chat channel, also register under a name that distinguishes you and coordinate scope there. `--no-sibling-check` skips the probe on `open`/`prompt` (and, for `open`, the lease write); `--offline` skips it too. `active-work prompt` detects siblings but never records a lease of its own — it stays read-only. Dead leases are swept at the next bootstrap; `active-work doctor` reports the live/pruned counts.
 
 **Ad-hoc sessions** (`aw <slug> --adhoc`, also `open`/`prompt --adhoc`): the opening and closing directives change to say the session is scoped to ad-hoc work on the workstream — the context is background, *not* a directive. Do **not** offer to continue the top task; wait for the user to describe the specific ad-hoc task, then work it with the workstream context in mind. The bootstrap prompt itself carries this instruction, so follow whichever framing it renders.
 

package/skill/references/auditing-existing-work.md

@@ -46,7 +46,7 @@ active-work track gh:hjewkes/active-work#42 \
   --title "Dashboard load is sluggish on cold open"
 ```
 
-`active-work track` scaffolds the initiative (`brief.md` with frontmatter, empty `handoff.md`, empty `tasks/`, an `artifacts.yml` seeded with the source ref), then prints the new slug. Open it next:
+`active-work track` scaffolds the initiative (`brief.md` with frontmatter, empty `tasks/`, an `artifacts.yml` seeded with the source ref), then prints the new slug. Open it next:
 
 ```bash
 active-work open dashboard-perf
@@ -82,15 +82,13 @@ After triage, run the audit to catch issues:
 active-work audit
 ```
 
-Audit checks:
+`audit` is a cross-initiative summary, not a rule engine. It returns exactly three things:
 
-- Every active slug has a non-empty `handoff.md`
-- Every active slug has at least one open task (otherwise: should it be archived?)
-- `artifacts.yml` references resolve (PRs exist, branches exist locally, etc.)
-- Last session timestamp isn't stale beyond the configured threshold
-- No frontmatter validation errors
+- `initiatives` — every slug with its title, state, rank, `updated` date, and ship target, sorted by rank then state
+- `parse_errors` — slugs whose `brief.md` frontmatter failed validation, with the error
+- `worktree_conflicts` — worktree paths registered by more than one initiative
 
-Warnings are non-fatal. Fix them iteratively with `active-work set <slug> ...`, `active-work task add`, or `active-work archive`.
+For per-initiative health checks — staleness, loops hanging past 30 days, dangling `next_steps` refs — use `active-work lint` and `active-work doctor` instead. Nothing here is fatal; fix findings with `active-work set <slug> ...`, `active-work task add`, or `active-work archive`.
 
 ## Worked example
 
@@ -118,8 +116,14 @@ $ active-work drop claude:session/0192abc --reason "one-off debugging, no follow
 dropped
 
 $ active-work audit
-brain-inbox-rewrite: handoff.md is empty — add a one-paragraph status
-ok: 1 warning across 2 initiatives
+{
+  "initiatives": [
+    { "slug": "dashboard-perf", "title": "Dashboard cold-load perf", "state": "focused", "rank": 1, "updated": "2026-07-28" },
+    { "slug": "brain-inbox-rewrite", "title": "Brain inbox rewrite", "state": "focused", "rank": 2, "updated": "2026-07-28" }
+  ],
+  "parse_errors": [],
+  "worktree_conflicts": []
+}
 ```
 
 The user is now caught up. Continue with `active-work open dashboard-perf` (or whichever slug they want to push on first).

package/skill/references/cli-dev.md

@@ -19,6 +19,7 @@ If you are modifying the `active-work` skill, adding a CLI command, extending th
 | `src/templates/` | Mustache templates for scaffolding new initiatives. |
 | `src/bootstrap/` | Bootstrap prompt assembly used by `active-work open`. |
 | `src/discover/` | Discovery sources (gh, git, projects, Claude sessions). |
+| `src/sources/` | Reads `<slug>/sources/*.md` at call time. There is no sidecar index and no `sources:` frontmatter field — a stored list drifts from the directory, so the listing is always derived. |
 | `skill/` | This skill. Copied into `~/.claude/skills/active-work/` by `scripts/postinstall.js`. |
 | `scripts/` | npm lifecycle hooks: `postinstall.js`, `preuninstall.js`. |
 | `__tests__/` | Vitest tests; fixtures under `__tests__/fixtures/`. |
@@ -26,7 +27,7 @@ If you are modifying the `active-work` skill, adding a CLI command, extending th
 ## Adding a new command
 
 1. Create `src/commands/<name>.ts` exporting a `defineCommand({...})` entry. Define:
-   - `name` (e.g. `"task add"`)
+   - `name` (dot-separated, e.g. `"task.add"`)
    - `description`
    - `input` zod schema
    - `output` zod schema
@@ -46,7 +47,7 @@ If you are modifying the `active-work` skill, adding a CLI command, extending th
 `src/server/` runs hono on `127.0.0.1:7400` by default (override with `AW_PORT`). It serves:
 
 - `/rpc/<command>` — REST for every registry entry
-- `/ws` — WebSocket live feed (chokidar-backed filesystem events)
+- `/events` — SSE live-reload feed (`hono/streaming`), backed by a hand-rolled recursive `fs.watch` in `src/server/file-watch.ts` (not WebSocket, not chokidar), debounced and broadcast via `EventHub`
 - `/mcp` — MCP-over-HTTP transport
 - `/ui` — bundled dashboard SPA
 

package/skill/references/onboarding.md

@@ -36,19 +36,15 @@ ls ~/.claude/skills/active-work/
 
 ## 4. Run `active-work setup`
 
-`active-work setup` (Wave 6) is the interactive wizard that initializes data roots, registers the MCP server with Claude Code, and offers to install the daemon launchd plist. **It is not yet implemented.** Until it lands, you can prepare the data root manually:
-
 ```bash
-mkdir -p "${XDG_DATA_HOME:-$HOME/Library/Application Support}/active-work"
+active-work setup
 ```
 
-(On Linux this resolves to `~/.local/share/active-work/`; on macOS to `~/Library/Application Support/active-work/`.)
+This is the interactive wizard: it checks your Node version, creates the active/state/config data roots, writes a config stub, installs the skill and the `/aw-prompt` command (idempotently — safe to re-run), registers the MCP server with Claude Code (`claude mcp add --user @hjewkes/active-work -- active-work mcp serve --stdio`), offers to install daemon supervision (launchd on macOS, systemd with linger on Linux), offers to start the daemon, and offers to walk through discovering existing work.
 
-Register the MCP server with Claude Code manually for now:
+Use `active-work setup --yes` for a non-interactive run (skips prompts, assumes no for daemon start), or `--update` to allow it to overwrite an existing config stub.
 
-```bash
-claude mcp add --user @hjewkes/active-work -- active-work mcp serve --stdio
-```
+If the `claude` CLI isn't on your PATH, the MCP-registration step prints the `~/.claude.json` snippet to add by hand instead of failing.
 
 ## 5. Verify the install
 
@@ -61,7 +57,7 @@ active-work mcp status      # reports daemon state
 
 ## 6. Optional — start the daemon
 
-The daemon hosts MCP-over-HTTP, the REST API, the WebSocket live feed, and the dashboard.
+The daemon hosts MCP-over-HTTP, the REST API, an SSE live-reload feed (`/events`), and the dashboard.
 
 ```bash
 active-work mcp serve --detach