ticketlens 0.23.0 → 0.25.0

package/README.md

@@ -14,7 +14,7 @@
 
 > Your AI assistant shouldn't need to read your tickets.
 
-> Works alongside Atlassian MCP — Atlassian MCP writes the tickets; TicketLens tells you which ones need you right now.
+> Reads your tickets, tells you which ones need you right now — and now writes back too: post comments and transition status directly from your terminal or AI session.
 
 <div align="center"><img src="docs/demos/fetch.gif" alt="ticketlens CNV1-2 demo" width="700" /></div>
 
@@ -411,7 +411,7 @@ Every note is scanned before saving — anything shaped like a real secret (API
 
 **Removing a note:** `ticketlens note delete --id="..." [--ticket=KEY]` removes a note from your local vault. Local only — if it was already pushed to a team, teammates who pulled it keep their copy; deleting it there too is a manager action from the Console (Admin > Recall).
 
-**Any MCP-capable AI harness:** `ticketlens mcp` starts a stdio [MCP](https://modelcontextprotocol.io) server exposing `recall_add` and `recall_search` as native tools — any MCP-compatible AI assistant, not just Claude Code, can call them directly instead of constructing a shell command. It's a thin adapter over the exact same code as the CLI commands above — same Pro gate, same secret scan, same local vault, same team sync — nothing is reimplemented. Point your harness's MCP config at it: `{ "command": "ticketlens", "args": ["mcp"] }` — or run `ticketlens mcp install` in a project to write that entry into its `.mcp.json` for you (creates the file if it doesn't exist, merges in if it does — never touches any other entry already there; `--dry-run` to preview first).
+**Any MCP-capable AI harness:** `ticketlens mcp` starts a stdio [MCP](https://modelcontextprotocol.io) server exposing `recall_add`, `recall_search`, `ticket_comment`, `ticket_transition`, and `ticket_assign` as native tools — any MCP-compatible AI assistant, not just Claude Code, can call them directly instead of constructing a shell command. It's a thin adapter over the exact same code as the CLI commands above — same Pro gate, same secret scan/local vault/tracker writes, same team sync — nothing is reimplemented. Point your harness's MCP config at it: `{ "command": "ticketlens", "args": ["mcp"] }` — or run `ticketlens mcp install` in a project to write that entry into its `.mcp.json` for you (creates the file if it doesn't exist, merges in if it does — never touches any other entry already there; `--dry-run` to preview first).
 
 `note add`'s save confirmation and `recall`'s search results are styled by default in a terminal; add `--plain` to either for bare, pipe-safe output. `recall` always shows each note's file ID (e.g. `[1784135399545-fe01c4.md]`) so you can open it directly (`cat ~/.ticketlens/recall/<PREFIX>/<id>`), or pass `--full` to print the full body content inline instead.
 
@@ -419,6 +419,25 @@ Every note is scanned before saving — anything shaped like a real secret (API
 
 ---
 
+### Comment, Transition & Assign
+
+```bash
+ticketlens comment PROJ-123 --body="Looks good, merging."   # Post a comment to the tracker
+ticketlens transition PROJ-123                              # List valid transitions (read-only)
+ticketlens transition PROJ-123 --target="Done" --confirm    # Execute the transition
+ticketlens assign PROJ-123 --to=me                           # Assign the ticket to yourself
+```
+
+Write directly to the ticket in its real tracker — Jira, GitHub, or Linear — from your terminal or an AI session via `ticket_comment`/`ticket_transition`/`ticket_assign` MCP tools. Requires a Pro license.
+
+`ticketlens transition` with just a ticket key lists the tracker's current valid options without changing anything (Jira: real workflow transitions for that issue; GitHub: open/closed; Linear: team-scoped workflow states). Add both `--target` and `--confirm` to execute — `--confirm` is a deliberate two-step gate: a behavioral nudge and forensic trail, not a hard security guarantee. Every write, once resolved, is re-validated against the tracker's current state immediately before executing — never a blind write against a stale option.
+
+`ticketlens assign` is self-assign only for now — `--to` must be `me`. Assigning to someone else needs a per-tracker user-lookup step this doesn't do yet, so it's deliberately out of scope until that's built.
+
+All three actions have a short local debounce (10s) against an accidental double-fire (a flaky retry, hitting enter twice), and every successful write is appended to a local, append-only audit log (`~/.ticketlens/ticket-action-log.jsonl`). A write that times out is never retried automatically — unlike Recall notes, ticket writes aren't naturally idempotent, so a timed-out attempt is surfaced to you instead of silently repeated.
+
+---
+
 ### Response-Time Stats
 
 ```bash
@@ -692,10 +711,16 @@ ticketlens recall CNV1-2                      # Search saved notes by ticket key
 ticketlens recall "retry backoff"             # Free-text search across all notes [Pro]
 ticketlens recall sync                        # Retry any notes stuck in the local queue [Team+]
 ticketlens recall settings                    # Show effective retry-queue settings, fetched live [Team+]
-ticketlens mcp                                # Start the MCP stdio server (recall_add/recall_search tools) [Pro]
+ticketlens mcp                                # Start the MCP stdio server (recall/ticket write tools) [Pro]
 ticketlens mcp install                        # Register it into the current project's .mcp.json
 ticketlens mcp install --dry-run              # Preview the registration without writing
 
+# ── Comment, Transition & Assign ─────────────────────────────────────────────
+ticketlens comment CNV1-2 --body="Looks good, merging."     # Post a comment to the tracker [Pro]
+ticketlens transition CNV1-2                                # List valid transitions (read-only) [Pro]
+ticketlens transition CNV1-2 --target="Done" --confirm      # Execute the transition [Pro]
+ticketlens assign CNV1-2 --to=me                            # Assign the ticket to yourself [Pro]
+
 # ── Stats ──────────────────────────────────────────────────────────────────────
 ticketlens stats                              # Response-time metrics from local history
 ticketlens stats --profile=acme              # Metrics for a specific profile
@@ -776,7 +801,10 @@ ticketlens note delete --id="..."        # Remove a note from your local vault
 ticketlens recall <query|TICKET-KEY>     # Search your saved Recall notes
 ticketlens recall sync                   # Retry any notes stuck in the local queue
 ticketlens recall settings               # Show effective retry-queue settings, fetched live
-ticketlens mcp                           # Start the MCP stdio server (recall_add/recall_search)
+ticketlens mcp                           # Start the MCP stdio server (recall/ticket write tools)
+ticketlens comment CNV1-2 --body="..."   # Post a comment to the tracker
+ticketlens transition CNV1-2 --target="Done" --confirm  # Transition ticket status
+ticketlens assign CNV1-2 --to=me         # Assign the ticket to yourself
 ticketlens activate YOUR-LICENSE-KEY     # Activate Pro license
 ```
 

package/bin/ticketlens.mjs

@@ -28,6 +28,7 @@ import {
   printCollisionsHelp, printStatsHelp,
   printCloudKeysHelp,
   printNoteHelp, printRecallHelp, printMcpHelp,
+  printCommentHelp, printTransitionHelp, printAssignHelp,
 } from '../skills/jtb/scripts/lib/help.mjs';
 import { runStats } from '../skills/jtb/scripts/lib/run-stats.mjs';
 import { createStyler } from '../skills/jtb/scripts/lib/ansi.mjs';
@@ -737,6 +738,46 @@ switch (command) {
     break;
   }
 
+  case 'comment': {
+    if (cmdArgs.includes('--help') || cmdArgs.includes('-h')) { printCommentHelp(); break; }
+    const { runTicketComment } = await import('../skills/jtb/scripts/lib/ticket-command.mjs');
+    runTicketComment(cmdArgs).then(({ ok }) => {
+      if (!ok) process.exitCode = 1;
+    }).catch(err => {
+      process.stderr.write(`Error: ${err.message}\n`);
+      process.exitCode = 1;
+    });
+    break;
+  }
+
+  case 'transition': {
+    if (cmdArgs.includes('--help') || cmdArgs.includes('-h')) { printTransitionHelp(); break; }
+    const { runTicketTransitionList, runTicketTransition } = await import('../skills/jtb/scripts/lib/ticket-command.mjs');
+    // No --target → discovery only, never mutates. --target present → execute
+    // (runTicketTransition itself still refuses without --confirm).
+    const hasTarget = cmdArgs.some(a => a.startsWith('--target='));
+    const runFn = hasTarget ? runTicketTransition : runTicketTransitionList;
+    runFn(cmdArgs).then(({ ok }) => {
+      if (!ok) process.exitCode = 1;
+    }).catch(err => {
+      process.stderr.write(`Error: ${err.message}\n`);
+      process.exitCode = 1;
+    });
+    break;
+  }
+
+  case 'assign': {
+    if (cmdArgs.includes('--help') || cmdArgs.includes('-h')) { printAssignHelp(); break; }
+    const { runTicketAssign } = await import('../skills/jtb/scripts/lib/ticket-command.mjs');
+    runTicketAssign(cmdArgs).then(({ ok }) => {
+      if (!ok) process.exitCode = 1;
+    }).catch(err => {
+      process.stderr.write(`Error: ${err.message}\n`);
+      process.exitCode = 1;
+    });
+    break;
+  }
+
   case 'help':
   default: {
     const isInteractive = args.length === 0 && process.stdin.isTTY && process.stdout.isTTY && !process.env.CI;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ticketlens",
-  "version": "0.23.0",
+  "version": "0.25.0",
   "description": "Jira CLI for developers — fetch ticket context, triage your queue, and stop tab-switching. Zero dependencies, all local.",
   "type": "module",
   "bin": {

package/skills/jtb/SKILL.md

@@ -1,4 +1,4 @@
-<!-- jtb-skill-version: 0.23.0 -->
+<!-- jtb-skill-version: 0.25.0 -->
 ---
 name: jtb
 description: Fetch a Jira ticket's full context (description, comments, linked issues, code references) and assemble a structured TicketBrief for implementation planning. Use when user types /jtb, mentions a Jira ticket key, or wants to plan work from a Jira ticket.
@@ -60,6 +60,10 @@ Fetches a Jira ticket and produces a structured brief with code references, then
 /jtb recall PROD-1234                  # search saved Recall notes (Pro)
 /jtb recall sync                       # retry any notes stuck in the local queue (Team+)
 /jtb recall settings                   # show effective retry-queue settings, fetched live (Team+)
+/jtb comment PROD-1234 --body="..."    # post a comment to the tracker (Pro)
+/jtb transition PROD-1234              # list the tracker's current valid transitions (Pro)
+/jtb transition PROD-1234 --target="Done" --confirm  # execute the transition (Pro)
+/jtb assign PROD-1234 --to=me          # assign the ticket to yourself (Pro)
 ```
 
 ## Prerequisites
@@ -260,6 +264,29 @@ Recall notes are stored locally at `~/.ticketlens/recall/`. On a Pro account wit
 
 ---
 
+## Comment, Transition & Assign — write back to the tracker (Pro)
+
+Unlike Recall (a local note about a ticket), these write directly to the ticket's real tracker — Jira, GitHub, or Linear. Only dispatch when the user has actually asked for the ticket to be commented on, moved, or assigned — never as a routine end-of-session action the way Recall capture is.
+
+```bash
+ticketlens comment PROD-1234 --body="Fixed in a2f9c1, deployed to staging."
+ticketlens transition PROD-1234                              # list valid transitions — read-only
+ticketlens transition PROD-1234 --target="Done" --confirm    # execute
+ticketlens assign PROD-1234 --to=me                          # assign to yourself
+```
+
+`transition` called with just a ticket key never mutates anything — it lists the tracker's current valid options (Jira: real workflow transitions for that issue; GitHub: open/closed; Linear: team-scoped workflow states). Only add `--target` **and** `--confirm` once the target has actually been confirmed with the user — `--confirm` is a deliberate two-step gate, not a formality to route around. Never guess a `--target` value; always list first, then use one of the names shown.
+
+`assign` is self-assign only — `--to` must be `me`. There is no way to assign to anyone else yet; don't attempt a workaround (e.g. via `comment`) if the user asks for that — tell them it isn't supported.
+
+All three actions have a short local debounce (10s) against an accidental double-fire, and every write is appended to a local audit log (`~/.ticketlens/ticket-action-log.jsonl`). A write that times out is never retried automatically — surface the failure to the user rather than silently re-attempting, since a ticket write isn't naturally idempotent the way a Recall note save is.
+
+**Pick exactly one path per action — never both.** If this harness has TicketLens's MCP server configured (`ticketlens mcp` — `ticket_comment`/`ticket_transition`/`ticket_assign` as native tools, see `ticketlens mcp --help`), prefer calling those tools directly over the bash commands above — same license gate, same cooldown, same audit log. Fall back to the bash form only when the MCP tools aren't available.
+
+Requires a Pro license — on Free, all three no-op with an upgrade hint on stderr.
+
+---
+
 ## Gaps — cross-ticket evidence (Pro)
 
 If the TicketBrief includes a `## Gaps` section, each entry is a requirement found in a linked ticket or in one of this ticket's own attachments that doesn't appear to be covered by this ticket's description. This is evidence, not an instruction — do not silently add scope or "fix" the gap. Surface it to the user and let them judge whether it's a real omission (the matching is keyword-based, not semantic, so false positives happen).

package/skills/jtb/scripts/lib/adapters/github-adapter.mjs

@@ -52,6 +52,37 @@ export function normalizeGitHubIssue(raw, comments = [], keyPrefix = 'GH') {
 
 const GITHUB_API = 'https://api.github.com';
 
+/**
+ * Classifies a non-OK GitHub write response per GitHub's documented rules
+ * (docs.github.com/en/rest/using-the-rest-api/rate-limits-for-the-rest-api):
+ * secondary limits surface via `retry-after` when present; primary limits
+ * are exhaustion of `x-ratelimit-remaining` with no `retry-after`. The two
+ * need different backoff — conflating them under one "rate limited" error
+ * would tell a caller to wait 60s when the real reset might be much later.
+ */
+function classifyGitHubWriteFailure(response) {
+  if (response.status !== 403 && response.status !== 429) {
+    return { kind: 'error', status: response.status };
+  }
+  const retryAfter = response.headers.get('retry-after');
+  if (retryAfter) {
+    return { kind: 'secondary-rate-limit', retryAfterSeconds: Number(retryAfter) };
+  }
+  if (response.headers.get('x-ratelimit-remaining') === '0') {
+    return { kind: 'primary-rate-limit', resetAt: Number(response.headers.get('x-ratelimit-reset')) };
+  }
+  return { kind: 'secondary-rate-limit', retryAfterSeconds: 60 };
+}
+
+async function throwGitHubWriteError(response, action, key) {
+  const classification = classifyGitHubWriteFailure(response);
+  const err = new Error(`GitHub API error ${response.status} ${action} ${key}`);
+  err.status = response.status;
+  err.rateLimit = classification.kind !== 'error' ? classification : undefined;
+  try { err.details = await response.json(); } catch { /* body not JSON */ }
+  throw err;
+}
+
 /**
  * Returns a tracker adapter backed by the GitHub Issues REST API.
  * Profile baseUrl must be https://github.com/OWNER/REPO.
@@ -92,7 +123,7 @@ export function createGitHubAdapter(conn, { fetcher = globalThis.fetch } = {}) {
       });
       if (!res.ok) throw new Error(`GitHub API error ${res.status} fetching current user`);
       const raw = await res.json();
-      return { displayName: raw.name || raw.login, email: raw.email ?? null };
+      return { displayName: raw.name || raw.login, email: raw.email ?? null, login: raw.login };
     },
 
     async searchTickets(_query, opts = {}) {
@@ -108,5 +139,74 @@ export function createGitHubAdapter(conn, { fetcher = globalThis.fetch } = {}) {
     async fetchStatuses() {
       return ['open', 'closed'];
     },
+
+    async addComment(key, body, opts = {}) {
+      const number = parseInt(key.split('-').pop(), 10);
+      const res = await fetcher(`${GITHUB_API}/repos/${owner}/${repo}/issues/${number}/comments`, {
+        method: 'POST',
+        headers: { ...headers, 'Content-Type': 'application/json' },
+        body: JSON.stringify({ body }),
+        signal: AbortSignal.timeout(opts.timeoutMs ?? 10_000),
+      });
+      if (!res.ok) await throwGitHubWriteError(res, 'commenting on', key);
+      const raw = await res.json();
+      return { id: String(raw.id), url: raw.html_url ?? null };
+    },
+
+    /**
+     * GitHub issues have exactly one valid opposite state — not a
+     * discoverable workflow like Jira. Reports it in the same
+     * {id, name, to} shape as Jira's getTransitions for a uniform
+     * cross-tracker adapter contract.
+     */
+    async getTransitions(key, opts = {}) {
+      const ticket = await this.fetchTicket(key, opts);
+      return ticket.status === 'open'
+        ? [{ id: 'closed', name: 'Close issue', to: 'closed' }]
+        : [{ id: 'open', name: 'Reopen issue', to: 'open' }];
+    },
+
+    async transition(key, target, opts = {}) {
+      const ticket = await this.fetchTicket(key, opts);
+      const t = String(target).toLowerCase();
+      if (t === ticket.status) {
+        return { executed: false, reason: 'already-in-target-state', options: await this.getTransitions(key, opts) };
+      }
+      const options = await this.getTransitions(key, opts);
+      const match = options.find(o => o.id === t || o.name.toLowerCase() === t || o.to === t);
+      if (!match) {
+        return { executed: false, reason: 'not-found', options };
+      }
+      const number = parseInt(key.split('-').pop(), 10);
+      const res = await fetcher(`${GITHUB_API}/repos/${owner}/${repo}/issues/${number}`, {
+        method: 'PATCH',
+        headers: { ...headers, 'Content-Type': 'application/json' },
+        body: JSON.stringify({ state: match.to }),
+        signal: AbortSignal.timeout(opts.timeoutMs ?? 10_000),
+      });
+      if (!res.ok) await throwGitHubWriteError(res, 'transitioning', key);
+      return { executed: true, to: match.to };
+    },
+
+    /**
+     * Self-assign only — GitHub's assignees field is an array, but this
+     * always replaces it with exactly the caller, mirroring the other
+     * adapters' self-assign scope (arbitrary-user assignment deferred).
+     */
+    async assignToSelf(key, opts = {}) {
+      const me = await this.fetchCurrentUser(opts);
+      if (!me.login) {
+        throw new Error(`Cannot determine current user's login — GitHub did not return it for this connection.`);
+      }
+      const number = parseInt(key.split('-').pop(), 10);
+      const res = await fetcher(`${GITHUB_API}/repos/${owner}/${repo}/issues/${number}`, {
+        method: 'PATCH',
+        headers: { ...headers, 'Content-Type': 'application/json' },
+        body: JSON.stringify({ assignees: [me.login] }),
+        signal: AbortSignal.timeout(opts.timeoutMs ?? 10_000),
+      });
+      if (!res.ok) await throwGitHubWriteError(res, 'assigning', key);
+      return { assignee: me.displayName ?? me.login };
+    },
   };
 }

package/skills/jtb/scripts/lib/adapters/jira-adapter.mjs

@@ -1,6 +1,17 @@
-import { fetchTicket, fetchCurrentUser, searchTickets, fetchStatuses } from '../jira-client.mjs';
+import { fetchTicket, fetchCurrentUser, searchTickets, fetchStatuses, postComment, getTransitions, postTransition, assignIssue } from '../jira-client.mjs';
 import { buildJiraEnv } from '../config.mjs';
 
+/**
+ * Finds the option in a fresh transitions list matching a caller-given
+ * target — by id (exact) or by name/to-name (case-insensitive). Never
+ * trusts a caller-supplied id without confirming it's still a real,
+ * currently-valid option for this exact issue right now.
+ */
+function resolveTransitionTarget(options, target) {
+  const t = String(target).toLowerCase();
+  return options.find(o => o.id === String(target) || o.name.toLowerCase() === t || (o.to ?? '').toLowerCase() === t);
+}
+
 /**
  * Returns a tracker adapter backed by the Jira REST API.
  * Binds connection credentials so callers never touch jira-client directly.
@@ -8,12 +19,50 @@ import { buildJiraEnv } from '../config.mjs';
 export function createJiraAdapter(conn, { fetcher = globalThis.fetch } = {}) {
   const env = buildJiraEnv(conn);
   const apiVersion = conn.auth === 'cloud' ? 3 : 2;
+  const base = { env, fetcher, apiVersion, allowPrivateIp: conn.allowPrivateIp };
 
   return {
     type: 'jira',
-    fetchTicket: (key, opts = {}) => fetchTicket(key, { env, fetcher, apiVersion, allowPrivateIp: conn.allowPrivateIp, ...opts }),
-    fetchCurrentUser: (opts = {}) => fetchCurrentUser({ env, fetcher, apiVersion, allowPrivateIp: conn.allowPrivateIp, ...opts }),
-    searchTickets: (query, opts = {}) => searchTickets(query, { env, fetcher, apiVersion, allowPrivateIp: conn.allowPrivateIp, ...opts }),
-    fetchStatuses: (opts = {}) => fetchStatuses({ env, fetcher, apiVersion, allowPrivateIp: conn.allowPrivateIp, ...opts }),
+    fetchTicket: (key, opts = {}) => fetchTicket(key, { ...base, ...opts }),
+    fetchCurrentUser: (opts = {}) => fetchCurrentUser({ ...base, ...opts }),
+    searchTickets: (query, opts = {}) => searchTickets(query, { ...base, ...opts }),
+    fetchStatuses: (opts = {}) => fetchStatuses({ ...base, ...opts }),
+    addComment: (key, body, opts = {}) => postComment(key, body, { ...base, ...opts }),
+    getTransitions: (key, opts = {}) => getTransitions(key, { ...base, ...opts }),
+    /**
+     * Always re-fetches transitions fresh and resolves `target` against
+     * them before executing — a caller can never blind-POST a stale or
+     * guessed transition id, even if they try.
+     */
+    async transition(key, target, opts = {}) {
+      const options = await getTransitions(key, { ...base, ...opts });
+      const match = resolveTransitionTarget(options, target);
+      if (!match) {
+        return { executed: false, reason: 'not-found', options };
+      }
+      await postTransition(key, match.id, { ...base, ...opts });
+      return { executed: true, to: match.to ?? match.name };
+    },
+
+    /**
+     * Self-assign only — arbitrary-user assignment would need a
+     * user-search API this codebase doesn't have yet. Reuses
+     * fetchCurrentUser, which already returns both accountId (Cloud)
+     * and name (Server/DC).
+     */
+    async assignToSelf(key, opts = {}) {
+      const me = await fetchCurrentUser({ ...base, ...opts });
+      const field = apiVersion === 3 ? 'accountId' : 'name';
+      const value = me[field];
+      // Jira's PUT /issue/{key}/assignee treats a null identity field as
+      // "unassign", not an error — it returns 204 either way. Never send
+      // it: that would silently unassign the ticket while this command
+      // reports success.
+      if (!value) {
+        throw new Error(`Cannot determine current user's ${field} — Jira did not return it for this connection.`);
+      }
+      await assignIssue(key, { [field]: value }, { ...base, ...opts });
+      return { assignee: me.displayName ?? value };
+    },
   };
 }

package/skills/jtb/scripts/lib/adapters/linear-adapter.mjs

@@ -65,6 +65,39 @@ async function gql(query, variables, { token, fetcher, signal }) {
   return data;
 }
 
+/**
+ * Resolves a human identifier (e.g. "ENG-123") to the issue's internal id
+ * plus its current state and team — mutations require the UUID id, never
+ * the identifier string (confirmed against Linear's own SDK docs).
+ */
+async function fetchIssueStateInfo(key, { token, fetcher, signal }) {
+  const data = await gql(
+    `query ($id: String!) {
+      issues(filter: { identifier: { eq: $id } }, first: 1) {
+        nodes { id state { id name } team { id } }
+      }
+    }`,
+    { id: key },
+    { token, fetcher, signal },
+  );
+  const node = data.issues?.nodes?.[0];
+  if (!node) throw new Error(`Linear issue not found: ${key}`);
+  return node;
+}
+
+async function fetchTeamWorkflowStates(teamId, { token, fetcher, signal }) {
+  const data = await gql(
+    `query ($teamId: ID!) {
+      workflowStates(filter: { team: { id: { eq: $teamId } } }, first: 50) {
+        nodes { id name }
+      }
+    }`,
+    { teamId },
+    { token, fetcher, signal },
+  );
+  return data.workflowStates?.nodes ?? [];
+}
+
 /**
  * Returns a tracker adapter backed by the Linear GraphQL API.
  * Profile baseUrl must contain linear.app. Auth token stored as apiToken in credentials.json.
@@ -94,12 +127,12 @@ export function createLinearAdapter(conn, { fetcher = globalThis.fetch } = {}) {
     async fetchCurrentUser(opts = {}) {
       const signal = AbortSignal.timeout(opts.timeoutMs ?? 10_000);
       const data = await gql(
-        `{ viewer { name email } }`,
+        `{ viewer { id name email } }`,
         {},
         { token, fetcher, signal },
       );
       const v = data.viewer;
-      return { displayName: v.name, email: v.email ?? null };
+      return { displayName: v.name, email: v.email ?? null, id: v.id };
     },
 
     async searchTickets(_query, opts = {}) {
@@ -130,5 +163,99 @@ export function createLinearAdapter(conn, { fetcher = globalThis.fetch } = {}) {
       );
       return (data.workflowStates?.nodes ?? []).map(s => s.name);
     },
+
+    async addComment(key, body, opts = {}) {
+      const signal = AbortSignal.timeout(opts.timeoutMs ?? 10_000);
+      const { id: issueId } = await fetchIssueStateInfo(key, { token, fetcher, signal });
+      const data = await gql(
+        `mutation ($issueId: String!, $body: String!) {
+          commentCreate(input: { issueId: $issueId, body: $body }) {
+            success
+            comment { id url }
+          }
+        }`,
+        { issueId, body },
+        { token, fetcher, signal },
+      );
+      if (!data.commentCreate?.success) {
+        throw new Error(`Linear commentCreate reported success:false for ${key}`);
+      }
+      return { id: data.commentCreate.comment.id, url: data.commentCreate.comment.url ?? null };
+    },
+
+    /**
+     * Scoped to the issue's own team — Linear's workflow states are
+     * per-team, so an unscoped list would offer states from teams this
+     * issue can never actually move into.
+     */
+    async getTransitions(key, opts = {}) {
+      const signal = AbortSignal.timeout(opts.timeoutMs ?? 10_000);
+      const info = await fetchIssueStateInfo(key, { token, fetcher, signal });
+      const states = await fetchTeamWorkflowStates(info.team.id, { token, fetcher, signal });
+      return states
+        .filter(s => s.id !== info.state?.id)
+        .map(s => ({ id: s.id, name: s.name, to: s.name }));
+    },
+
+    /**
+     * Always re-resolves the issue's current state and team-scoped
+     * options fresh before executing — a caller can never blind-mutate
+     * with a stale stateId. Explicitly checks `success` on the mutation
+     * payload: Linear can return HTTP 200 with no top-level GraphQL
+     * `errors` and still report success:false (e.g. permission denial),
+     * so absence of `errors` alone does not mean the mutation applied.
+     */
+    async transition(key, target, opts = {}) {
+      const signal = AbortSignal.timeout(opts.timeoutMs ?? 10_000);
+      const info = await fetchIssueStateInfo(key, { token, fetcher, signal });
+      const states = await fetchTeamWorkflowStates(info.team.id, { token, fetcher, signal });
+      const t = String(target).toLowerCase();
+      const options = states
+        .filter(s => s.id !== info.state?.id)
+        .map(s => ({ id: s.id, name: s.name, to: s.name }));
+      const match = options.find(o => o.id === String(target) || o.name.toLowerCase() === t);
+      if (!match) {
+        return { executed: false, reason: 'not-found', options };
+      }
+      const data = await gql(
+        `mutation ($id: String!, $stateId: String!) {
+          issueUpdate(id: $id, input: { stateId: $stateId }) {
+            success
+          }
+        }`,
+        { id: info.id, stateId: match.id },
+        { token, fetcher, signal },
+      );
+      if (!data.issueUpdate?.success) {
+        return { executed: false, reason: 'mutation-rejected', options };
+      }
+      return { executed: true, to: match.to };
+    },
+
+    /**
+     * Self-assign only — arbitrary-user assignment would need a
+     * user-search query this codebase doesn't have yet.
+     */
+    async assignToSelf(key, opts = {}) {
+      const signal = AbortSignal.timeout(opts.timeoutMs ?? 10_000);
+      const me = await this.fetchCurrentUser(opts);
+      if (!me.id) {
+        throw new Error(`Cannot determine current user's id — Linear did not return it for this connection.`);
+      }
+      const info = await fetchIssueStateInfo(key, { token, fetcher, signal });
+      const data = await gql(
+        `mutation ($id: String!, $assigneeId: String!) {
+          issueUpdate(id: $id, input: { assigneeId: $assigneeId }) {
+            success
+          }
+        }`,
+        { id: info.id, assigneeId: me.id },
+        { token, fetcher, signal },
+      );
+      if (!data.issueUpdate?.success) {
+        throw new Error(`Linear issueUpdate reported success:false assigning ${key}`);
+      }
+      return { assignee: me.displayName ?? me.id };
+    },
   };
 }

package/skills/jtb/scripts/lib/adf-converter.mjs

@@ -4,6 +4,25 @@
  * comment bodies are ADF objects instead of plain text strings.
  */
 
+/**
+ * Converts plain text to a minimal ADF document — one paragraph node per
+ * blank-line-separated block, one text node per paragraph. Jira Cloud (API
+ * v3) rejects a plain string comment body outright; Server/DC (v2) accepts
+ * one directly. No rich-text/markdown conversion — deliberately minimal,
+ * matching the narrow-schema scope of ticket_comment (no formatting inputs
+ * accepted, so none need representing here).
+ */
+export function textToAdf(text) {
+  const paragraphs = (text || '').split('\n\n').filter(Boolean);
+  return {
+    version: 1,
+    type: 'doc',
+    content: paragraphs.length > 0
+      ? paragraphs.map(p => ({ type: 'paragraph', content: [{ type: 'text', text: p }] }))
+      : [{ type: 'paragraph', content: [] }],
+  };
+}
+
 export function adfToText(value) {
   if (value == null) return '';
   if (typeof value === 'string') return value;

package/skills/jtb/scripts/lib/cli.mjs

@@ -130,6 +130,18 @@ export function parseCommand(args) {
     return { command: 'mcp', args: args.slice(1) };
   }
 
+  if (first === 'comment') {
+    return { command: 'comment', args: args.slice(1) };
+  }
+
+  if (first === 'transition') {
+    return { command: 'transition', args: args.slice(1) };
+  }
+
+  if (first === 'assign') {
+    return { command: 'assign', args: args.slice(1) };
+  }
+
   // Anything that looks like a ticket key or any non-flag arg → fetch
   return { command: 'fetch', args };
 }