@staff0rd/assist 0.372.0 → 0.374.0

package/README.md

@@ -121,6 +121,8 @@ After installation, the `assist` command will be available globally. You can als
 
 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.
 
+Backlog item ids are written and displayed in an `a`-prefixed form (e.g. item 555 is `a555`) to disambiguate them from GitHub PR/issue numbers (`#42`) and Jira keys. Commands and web API routes that take an `<id>` accept either the prefixed form (`a555`) or a bare number (`555`).
+
 - `assist backlog [--dir <path>]` - Open the backlog tab in the web dashboard (same as `backlog web`). `--dir` overrides the directory used to resolve the current repository's git origin
 - `assist backlog init` - Create an empty backlog
 - `assist backlog list [--status <type>] [-a, --all] [--all-repos] [-v]` - List backlog items with status icons (alias: `ls`). Defaults to the current repository's todo/in-progress items; `--all` includes done/wontdo, `--all-repos` lists items across all repositories. Also available as the top-level shortcut `assist list` / `assist ls` with the same flags
@@ -163,7 +165,7 @@ The first backlog command in a repository that still has a local `.assist/backlo
 - `assist backlog web [-p, --port <number>] [--no-open]` - Open the backlog tab in the web dashboard (default port 3100); `--no-open` skips opening a browser on startup
 - `assist roam auth` - Authenticate with Roam via OAuth (opens browser, saves tokens to ~/.assist.yml)
 - `assist roam show-claude-code-icon` - Forward Claude Code hook activity to Roam local API
-- `assist run <name> [params...]` - Run a configured command from assist.yml (positional params are matched to `params` config; supports `pre` array of commands to run first). If `<name>` is purely numeric and matches no configured command, it is treated as an alias for `assist backlog run <name>` and forwards `--write`/`--no-write`/`-w`.
+- `assist run <name> [params...]` - Run a configured command from assist.yml (positional params are matched to `params` config; supports `pre` array of commands to run first). If `<name>` is a backlog item id (`a555` or a bare `555`) and matches no configured command, it is treated as an alias for `assist backlog run <name>` and forwards `--write`/`--no-write`/`-w`.
 - `assist run add` - Add a new run configuration to assist.yml and create a Claude command file
 - `assist run link <path> --prefix <prefix>` - Link run configurations from another project's assist.yml
 - `assist run remove <name>` - Remove a run configuration from assist.yml and delete its Claude command file
@@ -179,6 +181,7 @@ The first backlog command in a repository that still has a local `.assist/backlo
 - `assist verify hardcoded-colors` - Check for hardcoded hex colors in src/ (supports `hardcodedColors.ignore` globs in config)
 - `assist verify block-comments` - Fail on any comment on a changed line (staged + unstaged), whether newly added or edited, reporting each offending file:line; functional machine directives are exempt and `blockComments.ignore` globs in config scope which files are scanned. Yaml `.yml`/`.yaml` files are scanned for `#` comments with no directive exemptions
 - `assist verify forbidden-strings` - Check configured JSON files for disallowed values. Each `forbiddenStrings` rule names a `file`, a list of dot-`paths` to inspect (string or string[] values are scanned; other types skipped), and a `disallowed` wildcard matched via minimatch; any matching value fails the check. Zero rules is a no-op that passes
+- `assist verify config-keys` - Check that every leaf key in `assistConfigSchema` is surfaced in some command's `--help` via the `configHelp` helper. Fails when a schema key is documented by no command (add it with `configHelp`) or when a declared key is not in the schema. Keys not yet migrated are tracked in a `pendingConfigDocumentation` list that must be drained as commands adopt `configHelp`
 - `assist lint [-f, --fix]` - Run lint checks for conventions not enforced by oxlint (use `-f` to auto-fix)
 - `assist lint init` - Initialize oxlint with baseline linter config
 - `assist refactor check [pattern]` - Check for files that exceed the maximum line count

package/claude/commands/bug.md

@@ -69,12 +69,12 @@ Pass the description as real markdown with line breaks preserved (use `printf` o
 
 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.
+Then show the user the item was created and suggest they can run `assist backlog run a<id>` to start implementation.
 
-Finally, signal that the bug-filing task is complete, passing the created item id:
+Finally, signal that the bug-filing task is complete, passing the created item id (a-prefixed, e.g. `a555`):
 
 ```
-assist signal done <id> 2>&1
+assist signal done a<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/draft.md

@@ -102,15 +102,15 @@ Note the created item id from the output — you'll pass it to the done signal b
 Then add each phase:
 
 ```
-assist backlog add-phase <id> "Phase name" --task "Task 1" --task "Task 2" --manual-check "optional check" 2>&1
+assist backlog add-phase a<id> "Phase name" --task "Task 1" --task "Task 2" --manual-check "optional check" 2>&1
 ```
 
-Then show the user the item was created and suggest they can run `assist backlog run <id>` to start implementation.
+Then show the user the item was created and suggest they can run `assist backlog run a<id>` to start implementation.
 
-Finally, signal that the drafting task is complete, passing the created item id:
+Finally, signal that the drafting task is complete, passing the created item id (a-prefixed, e.g. `a555`):
 
 ```
-assist signal done <id> 2>&1
+assist signal done a<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/jira.md

@@ -22,7 +22,7 @@ These actions operate on a single Jira issue. Resolve it once:
 - Otherwise read it from the backlog item this session is working on — the one you are implementing, reviewing, or otherwise focused on (e.g. via `/next-backlog-item`, a `backlog run`, or earlier in this conversation). Get its id, then run:
 
   ```
-  assist backlog show <id> 2>&1
+  assist backlog show a<id> 2>&1
   ```
 
   Use the `Jira: <KEY>` line from the output.

package/claude/commands/subtask.md

@@ -9,14 +9,14 @@ You are adding a sub-task to the backlog item this session is working on by call
 
 Use the backlog item this session is working on — the one you are implementing, reviewing, or otherwise focused on (e.g. via `/next-backlog-item`, a `backlog run`, or earlier in this conversation). Use its id directly.
 
-If this session is not working on a backlog item, there is nothing to attach the sub-task to — tell the user there is no current item and ask them to run this from a session working on one (or to add the sub-task with `assist backlog add-subtask <id>` directly).
+If this session is not working on a backlog item, there is nothing to attach the sub-task to — tell the user there is no current item and ask them to run this from a session working on one (or to add the sub-task with `assist backlog add-subtask a<id>` directly).
 
 ## Step 2: Add the sub-task
 
 `$ARGUMENTS` is the sub-task title. Call the CLI command with the resolved id:
 
 ```
-assist backlog add-subtask <id> --title '<sub-task text>' 2>&1
+assist backlog add-subtask a<id> --title '<sub-task text>' 2>&1
 ```
 
 Use single quotes around the title to avoid shell escaping issues. The sub-task is created with status `todo`.