@staff0rd/assist 0.296.1 → 0.297.0

package/README.md

@@ -45,12 +45,12 @@ After installation, the `assist` command will be available globally. You can als
 - `/devlog` - Generate devlog entry for the next unversioned day
 - `/draft` - Draft a new backlog item with LLM-assisted questioning
 - `/forward-comments` - Split a coarse PR comment (e.g. from Slack) into per-line review comments on the current branch's PR, attributed to the original reviewer
-- `/handover` - Write a session handover note (`.assist/HANDOVER.md`) for the next conversation; archives any prior handover first. The SessionStart hook surfaces the handover at the start of the next session
+- `/handover` - Write a session handover note for the next conversation and save it to the backlog DB (scoped by git origin, never on disk). Can be run any number of times; each call appends a note with a one-line summary. The SessionStart hook advises how many unrecalled handovers exist
 - `/pr` - Raise a PR with a concise description
 - `/prs-slack <number>` - Post a PR's title and URL to the Slack channel configured in `prs.slack`
 - `/refactor` - Run refactoring checks for code quality
 - `/prompts` - Analyze denied tool calls and suggest settings changes to auto-allow recurring prompts
-- `/recall` - Recall context from the most recent prior session in this repo by summarising its transcript (skips sdk-cli-only sessions); read-only, emits a `# Recall` block in chat
+- `/recall` - Recall the most recent handover note for this repo from the backlog DB, emit it as a `# Recall` block, and mark it recalled. Reads DB handovers only (no transcripts or disk files)
 - `/refine` - Refine an existing backlog item through conversation
 - `/restructure` - Analyze and restructure tightly-coupled files
 - `/review-comments` - Process PR review comments one by one
@@ -107,7 +107,7 @@ After installation, the `assist` command will be available globally. You can als
   - `--top <n>` - Only report the top `n` repos by commit count; committers and the author breakdown then cover those repos only (also caps the per-repo author queries, which speeds up large orgs)
   - `--json` - Output all three views as structured JSON instead of tables
 - `assist news add [url]` - Add an RSS feed URL (rendered in the sessions web News tab)
-Backlog data is stored in a global Postgres database (shared across all repos, scoped per repository by git origin), so a connection string is required. Set it via the `ASSIST_BACKLOG_DATABASE_URL` environment variable or the `backlog.databaseUrl` key in `assist.yml`; the environment variable takes precedence. Without one, every `assist backlog` command exits with a setup message. (There is no SQLite/JSONL fallback.) Commands default to the current repository's items; pass `--all-repos` to span every repository.
+Backlog data is stored in a global Postgres database (shared across all repos, scoped per repository by git origin), so a connection string is required. Set it via the `ASSIST_DATABASE_URL` environment variable or the `database.url` key in `assist.yml`; the environment variable takes precedence. Without one, every `assist backlog` command exits with a setup message. (There is no SQLite/JSONL fallback.) Commands default to the current repository's items; pass `--all-repos` to span every repository.
 
 The first backlog command in a repository that still has a local `.assist/backlog.jsonl` automatically migrates it into Postgres — but only as a one-time bootstrap into an empty origin. If Postgres has **no** items for the repo's origin yet, it runs `git pull` (best-effort) to fetch the latest committed copy, imports every item under the origin with fresh global IDs (rewriting links to other items), and verifies the result. If Postgres **already** has items for that origin (a prior run, another clone, or a pre-seeded database), the import is skipped to avoid creating duplicates. Either way the local `.assist/backlog.jsonl` and `.assist/backlog.db` are renamed to `*.bak`, so the migration never re-runs and a local copy is retained.
 
