@staff0rd/assist 0.405.0 → 0.407.0

package/README.md

@@ -162,7 +162,7 @@ Backlog item ids are written and displayed in an `a`-prefixed form (e.g. item 55
 - `assist backlog run <id>` - Run a backlog item's plan phase-by-phase with Claude; `--resume-session <id>` resumes an interrupted Claude session for the current phase (used by the sessions daemon when it restarts a running item)
 - `assist backlog export [file]` - Export every table in the backlog database (discovered by live schema introspection, so new tables are covered automatically) to a file, or stdout if omitted
 - `assist backlog import [file]` - Restore every table present in a dump (file or stdin) back into the backlog database in foreign-key-safe order, faithfully replacing all data and resyncing identity sequences; prompts for confirmation (use `-y, --yes` to skip; required when reading from stdin)
-- `assist backlog associate-jira <id> [key]` - Associate a Jira ticket with a backlog item; validates the key shape, fetches the issue to confirm it exists, and stores the key (re-running with a different key replaces it). Clears any GitHub issue on the item (one external tracker per item). Use `--clear` to remove the association
+- `assist backlog associate-jira <id> [key]` - Associate a Jira ticket with a backlog item; accepts a bare key (`PROJ-123`) or an Atlassian browse URL, validates the key shape, fetches the issue to confirm it exists, and stores the key (re-running with a different key replaces it). Clears any GitHub issue on the item (one external tracker per item). Use `--clear` to remove the association
 - `assist backlog associate-github <id> [issue]` - Associate a GitHub issue with a backlog item; accepts a full issue URL or `owner/repo#number` shorthand, normalises to `owner/repo#number`, and fetches the issue title via the `gh` CLI to confirm it. Clears any Jira key on the item (one external tracker per item). Use `--clear` to remove the association
 - `assist backlog add-activity <id> <kind> <ref>` - Attach a git activity ref to a backlog item, where `kind` is `branch`, `commit`, or `pr`; `branch`/`commit` auto-fill their GitHub URL. Use `--title`, `--url`, `--state` to supply or override metadata. Re-adding the same kind and ref upserts rather than duplicating
 - `assist backlog move-repo <old-origin> [new-origin]` - Retag all items from one origin to another after a repo rename; the new origin defaults to the current repo's remote, both accept URL or `git@` forms, and a bare repo name works for the old origin when unambiguous. Prompts for confirmation (use `-y, --yes` to skip)
@@ -211,6 +211,8 @@ Backlog item ids are written and displayed in an `a`-prefixed form (e.g. item 55
 - `assist edit-hook` - PreToolUse hook that blocks `Edit`/`Write`/`MultiEdit` calls from adding, changing, or removing a `// assist-maintainability-override` marker, or from introducing a code comment (use `code-comment set`/`confirm` for the rare comment that belongs)
 - `assist code-comment set <file> <line> <text>` - Validate a single-line comment (max 50 chars; no block comments for `.ts`/`.js`) and issue a pin authorising its insertion; inserts `#` for `#`-comment files (`.yml`/`.yaml`, Dockerfile, `*.env`, `*.sh`) and `//` otherwise
 - `assist code-comment confirm <pin>` - Insert the pinned comment at its file/line and clear the pin state
+- `assist db-migration unlock` - Page a human to approve creating the next new database migration module: issues a pin via desktop notification and records the pending migration id
+- `assist db-migration confirm <pin>` - Confirm a pin from `db-migration unlock` to record a one-shot approval for that migration id, allowing the edit hook to let its `migrationNNNN*.ts` write through once
 - `assist update` - Update assist to the latest version and sync commands
 - `assist vscode init` - Add VS Code configuration files
 - `assist deploy init` - Initialize Netlify project and configure deployment

package/claude/commands/bug.md

@@ -69,6 +69,24 @@ 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.
 
+### Associate an external tracker
+
+If the user's original input (`$ARGUMENTS`) referenced an external tracker, associate it with the created item so downstream sessions have the context. Detect at most **one** tracker:
+
+- A **Jira** issue — a bare key (`PROJ-123`) or an Atlassian browse URL (`https://<site>.atlassian.net/browse/PROJ-123`):
+
+  ```
+  assist backlog associate-jira a<id> "<key-or-url>" 2>&1
+  ```
+
+- A **GitHub** issue — `owner/repo#number` shorthand or a `https://github.com/owner/repo/issues/N` URL:
+
+  ```
+  assist backlog associate-github a<id> "<issue-or-url>" 2>&1
+  ```
+
+Only one external tracker can be set per item (associating one clears the other), so run at most one of these. If the input referenced no tracker, skip this step. If the association command reports an error (malformed reference, issue not found), relay it to the user but do not treat it as fatal — the item was still created successfully.
+
 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 (a-prefixed, e.g. `a555`):

package/claude/commands/draft.md

@@ -105,6 +105,24 @@ Then add each phase:
 assist backlog add-phase a<id> "Phase name" --task "Task 1" --task "Task 2" --manual-check "optional check" 2>&1
 ```
 
+### Associate an external tracker
+
+If the user's original input (`$ARGUMENTS`) referenced an external tracker, associate it with the created item so downstream sessions have the context. Detect at most **one** tracker:
+
+- A **Jira** issue — a bare key (`PROJ-123`) or an Atlassian browse URL (`https://<site>.atlassian.net/browse/PROJ-123`):
+
+  ```
+  assist backlog associate-jira a<id> "<key-or-url>" 2>&1
+  ```
+
+- A **GitHub** issue — `owner/repo#number` shorthand or a `https://github.com/owner/repo/issues/N` URL:
+
+  ```
+  assist backlog associate-github a<id> "<issue-or-url>" 2>&1
+  ```
+
+Only one external tracker can be set per item (associating one clears the other), so run at most one of these. If the input referenced no tracker, skip this step. If the association command reports an error (malformed reference, issue not found), relay it to the user but do not treat it as fatal — the item was still created successfully.
+
 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 (a-prefixed, e.g. `a555`):

package/claude/commands/refine.md

@@ -25,6 +25,7 @@ Ask the user what they want to change or improve about this item. Listen for cha
 - **Type** (story / bug)
 - **Acceptance criteria**
 - **Plan phases** (add, modify, or remove phases and their tasks)
+- **External tracker** (a Jira key/URL or a GitHub issue reference to associate)
 - **General feedback** that should be captured as a comment
 
 Ask one focused question at a time. Wait for the user's response before continuing.
@@ -76,6 +77,15 @@ When adding or restructuring plan phases, follow the same rules as /draft:
 - **Every phase must pass `assist verify` on its own.** Verification includes knip, which fails on unused exports — so every export a phase adds must have a caller wired up in that same phase. No "phase 2 will use it" scaffolding.
 - 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 associate an external tracker** (Jira or GitHub — mutually exclusive, one per item; associating one clears the other):
+
+```
+assist backlog associate-jira <id> "<key-or-browse-url>" 2>&1
+assist backlog associate-github <id> "<owner/repo#number-or-issue-url>" 2>&1
+```
+
+`associate-jira` accepts a bare key (`PROJ-123`) or an Atlassian browse URL; `associate-github` accepts `owner/repo#number` or a `github.com` issue URL. To remove any association, add `--clear` with no reference. If the command reports an error (malformed reference, issue not found), relay it to the user — nothing is stored on failure.
+
 **To add a comment** (for context, decisions, or notes that don't fit in fields):
 
 ```