@staff0rd/assist 0.318.1 → 0.318.3

package/README.md

@@ -5,6 +5,7 @@ A CLI tool for enforcing determinism in LLM development workflow automation.
 See [devlog](https://staffordwilliams.com/devlog/assist/) for latest features.
 
 ## Installation
+
 You can install `assist` globally using npm:
 
 ```bash
@@ -13,6 +14,7 @@ assist sync
 ```
 
 ## Updating
+
 ```bash
 assist update
 ```
@@ -68,7 +70,7 @@ After installation, the `assist` command will be available globally. You can als
 - `/seq` - Query Seq logs from a URL or filter expression
 - `/sql` - Query a MSSQL database via assist sql
 - `/verify` - Run all verification commands in parallel
-- `/verify-new` - Add a new verify:* run command to assist.yml
+- `/verify-new` - Add a new verify:\* run command to assist.yml
 - `/transcript-format` - Format meeting transcripts from VTT files
 - `/transcript-summarise` - Summarise transcripts missing summaries
 - `/voice-setup` - Download required voice models (VAD, STT)
@@ -113,7 +115,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_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.
+  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.
 
@@ -159,7 +161,7 @@ The first backlog command in a repository that still has a local `.assist/backlo
 - `assist config get <key>` - Get a config value
 - `assist config list` - List all config values
   - `prs.slack` - The Slack channel (e.g. `#example`) that `/prs-slack` posts pull requests to via the Slack MCP connector
-- `assist verify` - Run all verify:* commands in parallel (from run configs in assist.yml and scripts in package.json)
+- `assist verify` - Run all verify:\* commands in parallel (from run configs in assist.yml and scripts in package.json)
 - `assist verify all` - Run all checks, ignoring diff-based filters
 - `assist verify --measure` - After the run, print a summary table of each command's status and duration (slowest first) plus a wall-clock total
 - `assist verify init` - Add verify scripts to a project (writes to `assist.yml` by default; pass `--package-json` to write to `package.json` scripts instead)
@@ -268,10 +270,12 @@ The first backlog command in a repository that still has a local `.assist/backlo
 Web sessions are owned by a long-lived daemon process, not the web server: the server is a thin client that relays WebSocket traffic to the daemon over a local IPC socket (unix domain socket at `~/.assist/daemon/daemon.sock`; named pipe `\\.\pipe\assist-sessions-daemon` on Windows). Restarting the web server leaves sessions running with scrollback intact. The daemon logs to `~/.assist/daemon/daemon.log` (timestamped lines tagged with the daemon's pid, including why it spawned and which sessions it restored) and auto-exits once no sessions remain and no client has been connected for 60 seconds (it is respawned on demand by the web server). Daemon spawning is arbitrated by an `O_EXCL` lockfile so racing clients start at most one daemon; sessions are only restored after the daemon owns the IPC socket, and a daemon that loses ownership of `daemon.pid` shuts down its sessions and exits rather than running orphaned.
 
 From WSL, the selector can also surface and drive Windows-host repos (requires `assist` installed on the Windows host). Config keys:
+
 - `sessions.windowsProjectsRoot` — the Windows `.claude/projects` directory as seen from WSL (e.g. `/mnt/c/Users/<user>/.claude/projects`); enables discovery of Windows-host repos, tagged with a `Windows` badge. Selecting one launches a native assist daemon on Windows and runs an interactive session there.
 - `sessions.windowsDaemonHost` / `sessions.windowsDaemonPort` — where the WSL daemon reaches the native Windows daemon (defaults `127.0.0.1` / `51764`; set the host to the Windows IP on WSL2 NAT-mode networking).
 
 When iterating on assist itself: web server changes only need the `assist sessions` process restarted — sessions survive. Daemon/session-core changes need `assist daemon restart` to load the new code; this kills the PTYs, then claude sessions — including assist sessions that wrap claude, like `assist draft` — are auto-respawned via `claude --resume` with scrollback starting fresh, while run sessions (and assist sessions whose claude sessionId was never discovered) reappear as not-restored tiles that can be retried.
+
 - `assist next [id] [--once]` - Alias for `backlog next [id]`; `--once` exits after the first completed item run instead of prompting for another
 - `assist draft [description] [--once]` (alias: `feat`) - Launch Claude in `/draft` mode, chain into next on `/next` signal; an optional `description` is forwarded as `/draft <description>`; `--once` exits when the done signal arrives after the initial draft completes
 - `assist bug [description] [--once]` - Launch Claude in `/bug` mode, chain into next on `/next` signal; an optional `description` is forwarded as `/bug <description>`; `--once` exits when the done signal arrives after the initial bug report completes
@@ -284,7 +288,6 @@ When `commit.pull` is enabled in config, `assist draft`, `assist bug`, `assist r
 
 When `commit.expectedBranch` is set (e.g. `main`), `assist commit` prints a prominent warning if HEAD is on any other branch before committing — so work committed (and pushed) on a stray branch in a repo that lands directly on the expected branch isn't silently orphaned. The warning is non-blocking: the commit still proceeds. With the key unset, behaviour is unchanged and no branch check runs.
 
-
 ## netcap browser extension
 
 `assist netcap` only runs the receiver; the browser side is a raw Manifest V3 extension (no build step) under `netcap-extension/`. A MAIN-world content script patches `fetch`/`XMLHttpRequest` to capture `{url, method, status, requestBody, responseBody, timestamp}`, relays each entry to the background service worker (`window.postMessage` → `chrome.runtime.sendMessage`), and the background worker POSTs it to the receiver. The XHR patch reads the response across every `responseType` (`json`, `blob`, `arraybuffer`, `document`, not just `text`) — LinkedIn's voyager GraphQL calls use `responseType: "json"`, which exposes no `responseText`, so reading `responseText` alone captured those bodies empty. Forwarding happens in the background context, so the page's CSP (`connect-src`) never blocks it — the limitation that killed the earlier console-paste approach.

package/claude/CLAUDE.md

@@ -3,20 +3,23 @@ After any code change, run `/verify` to ensure all checks pass.
 `assist` is installed globally. Use it directly (e.g., `assist commit "message"`).
 
 When renaming TypeScript files or symbols, use the refactor commands instead of doing it manually:
+
 - `assist refactor rename file <source> <destination>` — rename/move a file and update all imports
 - `assist refactor rename symbol <file> <oldName> <newName>` — rename a variable, function, class, or type across the project
 - `assist refactor extract <file> <functionName> <destination>` — extract a function and its private dependencies to a new file
-All default to dry-run; add `--apply` to execute.
-When using extract, name the destination file after the exported function (e.g. `updateWorkerCapacity.ts` for `updateWorkerCapacity`) to satisfy `useFilenamingConvention` lint rules.
+  All default to dry-run; add `--apply` to execute.
+  When using extract, name the destination file after the exported function (e.g. `updateWorkerCapacity.ts` for `updateWorkerCapacity`) to satisfy `useFilenamingConvention` lint rules.
 
 Do not modify `claude/settings.json` without asking the user first. Only read-only commands should be added to the allow list — write operations (add, remove, set, delete) must require confirmation.
 
 ## Fetching Jira context
-When the user mentions a Jira issue key (e.g. `BAD-671`, `PROJ-123`), use the Atlassian MCP to fetch context.
 
+When the user mentions a Jira issue key (e.g. `BAD-671`, `PROJ-123`), use the Atlassian MCP to fetch context.
 
 ## Commenting code
+
 Do not include comments for standard logic or syntax. Only comment if the specific line involves unintuitive complexity or a hack.
 
 ## Backlog items, PRs, and commits
+
 Do not mention assist backlog items in PR descriptions or PR comments. The reference goes the other way: mention the relevant commits or PRs in the assist backlog item.

package/claude/commands/bug.md

@@ -33,6 +33,7 @@ Show the user the bug report:
 **Actual:** ...
 
 **Acceptance Criteria:**
+
 - (conditions that confirm the bug is fixed)
 
 Do NOT generate a plan — the implementer will determine how to fix it.
@@ -44,15 +45,19 @@ Ask the user if they want to change anything. Iterate until they confirm.
 ## Step 5: Save
 
 Once confirmed, add the item via CLI and capture the id it prints:
+
 ```
 assist backlog add --name "Bug title" --type bug --desc "**Repro:**\n1. ...\n\n**Expected:** ...\n\n**Actual:** ..." --ac "criterion 1" --ac "criterion 2" 2>&1
 ```
+
 Note the created item id from the output — you'll pass it to the done signal below.
 
 Then show the user the item was created and suggest they can run `assist backlog run <id>` to start implementation.
 
 Finally, signal that the bug-filing task is complete, passing the created item id:
+
 ```
 assist signal done <id> 2>&1
 ```
+
 This lets a wrapping `assist bug --once` session end and surfaces the created item id to the session card; in a plain interactive session it has no effect.

package/claude/commands/comment.md

@@ -12,6 +12,7 @@ Parse `$ARGUMENTS` as a comma-separated list of item numbers (e.g. `1,2` or `1,2
 ## Finding the Referenced List
 
 Look back through the conversation for the most recent numbered list of issues, suggestions, or comments. Each item should have enough context to determine:
+
 - **path**: the file path
 - **line**: the line number
 - **body**: a concise comment describing the issue
@@ -29,6 +30,7 @@ assist prs comment <path> <line> '<body>' 2>&1
 **Important:** Always use single quotes around `<body>`, never double quotes. Double quotes cause shell escaping issues with backticks and special characters.
 
 The body must:
+
 - Be a clear, concise description of the issue (1-2 sentences)
 - Not contain "claude" or "opus" (case-insensitive) — the command will reject it
 - Not contain single quotes (reword to avoid them)

package/claude/commands/commit.md

@@ -7,10 +7,12 @@ Review the git status and create a commit with only the files that are relevant
 First run `assist commit status` to see the current state of the working tree.
 
 Then either:
+
 - `assist commit "your message"` to commit already-staged changes, or
 - `assist commit "your message" <file1> <file2> ...` to stage files and commit
 
 Where:
+
 - The first argument is the commit message
 - Any subsequent arguments are paths to git add before committing
 - The commit message is 40 characters or less

package/claude/commands/draft.md

@@ -30,9 +30,11 @@ Once you have enough context, propose a complete backlog item. Show it to the us
 **Type:** story or bug
 **Description:** 1-3 sentences
 **Acceptance Criteria:**
+
 - (specific, testable criteria)
 
 **Plan:**
+
 - Phase 1: (name) — tasks...
 - Phase 2: (name) — tasks... [manual checks: ...]
 
@@ -41,12 +43,14 @@ Once you have enough context, propose a complete backlog item. Show it to the us
 **Phases must be vertical slices, not horizontal layers.** Each phase should deliver a thin, working increment of the feature that can be verified end-to-end. Do NOT decompose by architectural layer (e.g. "Phase 1: schema changes", "Phase 2: backend API", "Phase 3: UI"). Instead, each phase should cut through all necessary layers to produce something observable.
 
 Bad (horizontal):
+
 - Phase 1: Add database schema and types
 - Phase 2: Build API endpoints
 - Phase 3: Create UI components
 - Phase 4: Wire everything together
 
 Good (vertical):
+
 - Phase 1: Minimal working feature (hardcoded/simplified) visible end-to-end
 - Phase 2: Add real data handling and validation
 - Phase 3: Polish edge cases and error states
@@ -58,6 +62,7 @@ Good (vertical):
 - If a feature spans backend + UI, each phase carries its slice through both — e.g. "Phase 1: endpoint + UI button that calls it", not "Phase 1: endpoint, Phase 2: button".
 
 Two tests for each phase before proposing the plan:
+
 1. **Observable**: can you answer "does this work?" by running or inspecting the result? If a phase only produces internal plumbing with no observable effect, it's horizontal — restructure it.
 2. **Self-contained**: would `assist verify` pass with only this phase's code committed — no unused exports, no dead stubs awaiting a later phase? If not, merge the producer and its consumer into the same phase.
 
@@ -74,12 +79,15 @@ Ask the user if they want to change anything. Iterate until they confirm.
 Once confirmed, create the item and its phases via CLI commands.
 
 First, add the item and capture the id it prints:
+
 ```
 assist backlog add --name "Item name" --type story --desc "Description text" --ac "criterion 1" --ac "criterion 2" 2>&1
 ```
+
 Note the created item id from the output — you'll pass it to the done signal below.
 
 Then add each phase:
+
 ```
 assist backlog add-phase <id> "Phase name" --task "Task 1" --task "Task 2" --manual-check "optional check" 2>&1
 ```
@@ -87,7 +95,9 @@ assist backlog add-phase <id> "Phase name" --task "Task 1" --task "Task 2" --man
 Then show the user the item was created and suggest they can run `assist backlog run <id>` to start implementation.
 
 Finally, signal that the drafting task is complete, passing the created item id:
+
 ```
 assist signal done <id> 2>&1
 ```
+
 This lets a wrapping `assist draft --once` session end and surfaces the created item id to the session card; in a plain interactive session it has no effect.

package/claude/commands/forward-comments.md

@@ -32,7 +32,7 @@ If either is missing or ambiguous, ask before proceeding. The PR is always the c
 
    Rules for the quote:
    - **Quote verbatim.** Preserve the reviewer's exact wording, including typos, repeated words, odd spacing, and punctuation. Do not paraphrase, "fix," or tidy. The reviewer's voice matters.
-   - **Drop framing prose.** Only the actionable suggestion that maps to *this specific line* should appear. If the reviewer's sentence opens with broad framing ("the only thing that's slightly naff is...") and then states the suggestion, quote only the suggestion part.
+   - **Drop framing prose.** Only the actionable suggestion that maps to _this specific line_ should appear. If the reviewer's sentence opens with broad framing ("the only thing that's slightly naff is...") and then states the suggestion, quote only the suggestion part.
    - **Add backticks around symbols.** Identifier names, type names, file names, and function names should be wrapped in backticks (e.g. `` `displayValue` ``, `` `SurveyQuestionModel` ``, `` `resolvers.ts` ``) even if the reviewer didn't use them. This is the only formatting change permitted.
    - **No editorialising.** Do not add your own commentary, explanation, or restatement. The whole body is the attribution line plus the quote.
 

package/claude/commands/next.md

@@ -5,6 +5,7 @@ description: Signal completion and chain into the next backlog item
 You are done with the current session. Write the signal file to terminate this session and chain into the next backlog item.
 
 Run:
+
 ```
 assist signal next $ARGUMENTS
 ```

package/claude/commands/prompts.md

@@ -15,6 +15,7 @@ Otherwise, analyze each entry and suggest specific changes to auto-allow the rec
 Present your suggestions as a numbered list with the specific change for each. Group related suggestions together.
 
 **Important:**
+
 - Only suggest allowing read-only, non-destructive commands
 - Never suggest allowing write operations (git push, rm, npm publish, etc.) without flagging them as risky
 - Reference the deny reason from the output to explain why each command was blocked

package/claude/commands/refine.md

@@ -34,6 +34,7 @@ Ask one focused question at a time. Wait for the user's response before continui
 Based on the user's input, apply changes using the appropriate commands. Always append `2>&1` to each command.
 
 **To update item fields:**
+
 ```
 assist backlog update-field <id> --name "New name"
 assist backlog update-field <id> --desc "New description"
@@ -44,6 +45,7 @@ assist backlog update-field <id> --ac "criterion 1" --ac "criterion 2"
 Note: `--ac` replaces all acceptance criteria, so include the full list (both existing and new).
 
 **To modify a plan phase** (phase is 0-indexed):
+
 ```
 assist backlog update-phase <id> <phase> --name "New phase name"
 assist backlog update-phase <id> <phase> --task "Task 1" --task "Task 2"
@@ -53,11 +55,13 @@ assist backlog update-phase <id> <phase> --manual-check "Check 1"
 Note: `--task` and `--manual-check` replace the full list for that phase, so include all items.
 
 **To remove a plan phase:**
+
 ```
 assist backlog remove-phase <id> <phase>
 ```
 
 **To add a new plan phase:**
+
 ```
 assist backlog add-phase <id> "Phase name" --task "Task 1" --task "Task 2"
 ```
@@ -71,6 +75,7 @@ When adding or restructuring plan phases, follow the same rules as /draft:
 - If the user proposes a horizontal split, point out that the earlier phase won't verify (knip will flag the unused exports) and suggest a vertical restructure instead.
 
 **To add a comment** (for context, decisions, or notes that don't fit in fields):
+
 ```
 assist backlog comment <id> "Comment text"
 ```
@@ -84,7 +89,9 @@ Ask if there is anything else to refine. Continue the conversation until the use
 ## Step 5: Signal completion
 
 Once the user confirms they are done refining, signal that the task is complete:
+
 ```
 assist signal done 2>&1
 ```
+
 This lets a wrapping `assist refine --once` session end; in a plain interactive session it has no effect.

package/claude/commands/seq.md

@@ -7,10 +7,12 @@ The user wants to query Seq log events. The argument is either a Seq UI URL or a
 ## If the argument is a URL
 
 Parse it to extract:
+
 1. **Base URL** — the origin (e.g., `http://localhost:5341`)
 2. **Filter** — URL-decode the `filter` query parameter from the fragment (after `#`). For example, from `http://localhost:5341/#/events?filter=JobId%20%3D%3D%20%22abc%22`, extract filter `JobId == "abc"`.
 
 Then determine the correct connection:
+
 - Run `assist seq auth list` to see configured connections.
 - Match the base URL from the parsed URL against a connection's URL.
 - If a match is found, use that connection name with `-c <name>`.

package/claude/commands/strip-comments.md

@@ -34,7 +34,7 @@ Read each file and remove only comments that violate the policy:
 **Never remove** the following, even if they look like noise:
 
 - **Functional directives** that the toolchain acts on: `eslint-disable*`, `@ts-expect-error`, `@ts-ignore`, `oxlint-disable`, `prettier-ignore`, `// @ts-nocheck`, coverage pragmas (`c8 ignore`, `istanbul ignore`), `noqa`, `type: ignore`, `#pragma`, `//go:`-style directives, and similar.
-- **Comments marking a genuine hack or workaround** — anything explaining *why* non-obvious code exists, including `HACK`/`WORKAROUND`/`FIXME`/`TODO` notes, links to issues, or rationale the code cannot convey on its own.
+- **Comments marking a genuine hack or workaround** — anything explaining _why_ non-obvious code exists, including `HACK`/`WORKAROUND`/`FIXME`/`TODO` notes, links to issues, or rationale the code cannot convey on its own.
 - **Doc comments** that form part of an API contract (JSDoc/TSDoc, XML doc comments, docstrings) unless they only restate the signature.
 
 When in doubt, keep the comment. The cost of leaving a borderline comment is far lower than deleting one that carries intent.

package/claude/commands/test-cover.md

@@ -26,6 +26,7 @@ From the uncovered files, prioritise by:
 3. **Complexity** — files with branching logic, edge cases, or error handling
 
 Skip files that are primarily:
+
 - Thin CLI wrappers (just parse args and call another function)
 - UI components (React/TSX)
 - Files that only re-export or wire things together
@@ -63,29 +64,30 @@ Example:
 
 ```typescript
 describe("parseToken", () => {
-  describe("when given a valid token", () => {
-    it("should return the decoded payload", () => {
-      const token = createToken({ sub: "user-1" });
+	describe("when given a valid token", () => {
+		it("should return the decoded payload", () => {
+			const token = createToken({ sub: "user-1" });
 
-      const result = parseToken(token);
+			const result = parseToken(token);
 
-      expect(result.sub).toBe("user-1");
-    });
-  });
+			expect(result.sub).toBe("user-1");
+		});
+	});
 
-  describe("when given an expired token", () => {
-    it("should throw an expiration error", () => {
-      const token = createToken({ exp: pastDate() });
+	describe("when given an expired token", () => {
+		it("should throw an expiration error", () => {
+			const token = createToken({ exp: pastDate() });
 
-      expect(() => parseToken(token)).toThrow("expired");
-    });
-  });
+			expect(() => parseToken(token)).toThrow("expired");
+		});
+	});
 });
 ```
 
 ### Coverage targets
 
 Cover:
+
 - Happy path for each exported function
 - Edge cases (empty input, undefined, boundary values)
 - Error cases and invalid input

package/claude/commands/test-review.md

@@ -18,21 +18,25 @@ For each test file, read both the test and the source file it covers. You need b
 Assess each test file against these criteria:
 
 ### Correctness
+
 - Do assertions actually verify the behaviour, or are they tautological (e.g., testing that a mock returns what you told it to)?
 - Are expected values correct and meaningful, not just copied from implementation output?
 - Do tests assert the right thing — return values, side effects, thrown errors — for each scenario?
 
 ### Coverage of behaviour
+
 - Are all exported functions tested?
 - Are conditional branches exercised (if/else, switch, early returns, error paths)?
 - Are edge cases covered (empty input, null/undefined, boundary values, large input)?
 - Are error cases tested (invalid arguments, missing data, thrown exceptions)?
 
 ### Test independence
+
 - Can each test run in isolation, or do tests depend on shared mutable state or execution order?
 - Are mocks reset properly between tests?
 
 ### BDD structure and Arrange-Act-Assert
+
 - Does the outer `describe` name the function or module under test?
 - Do inner `describe("when ...")` blocks group tests by shared setup/scenario?
 - Do `it` blocks use `should` phrasing with bare outcomes (e.g., `it("should allow")`, `it("should reject")`)? State specifiers (flags, syntax variants, conditions) belong in `when` blocks, never in `it` descriptions.
@@ -40,11 +44,13 @@ Assess each test file against these criteria:
 - Are assertions minimal per test — ideally one, at most two closely related? If multiple things are asserted about the same action, are they split into separate `it` blocks under the same `describe("when ...")`?
 
 ### Mocking discipline
+
 - Are mocks used only when necessary (external I/O, complex dependencies)?
 - Do mocks faithfully represent the real dependency's contract, or do they mask bugs?
 - Is there a risk that mocked tests pass but real integration would fail?
 
 ### Missing tests
+
 - Are there exported functions or significant code paths with no corresponding test?
 - Are there recently added functions (check git log) that lack tests?
 
@@ -57,12 +63,15 @@ For each test file, report:
 **Verdict:** Good / Needs improvement / Weak
 
 **Strengths:**
+
 - (what the tests do well)
 
 **Issues:**
+
 - (specific problems, each with a concrete recommendation)
 
 **Missing coverage:**
+
 - (untested functions or paths, with suggested test cases)
 
 ## Step 5: Summary

package/dist/index.js

@@ -6,7 +6,7 @@ import { Command } from "commander";
 // package.json
 var package_default = {
   name: "@staff0rd/assist",
-  version: "0.318.1",
+  version: "0.318.3",
   type: "module",
   main: "dist/index.js",
   bin: {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@staff0rd/assist",
-	"version": "0.318.1",
+	"version": "0.318.3",
 	"type": "module",
 	"main": "dist/index.js",
 	"bin": {