@@ -224,9 +224,10 @@ The first backlog command in a repository that still has a local `.assist/backlo
 - `assist sql tables [connection]` - List tables in the connected database (via INFORMATION_SCHEMA.TABLES)
 - `assist sql columns <table> [connection]` - List columns for a table (use `schema.table` for non-default schema; via INFORMATION_SCHEMA.COLUMNS)
 - `assist screenshot <process>` - Capture a screenshot of a running application window (e.g. `assist screenshot notepad`). Output directory is configurable via `screenshot.outputDir` (default `./screenshots`)
-- `assist handover archive [--suffix <s>]` - Archive the current `.assist/HANDOVER.md` to `.assist/handovers/archive/<ISO-ts>[-<suffix>].md`. Prints the archive path; no-op when no handover exists
-- `assist handover summarise <jsonl>` - Print a one-line summary of a session JSONL via `claude -p --model haiku`. Filters sdk-cli-only transcripts and sets a recursion-guard env var so the inner SessionStart hook short-circuits
-- `assist handover load` - SessionStart hook entry point: reads `{cwd, session_id}` from stdin, and only when `.assist/HANDOVER.md` exists archives it and emits `{ hookSpecificOutput: { hookEventName: "SessionStart", additionalContext }, systemMessage }`. Emits nothing when no handover exists (use `/recall` to pull prior-session context on demand). Honors `_CLAUDE_HOOK_SUMMARISE_RUNNING` so nested invocations short-circuit silently
+- `assist handover save --summary <s>` - Save a session handover note to the backlog DB (content read from stdin), scoped by the repo's git origin. Appends a new row each call; `--summary` is the one-line description shown when recalling
+- `assist handover list` - List unrecalled handovers for this repo, most recent first, one per line as tab-separated `id`, ISO-8601 created timestamp, and one-line summary. Prints nothing when none are pending
+- `assist handover recall [id]` - Print an unrecalled handover for this repo and mark it recalled (so it drops out of the SessionStart advisory and future recalls). Recalls the most recent by default, or the given `id`. Prints nothing when none match
+- `assist handover load` - SessionStart hook entry point: reads `{cwd, session_id}` from stdin, migrates any legacy disk handovers (`.assist/HANDOVER.md` and notes under `.assist/handovers/`) into the backlog DB then deletes them, and emits `{ hookSpecificOutput: { hookEventName: "SessionStart" }, systemMessage }` advising how many unrecalled handovers exist. Emits nothing when there are none (use `/recall` to load one)
 - `assist mermaid export [file.md]` - Render each fenced mermaid block to `<stem>-<index>.svg` via [Kroki](https://kroki.io). With no file, scans `*.md` in the current directory (non-recursive). Use `--out <dir>` to override the output directory. Use `--index <n>` to render only the nth mermaid block (1-based; requires a file argument). Endpoint is configurable via `mermaid.krokiUrl` (default `https://kroki.io`).
 - `assist prompts` - Show top 10 denied tool calls by frequency with count and repo breakdown
 - `assist coverage` - Print global statement coverage percentage

package/claude/commands/handover.md

@@ -2,17 +2,13 @@
 description: Write a session handover note for the next conversation
 ---
 
-Write a concise handover note for the next session working on this repo. The note captures everything the next session needs to pick up where this one left off.
+Write a concise handover note for the next session working on this repo, then save it to the backlog database. The note captures everything the next session needs to pick up where this one left off.
 
-## Step 1: Archive the previous handover
+Handover notes are stored in the backlog DB (scoped by git origin), never on disk. `/handover` can be run any number of times — each run appends a new note.
 
-Run `assist handover archive` first. If a `.assist/HANDOVER.md` already exists, it is moved to `.assist/handovers/archive/<ISO-ts>.md` (path printed to stdout). If no handover exists, the command is a no-op.
+## Step 1: Compose the note
 
-Do NOT skip this step — re-running `/handover` must never overwrite a prior unsaved note.
-
-## Step 2: Write `.assist/HANDOVER.md`
-
-Always operate on the current working directory. Write the file at `.assist/HANDOVER.md` (create the `.assist/` directory if needed). Use the following sections, in this order, and omit none even if empty (use a single "—" placeholder line):
+Always operate on the current working directory. Compose the note body using the following sections, in this order, and omit none even if empty (use a single "—" placeholder line):
 
 ```markdown
 # Handover
@@ -46,9 +42,24 @@ Non-obvious gotchas, in-flight refactors, broken tests, half-applied changes, or
 Things that have been ruled out, attempted unsuccessfully, or that the user has explicitly asked not to do. Saves the next session from repeating dead ends.
 ```
 
+## Step 2: Save the note
+
+Author a one-line summary (under 100 chars) describing the note — this is what `/recall` shows when listing notes. Then save it by piping the composed note into `assist handover save` via stdin:
+
+```bash
+assist handover save --summary "<one-line summary>" <<'HANDOVER_EOF'
+# Handover
+
+## Current Task
+...
+HANDOVER_EOF
+```
+
+Use a quoted heredoc delimiter (`<<'HANDOVER_EOF'`) so nothing in the note body is expanded by the shell. The command resolves the repo's git origin and inserts a new row in the backlog DB.
+
 ## Guidelines
 
 - Keep each section terse — bullets, not paragraphs. The next session will read this cold.
 - Reference concrete file paths and line numbers wherever it helps orientation.
 - Do not summarise context that is already obvious from the code or git history.
-- Do not commit `.assist/HANDOVER.md` — it is gitignored.
+- Do not write `.assist/HANDOVER.md` or any other file — handovers live only in the backlog DB.

package/claude/commands/recall.md

@@ -2,51 +2,54 @@
 description: Recall context from the most recent prior session in this repo
 ---
 
-Summarise the most recent **prior** Claude Code session for this working directory, so the current session can pick up where it left off. Always operate on the current working directory; do not ask which repo to recall.
+Load the most recent handover note for this repo so the current session can pick up where the last one left off. Always operate on the current working directory; do not ask which repo to recall.
 
-## Step 1: Locate the prior session JSONL
+Handover notes are stored in the backlog database (scoped by git origin), authored by `/handover`. `/recall` reads only those notes — it does not read session transcripts or any disk files.
 
-Sessions are stored under `~/.claude/projects/<encoded-cwd>/`, where `<encoded-cwd>` is the absolute current working directory with every `/` replaced by `-` (e.g. `/home/me/git/foo` → `-home-me-git-foo`).
+## Step 1: List unrecalled notes
 
-1. Compute `<encoded-cwd>` from the absolute path of the current working directory. Do not hard-code a path — derive it.
-2. List `*.jsonl` files in that directory, newest-first by mtime.
-3. Walk the list and pick the **first** file that satisfies all of:
-   - It is **not** the current session's JSONL (the current session id is in `$CLAUDE_SESSION_ID` if set, or matches the JSONL whose tail you would actively be appending to right now — when in doubt, skip the newest if it could be this session).
-   - It is **not** an sdk-cli-only transcript. A transcript is sdk-cli-only when every `type:"user"` entry with text content has `"entrypoint":"sdk-cli"`. If at least one `type:"user"` entry has `"entrypoint":"cli"` (or any value other than `sdk-cli`), the transcript counts as a real interactive session and is eligible.
+Run:
 
-If no eligible prior session exists, emit:
+```bash
+assist handover list
+```
 
-```markdown
-# Recall
+This prints one unrecalled handover per line, most recent first, as tab-separated `id`, ISO-8601 created timestamp, and one-line summary.
 
-No prior session found for this directory.
-```
+- **No output** — there are no unrecalled handovers. Skip to Step 3 and emit the "no handover" block.
+- **Exactly one line** — recall it directly in Step 2 with no id.
+- **More than one line** — present the summaries (with their created timestamps) to the user and ask which to recall, then pass the chosen `id` in Step 2.
+
+## Step 2: Recall the chosen note
 
-…and stop.
+Run:
 
-## Step 2: Emit the # Recall block
+```bash
+assist handover recall [id]
+```
 
-Read enough of the chosen JSONL to understand what the previous session was working on (recent human user turns are the highest signal — skip tool results and assistant messages). Then emit a single `# Recall` block directly in chat. **Do not write any file.**
+With no argument this recalls the most recent unrecalled handover; with an `id` it recalls that specific note. Either way it prints the note's content to stdout and marks it recalled (so it drops out of the SessionStart advisory and future recalls).
 
-Use this structure:
+## Step 3: Surface it
+
+If the command printed content, present it to the user as a `# Recall` block so they can resume:
 
 ```markdown
 # Recall
 
-**Previous session:** <one-line summary of what the prior session was doing>
+<the recalled handover content>
+```
+
+If the command printed nothing, there are no unrecalled handovers — emit:
 
-**Key points:**
-- <bullet> — what was happening, decisions made, or where it stopped
-- <bullet>
-- <bullet>
+```markdown
+# Recall
 
-**Suggested next step:** <one concrete thing to do now, or "—" if unclear>
+No handover found for this repo.
 ```
 
 ## Guidelines
 
 - Always operate on the current working directory — never guess or substitute another repo.
-- Keep the summary terse. The user is reading it cold at the start of a new session.
-- Prefer concrete file paths, command names, and backlog IDs over vague descriptions.
-- If `.assist/HANDOVER.md` exists, the SessionStart hook will already have surfaced it — `/recall` complements that by pulling context from the prior transcript, not the handover file.
-- Do not modify any files. `/recall` is read-only.
+- `/recall` is the counterpart to `/handover`: it reads notes the previous session authored, nothing else.
+- Do not write or modify any files.