ticketlens 0.23.0 → 0.24.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`, and `ticket_transition` 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,22 @@ Every note is scanned before saving — anything shaped like a real secret (API
 
 ---
 
+### Comment & Transition
+
+```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
+```
+
+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` 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.
+
+Both 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 comments/transitions aren't naturally idempotent, so a timed-out attempt is surfaced to you instead of silently repeated.
+
+---
+
 ### Response-Time Stats
 
 ```bash
@@ -692,10 +708,15 @@ 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 ─────────────────────────────────────────────────────
+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]
+
 # ── Stats ──────────────────────────────────────────────────────────────────────
 ticketlens stats                              # Response-time metrics from local history
 ticketlens stats --profile=acme              # Metrics for a specific profile
@@ -776,7 +797,9 @@ 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 activate YOUR-LICENSE-KEY     # Activate Pro license
 ```
 

package/bin/ticketlens.mjs

@@ -28,6 +28,7 @@ import {
   printCollisionsHelp, printStatsHelp,
   printCloudKeysHelp,
   printNoteHelp, printRecallHelp, printMcpHelp,
+  printCommentHelp, printTransitionHelp,
 } 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,34 @@ 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 '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.24.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.24.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,9 @@ 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)
 ```
 
 ## Prerequisites
@@ -260,6 +263,26 @@ Recall notes are stored locally at `~/.ticketlens/recall/`. On a Pro account wit
 
 ---
 
+## Comment & Transition — 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 or moved — 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
+```
+
+`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.
+
+Both 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` 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, both 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.
@@ -108,5 +139,53 @@ 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 };
+    },
   };
 }

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 } 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,29 @@ 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 };
+    },
   };
 }

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.
@@ -130,5 +163,73 @@ 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 };
+    },
   };
 }

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,14 @@ 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) };
+  }
+
   // Anything that looks like a ticket key or any non-flag arg → fetch
   return { command: 'fetch', args };
 }

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

@@ -54,6 +54,8 @@ export function printHelp({ stream = process.stdout } = {}) {
     `    ${s.brand('ticketlens')} recall sync                 Retry any notes stuck in the local queue  ${s.dim('[Team+]')}`,
     `    ${s.brand('ticketlens')} recall settings             Show effective retry-queue settings, fetched live  ${s.dim('[Team+]')}`,
     `    ${s.brand('ticketlens')} mcp                         Start the MCP stdio server for Recall  ${s.dim('[Pro]')}`,
+    `    ${s.brand('ticketlens')} comment ${s.dim('<TICKET-KEY> --body=...')}  Post a comment to the tracker  ${s.dim('[Pro]')}`,
+    `    ${s.brand('ticketlens')} transition ${s.dim('<TICKET-KEY> [--target=... --confirm]')}  Move ticket status  ${s.dim('[Pro]')}`,
     '',
     `    ${s.brand('ticketlens')} delete ${s.dim('<PROFILE-NAME>')}       Remove a profile`,
     `    ${s.brand('ticketlens')} activate ${s.dim('<KEY>')}              Activate a license key`,
@@ -592,11 +594,13 @@ export function printMcpHelp({ stream = process.stdout } = {}) {
     '',
     `  ${s.bold(s.brand('ticketlens'))} ${s.bold('mcp')}  ${s.dim('[Pro]')}`,
     '',
-    `  Start an MCP (Model Context Protocol) stdio server exposing Recall as`,
-    `  native tools — ${s.cyan('recall_add')} and ${s.cyan('recall_search')} — for any MCP-compatible AI`,
-    `  harness, not just Claude Code. Thin adapter over the same code as`,
-    `  ${s.cyan('note add')}/${s.cyan('recall')} above: same Pro gate, same secret scan, same local`,
-    `  vault, same team sync. Long-running — exits when the client closes stdin.`,
+    `  Start an MCP (Model Context Protocol) stdio server exposing Recall and`,
+    `  ticket writes as native tools — ${s.cyan('recall_add')}, ${s.cyan('recall_search')}, ${s.cyan('ticket_comment')},`,
+    `  ${s.cyan('ticket_transition')} — for any MCP-compatible AI harness, not just Claude Code.`,
+    `  Thin adapter over the same code as ${s.cyan('note add')}/${s.cyan('recall')}/${s.cyan('comment')}/${s.cyan('transition')}`,
+    `  above: same Pro gate, same local vault/tracker writes, same team sync.`,
+    `  ${s.cyan('ticket_transition')} is destructive when called with \`target\`+\`confirm: true\`.`,
+    `  Long-running — exits when the client closes stdin.`,
     '',
     `  ${s.bold('OPTIONS')}`,
     '',
@@ -623,6 +627,55 @@ export function printMcpHelp({ stream = process.stdout } = {}) {
   stream.write(lines.join('\n') + '\n');
 }
 
+export function printCommentHelp({ stream = process.stdout } = {}) {
+  const s = createStyler({ isTTY: stream.isTTY });
+  const lines = [
+    '',
+    `  ${s.bold(s.brand('ticketlens'))} ${s.bold('comment')} ${s.dim('TICKET-KEY --body="..."')}  ${s.dim('[Pro]')}`,
+    '',
+    `  Post a comment directly to the ticket in its tracker (Jira/GitHub/Linear). ${s.dim('[Pro]')}`,
+    `  Writes to the real tracker — this is not a local Recall note.`,
+    '',
+    `  ${s.bold('OPTIONS')}`,
+    '',
+    `    ${s.brand('--body')}=${s.dim('TEXT')}    Comment body ${s.dim('(required)')}`,
+    `    ${s.brand('--profile')}=${s.dim('NAME')} Connection profile to use ${s.dim('(optional)')}`,
+    `    ${s.brand('-h')}, ${s.brand('--help')}   Show this help`,
+    '',
+    `  ${s.bold('EXAMPLES')}`,
+    '',
+    `    ${s.dim('$')} ticketlens comment PROD-123 --body="Looks good, merging."`,
+    '',
+  ];
+  stream.write(lines.join('\n') + '\n');
+}
+
+export function printTransitionHelp({ stream = process.stdout } = {}) {
+  const s = createStyler({ isTTY: stream.isTTY });
+  const lines = [
+    '',
+    `  ${s.bold(s.brand('ticketlens'))} ${s.bold('transition')} ${s.dim('TICKET-KEY [--target="..." --confirm]')}  ${s.dim('[Pro]')}`,
+    '',
+    `  Move a ticket to a new status in its tracker (Jira/GitHub/Linear). ${s.dim('[Pro]')}`,
+    `  Called with just a ticket key, lists the tracker's current valid options`,
+    `  without changing anything. Add ${s.brand('--target')} and ${s.brand('--confirm')} together to execute.`,
+    '',
+    `  ${s.bold('OPTIONS')}`,
+    '',
+    `    ${s.brand('--target')}=${s.dim('NAME')}  Target status/transition name ${s.dim('(from the list, case-insensitive)')}`,
+    `    ${s.brand('--confirm')}     Required alongside --target to actually execute`,
+    `    ${s.brand('--profile')}=${s.dim('NAME')} Connection profile to use ${s.dim('(optional)')}`,
+    `    ${s.brand('-h')}, ${s.brand('--help')}   Show this help`,
+    '',
+    `  ${s.bold('EXAMPLES')}`,
+    '',
+    `    ${s.dim('$')} ticketlens transition PROD-123`,
+    `    ${s.dim('$')} ticketlens transition PROD-123 --target="Done" --confirm`,
+    '',
+  ];
+  stream.write(lines.join('\n') + '\n');
+}
+
 export function printSwitchHelp({ stream = process.stdout } = {}) {
   const s = createStyler({ isTTY: stream.isTTY });
   const lines = [

package/skills/jtb/scripts/lib/jira-client.mjs

@@ -4,7 +4,7 @@
  * Supports v2 (Server/DC) and v3 (Cloud) API versions.
  */
 
-import { adfToText } from './adf-converter.mjs';
+import { adfToText, textToAdf } from './adf-converter.mjs';
 import { lookup as dnsLookup } from 'node:dns/promises';
 
 function toText(value) {
@@ -408,6 +408,92 @@ export async function fetchRemoteLinks(ticketKey, opts = {}) {
     .map(link => ({ url: link.object.url, title: link.object.title ?? null }));
 }
 
+/**
+ * Adds a comment to an issue. Cloud (v3) rejects a plain string body
+ * outright and requires ADF; Server/DC (v2) accepts plain text directly —
+ * same apiVersion branch point every other write/read here already uses.
+ */
+export async function postComment(ticketKey, body, opts = {}) {
+  const { env = process.env, fetcher = globalThis.fetch, lookup = defaultLookupFor(fetcher), apiVersion = 2, timeoutMs = 10_000, allowPrivateIp = false } = opts;
+  validateBaseUrl(env.JIRA_BASE_URL, allowPrivateIp);
+  const baseUrl = env.JIRA_BASE_URL.replace(/\/$/, '');
+  const url = `${baseUrl}/rest/api/${apiVersion}/issue/${encodeURIComponent(ticketKey)}/comment`;
+
+  const payload = { body: apiVersion === 3 ? textToAdf(body) : body };
+  const fetchOpts = {
+    method: 'POST',
+    headers: { ...buildAuthHeader(env), 'Content-Type': 'application/json' },
+    body: JSON.stringify(payload),
+  };
+  if (timeoutMs) fetchOpts.signal = AbortSignal.timeout(timeoutMs);
+
+  const response = await guardedFetch(url, fetchOpts, { fetcher, lookup, allowPrivateIp });
+  if (!response.ok) {
+    const err = new Error(`Jira API error ${response.status} commenting on ${ticketKey}`);
+    err.status = response.status;
+    throw err;
+  }
+  const raw = await response.json();
+  return { id: raw.id, url: raw.self ?? null };
+}
+
+/**
+ * Discovers the transitions actually available for this specific issue
+ * right now (workflow-dependent, varies per project/status) — never
+ * hardcode transition names or ids, they aren't stable across projects.
+ */
+export async function getTransitions(ticketKey, opts = {}) {
+  const { env = process.env, fetcher = globalThis.fetch, lookup = defaultLookupFor(fetcher), apiVersion = 2, timeoutMs = 10_000, allowPrivateIp = false } = opts;
+  validateBaseUrl(env.JIRA_BASE_URL, allowPrivateIp);
+  const baseUrl = env.JIRA_BASE_URL.replace(/\/$/, '');
+  const url = `${baseUrl}/rest/api/${apiVersion}/issue/${encodeURIComponent(ticketKey)}/transitions`;
+
+  const fetchOpts = { headers: { ...buildAuthHeader(env), 'Content-Type': 'application/json' } };
+  if (timeoutMs) fetchOpts.signal = AbortSignal.timeout(timeoutMs);
+
+  const response = await guardedFetch(url, fetchOpts, { fetcher, lookup, allowPrivateIp });
+  if (!response.ok) {
+    const err = new Error(`Jira API error ${response.status} fetching transitions for ${ticketKey}`);
+    err.status = response.status;
+    throw err;
+  }
+  const raw = await response.json();
+  return (raw.transitions ?? []).map(t => ({ id: t.id, name: t.name, to: t.to?.name ?? null }));
+}
+
+/**
+ * Executes a transition by id. Callers must resolve the id via
+ * getTransitions() immediately before calling this — never pass a
+ * remembered/stale id, since transitions are workflow- and
+ * time-of-status-dependent (see ticket-command.mjs's re-validation).
+ * A transition requiring a mandatory screen field the caller didn't
+ * supply returns Jira's own 400 with the field list — surfaced as-is,
+ * never silently swallowed or auto-filled.
+ */
+export async function postTransition(ticketKey, transitionId, opts = {}) {
+  const { env = process.env, fetcher = globalThis.fetch, lookup = defaultLookupFor(fetcher), apiVersion = 2, timeoutMs = 10_000, allowPrivateIp = false } = opts;
+  validateBaseUrl(env.JIRA_BASE_URL, allowPrivateIp);
+  const baseUrl = env.JIRA_BASE_URL.replace(/\/$/, '');
+  const url = `${baseUrl}/rest/api/${apiVersion}/issue/${encodeURIComponent(ticketKey)}/transitions`;
+
+  const fetchOpts = {
+    method: 'POST',
+    headers: { ...buildAuthHeader(env), 'Content-Type': 'application/json' },
+    body: JSON.stringify({ transition: { id: transitionId } }),
+  };
+  if (timeoutMs) fetchOpts.signal = AbortSignal.timeout(timeoutMs);
+
+  const response = await guardedFetch(url, fetchOpts, { fetcher, lookup, allowPrivateIp });
+  if (!response.ok) {
+    let details;
+    try { details = await response.json(); } catch { /* body not JSON — fall through with no details */ }
+    const err = new Error(`Jira API error ${response.status} transitioning ${ticketKey}`);
+    err.status = response.status;
+    err.details = details;
+    throw err;
+  }
+}
+
 export async function fetchTicket(ticketKey, opts = {}) {
   const { env = process.env, fetcher = globalThis.fetch, lookup = defaultLookupFor(fetcher), depth = 1, apiVersion = 2, timeoutMs = 10_000, expandChangelog = false, allowPrivateIp = false, _visited = new Set(), _currentDepth = 0 } = opts;
   validateBaseUrl(env.JIRA_BASE_URL, allowPrivateIp);

package/skills/jtb/scripts/lib/mcp-server.mjs

@@ -3,12 +3,15 @@
  *
  * A pure transport adapter: parses JSON-RPC 2.0 off stdin, translates
  * `tools/call` arguments into the exact args/dependency shape `runNoteAdd`/
- * `runRecall` already accept, and captures their human-readable `stream`
- * output into the JSON-RPC response instead of a real stream. Zero new
- * validation, licensing, or vault logic — both tools funnel through the
- * same functions the CLI's `note add`/`recall` commands already use, so
- * every existing gate (license, secret scan, structural check, retry
- * queue) applies identically here.
+ * `runRecall`/`runTicketComment`/`runTicketTransitionList`/
+ * `runTicketTransition` already accept, and captures their human-readable
+ * `stream` output into the JSON-RPC response instead of a real stream. Zero
+ * new validation, licensing, or vault logic — every tool funnels through
+ * the same functions the CLI's `note add`/`recall`/`comment`/`transition`
+ * commands already use, so every existing gate (license, secret scan,
+ * structural check, retry queue, cooldown, audit log) applies identically
+ * here. Ticket-writing tools must never import an adapter directly — doing
+ * so would fully bypass the Pro+ gate that lives in ticket-command.mjs.
  *
  * Per the MCP stdio transport spec, the server MUST NOT write anything to
  * stdout that isn't a valid MCP message — every wrapped function's output
@@ -20,6 +23,7 @@ import readline from 'node:readline';
 import { DEFAULT_CONFIG_DIR, getVersion } from './config.mjs';
 import { runNoteAdd } from './note-command.mjs';
 import { runRecall } from './recall-command.mjs';
+import { runTicketComment, runTicketTransitionList, runTicketTransition } from './ticket-command.mjs';
 
 const PROTOCOL_VERSION = '2025-11-25';
 
@@ -49,6 +53,31 @@ const TOOLS = [
       required: ['query'],
     },
   },
+  {
+    name: 'ticket_comment',
+    description: 'Post a comment to a ticket in its tracker (Jira/GitHub/Linear). Destructive — writes directly to the live tracker, not a local Recall note. Requires a TicketLens Pro license.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        ticket: { type: 'string', description: 'Ticket key, e.g. PROJ-123.' },
+        body: { type: 'string', description: 'Comment body.' },
+      },
+      required: ['ticket', 'body'],
+    },
+  },
+  {
+    name: 'ticket_transition',
+    description: 'List or execute a ticket status transition in its tracker (Jira/GitHub/Linear). Called with only `ticket`, lists the tracker\'s current valid options without changing anything. Destructive when `target` and `confirm: true` are both given — requires confirmation and writes directly to the live tracker. Requires a TicketLens Pro license.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        ticket: { type: 'string', description: 'Ticket key, e.g. PROJ-123.' },
+        target: { type: 'string', description: 'Target status/transition name. Omit to just list the tracker\'s current valid options.' },
+        confirm: { type: 'boolean', description: 'Must be true, alongside `target`, to actually execute the transition — a nudge and audit trail, not just a formality.' },
+      },
+      required: ['ticket'],
+    },
+  },
 ];
 
 function jsonRpcResult(id, result) {
@@ -112,14 +141,59 @@ async function callRecallSearch(args, { configDir, runRecallFn }) {
   return ok ? { content } : { isError: true, content };
 }
 
+/**
+ * `ticket`/`body` become single opaque cmdArgs elements (`--body=${body}`),
+ * same reasoning as buildNoteAddArgs above — a body containing literal
+ * `--confirm` or `--target=` text stays inert since parseFlag only matches
+ * a whole array element via startsWith, never scans inside one.
+ */
+async function callTicketComment(args, { configDir, runTicketCommentFn }) {
+  if (!args.ticket) {
+    return { isError: true, content: [{ type: 'text', text: 'Missing required argument: ticket' }] };
+  }
+  if (!args.body) {
+    return { isError: true, content: [{ type: 'text', text: 'Missing required argument: body' }] };
+  }
+  const capture = capturingStream();
+  const { ok } = await runTicketCommentFn([args.ticket, `--body=${args.body}`], { configDir, stream: capture });
+  const content = [{ type: 'text', text: capture.text }];
+  return ok ? { content } : { isError: true, content };
+}
+
+/**
+ * No `target` → discovery only, dispatched to the read-only list function —
+ * never touches the mutating path. `target` present → dispatched to the
+ * executing function, which itself still refuses without `confirm: true`
+ * (the MCP layer doesn't pre-empt that check, so the same refusal message
+ * a CLI user sees is what a calling AI harness sees too).
+ */
+async function callTicketTransition(args, { configDir, runTicketTransitionListFn, runTicketTransitionFn }) {
+  if (!args.ticket) {
+    return { isError: true, content: [{ type: 'text', text: 'Missing required argument: ticket' }] };
+  }
+  const capture = capturingStream();
+  if (!args.target) {
+    const { ok } = await runTicketTransitionListFn([args.ticket], { configDir, stream: capture });
+    const content = [{ type: 'text', text: capture.text }];
+    return ok ? { content } : { isError: true, content };
+  }
+  const cmdArgs = [args.ticket, `--target=${args.target}`];
+  if (args.confirm === true) cmdArgs.push('--confirm');
+  const { ok } = await runTicketTransitionFn(cmdArgs, { configDir, stream: capture });
+  const content = [{ type: 'text', text: capture.text }];
+  return ok ? { content } : { isError: true, content };
+}
+
 async function handleToolsCall(params, deps) {
   const { name, arguments: args = {} } = params ?? {};
   if (name === 'recall_add') return callRecallAdd(args, deps);
   if (name === 'recall_search') return callRecallSearch(args, deps);
+  if (name === 'ticket_comment') return callTicketComment(args, deps);
+  if (name === 'ticket_transition') return callTicketTransition(args, deps);
   return { isError: true, content: [{ type: 'text', text: `Unknown tool: ${name}` }] };
 }
 
-async function handleMessage(raw, { configDir, runNoteAddFn, runRecallFn }) {
+async function handleMessage(raw, { configDir, runNoteAddFn, runRecallFn, runTicketCommentFn, runTicketTransitionListFn, runTicketTransitionFn }) {
   let msg;
   try {
     msg = JSON.parse(raw);
@@ -149,7 +223,7 @@ async function handleMessage(raw, { configDir, runNoteAddFn, runRecallFn }) {
 
   if (method === 'tools/call') {
     try {
-      const result = await handleToolsCall(params, { configDir, runNoteAddFn, runRecallFn });
+      const result = await handleToolsCall(params, { configDir, runNoteAddFn, runRecallFn, runTicketCommentFn, runTicketTransitionListFn, runTicketTransitionFn });
       return jsonRpcResult(id, result);
     } catch (err) {
       return jsonRpcError(id ?? null, -32603, `Internal error: ${err.message}`);
@@ -172,6 +246,9 @@ export function runMcpServer({
   stdout = process.stdout,
   runNoteAddFn = runNoteAdd,
   runRecallFn = runRecall,
+  runTicketCommentFn = runTicketComment,
+  runTicketTransitionListFn = runTicketTransitionList,
+  runTicketTransitionFn = runTicketTransition,
 } = {}) {
   // A client can disconnect mid-write (EPIPE) at any time on a long-lived
   // process — an unhandled 'error' event on either stream would otherwise
@@ -191,7 +268,7 @@ export function runMcpServer({
     // never resolving (a dropped rejection isn't a resolution) — the
     // server would hang on shutdown instead of exiting.
     queue = queue.then(async () => {
-      const response = await handleMessage(line, { configDir, runNoteAddFn, runRecallFn });
+      const response = await handleMessage(line, { configDir, runNoteAddFn, runRecallFn, runTicketCommentFn, runTicketTransitionListFn, runTicketTransitionFn });
       if (response) stdout.write(response);
     }).catch(() => {});
   });

package/skills/jtb/scripts/lib/resolve-adapter.mjs

@@ -19,7 +19,7 @@ export function detectTrackerType(baseUrl) {
  * Instantiates the correct tracker adapter for a resolved connection.
  * @param {{ baseUrl: string, auth?: string, email?: string, apiToken?: string, pat?: string }} conn
  * @param {{ fetcher?: Function }} [opts]
- * @returns {{ type: string, fetchTicket: Function, fetchCurrentUser: Function, searchTickets: Function, fetchStatuses: Function }}
+ * @returns {{ type: string, fetchTicket: Function, fetchCurrentUser: Function, searchTickets: Function, fetchStatuses: Function, addComment: Function, getTransitions: Function, transition: Function }}
  */
 export function resolveAdapter(conn, opts = {}) {
   const type = detectTrackerType(conn?.baseUrl);

package/skills/jtb/scripts/lib/ticket-action-cooldown.mjs

@@ -0,0 +1,72 @@
+/**
+ * Local debounce guard against accidentally firing the same ticket write
+ * twice in quick succession (a flaky agent retry loop, a doubled CLI
+ * invocation, a human hitting enter twice). This is not a security boundary
+ * and not a notification-style cooldown — just enough of a window to catch a
+ * true double-fire without blocking a deliberate follow-up action moments
+ * later.
+ *
+ * Deliberately a separate file from ticket-action-log.mjs (the append-only
+ * audit trail): this file is small and read on every write attempt, so it
+ * must stay O(1) to check. A shared file would force scanning full history
+ * per check, or risk one read-modify-write clobbering the other's data.
+ * Same read-modify-write-no-lock tradeoff already accepted by
+ * recall-queue.mjs for the same reason — low-frequency, single-user CLI.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { DEFAULT_CONFIG_DIR } from './config.mjs';
+import { writeFileAtomically } from './recall-vault.mjs';
+
+const COOLDOWN_FILE = 'ticket-action-cooldown.json';
+
+/** Default debounce window: long enough to catch a true double-fire, short enough to never block a deliberate follow-up action. */
+export const DEFAULT_COOLDOWN_MS = 10_000;
+
+function cooldownPath(configDir) {
+  return path.join(configDir, COOLDOWN_FILE);
+}
+
+function readCooldowns(configDir) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(cooldownPath(configDir), 'utf8'));
+    return (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+function cooldownKey(ticketKey, action) {
+  return `${ticketKey}:${action}`;
+}
+
+/**
+ * @param {string} ticketKey
+ * @param {string} action
+ * @param {{ configDir?: string, cooldownMs?: number, now?: () => number }} [opts]
+ * @returns {{ active: boolean, remainingMs: number }}
+ */
+export function checkCooldown(ticketKey, action, {
+  configDir = DEFAULT_CONFIG_DIR,
+  cooldownMs = DEFAULT_COOLDOWN_MS,
+  now = () => Date.now(),
+} = {}) {
+  const lastAt = readCooldowns(configDir)[cooldownKey(ticketKey, action)];
+  if (!lastAt) return { active: false, remainingMs: 0 };
+
+  const elapsed = now() - new Date(lastAt).getTime();
+  const remainingMs = cooldownMs - elapsed;
+  return remainingMs > 0 ? { active: true, remainingMs } : { active: false, remainingMs: 0 };
+}
+
+/**
+ * @param {string} ticketKey
+ * @param {string} action
+ * @param {{ configDir?: string, now?: () => number }} [opts]
+ */
+export function recordAction(ticketKey, action, { configDir = DEFAULT_CONFIG_DIR, now = () => Date.now() } = {}) {
+  const cooldowns = readCooldowns(configDir);
+  cooldowns[cooldownKey(ticketKey, action)] = new Date(now()).toISOString();
+  writeFileAtomically(cooldownPath(configDir), JSON.stringify(cooldowns));
+}

package/skills/jtb/scripts/lib/ticket-action-log.mjs

@@ -0,0 +1,72 @@
+/**
+ * Append-only forensic audit trail for ticket writes (comment/transition).
+ * Every entry is JSON-serialized on its own line — comment bodies are
+ * attacker/AI-controlled free text, and a raw newline embedded in one could
+ * otherwise forge a fake extra log line (same bug class already fixed once
+ * in this codebase for brief section filenames). JSON.stringify escapes
+ * embedded newlines as \n within the string, so one JSON.parse per line
+ * always recovers exactly one real entry.
+ *
+ * Deliberately a separate file from ticket-action-cooldown.mjs — this one
+ * only ever grows and is never read on the hot path of a write attempt, so
+ * its O(n) full-file nature doesn't matter to normal command latency.
+ *
+ * ticketKey is validated by the caller (ticket-command.mjs, via
+ * TICKET_KEY_PATTERN) before it ever reaches here — this module re-validates
+ * defensively since a log line is a place a malformed key could otherwise do
+ * real damage (path traversal has no surface here since the log file path
+ * never incorporates ticketKey, but a stray literal newline inside an
+ * unvalidated key would reintroduce exactly the forgeable-line risk this
+ * file exists to prevent).
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { DEFAULT_CONFIG_DIR } from './config.mjs';
+import { TICKET_KEY_PATTERN } from './cli.mjs';
+
+const LOG_FILE = 'ticket-action-log.jsonl';
+
+function logPath(configDir) {
+  return path.join(configDir, LOG_FILE);
+}
+
+/**
+ * @param {{ ticketKey: string, action: 'comment'|'transition', actor: string, tracker: string, detail?: object }} entry
+ * @param {{ configDir?: string, now?: () => Date }} [opts]
+ */
+export function logAction({ ticketKey, action, actor, tracker, detail = {} }, {
+  configDir = DEFAULT_CONFIG_DIR,
+  now = () => new Date(),
+} = {}) {
+  if (!TICKET_KEY_PATTERN.test(ticketKey)) {
+    throw new Error(`Refusing to log malformed ticket key: ${JSON.stringify(ticketKey)}`);
+  }
+  const line = JSON.stringify({ ticketKey, action, actor, tracker, detail, at: now().toISOString() });
+  fs.appendFileSync(logPath(configDir), line + '\n', 'utf8');
+}
+
+/**
+ * @param {string} [configDir]
+ * @returns {object[]} parsed entries, oldest first — a corrupt individual
+ *   line is skipped rather than failing the whole read, since this is an
+ *   append-only historical record and one bad line must not hide the rest.
+ */
+export function readActionLog(configDir = DEFAULT_CONFIG_DIR) {
+  let raw;
+  try {
+    raw = fs.readFileSync(logPath(configDir), 'utf8');
+  } catch {
+    return [];
+  }
+  const entries = [];
+  for (const line of raw.split('\n')) {
+    if (!line.trim()) continue;
+    try {
+      entries.push(JSON.parse(line));
+    } catch {
+      // Skip a corrupt line — never let one bad append hide the rest of the trail.
+    }
+  }
+  return entries;
+}

package/skills/jtb/scripts/lib/ticket-command.mjs

@@ -0,0 +1,236 @@
+/**
+ * Implements `tl comment` and `tl transition`. Both are Pro+-gated writes to
+ * the underlying tracker (Jira/GitHub/Linear), consistent with the rest of
+ * the Recall/MCP family. `transition` is split into two functions from the
+ * start — list (read-only discovery) and execute (requires a resolved
+ * --target + --confirm) — rather than one function branching internally,
+ * so each independently matches the established runX(cmdArgs, deps) -> {ok}
+ * single-decision shape. `--confirm` is a behavioral nudge and audit trail,
+ * not a hard security guarantee — framed that way deliberately, not oversold.
+ */
+
+import os from 'node:os';
+import { DEFAULT_CONFIG_DIR } from './config.mjs';
+import { isLicensed, showUpgradePrompt } from './license.mjs';
+import { resolveConnection } from './profile-resolver.mjs';
+import { resolveAdapter } from './resolve-adapter.mjs';
+import { checkCooldown, recordAction } from './ticket-action-cooldown.mjs';
+import { logAction } from './ticket-action-log.mjs';
+import { TICKET_KEY_PATTERN } from './cli.mjs';
+
+function parseFlag(cmdArgs, name) {
+  return cmdArgs.find(a => a.startsWith(`--${name}=`))?.slice(name.length + 3);
+}
+
+/**
+ * Distinguishes retryable/terminal/rate-limited write failures so CLI and
+ * MCP callers get the same actionable signal instead of a generic catch —
+ * mirrors recall-queue.mjs's isRetryableFailure/pushNote pairing. Never
+ * auto-retries a timeout itself: a timed-out write may have already landed
+ * server-side, unlike Recall's idempotent-by-external_id notes.
+ *
+ * @param {Error & { status?: number, rateLimit?: object }} err
+ * @returns {{ kind: 'rate-limited'|'network-or-timeout'|'server-error'|'terminal', [key: string]: unknown }}
+ */
+export function classifyWriteFailure(err) {
+  if (err?.rateLimit) {
+    return { kind: 'rate-limited', detail: err.rateLimit };
+  }
+  if (err?.status === undefined) {
+    return { kind: 'network-or-timeout' };
+  }
+  if (err.status >= 500) {
+    return { kind: 'server-error', status: err.status };
+  }
+  return { kind: 'terminal', status: err.status, details: err.details };
+}
+
+function formatWriteFailure(ticketKey, err) {
+  const classification = classifyWriteFailure(err);
+  switch (classification.kind) {
+    case 'rate-limited': {
+      const wait = classification.detail.retryAfterSeconds ?? null;
+      return wait
+        ? `  Rate limited by the tracker — retry ${ticketKey} after ~${wait}s.\n`
+        : `  Rate limited by the tracker — try ${ticketKey} again later.\n`;
+    }
+    case 'network-or-timeout':
+      return `  Network error or timeout writing to ${ticketKey} — not retried automatically (a timed-out write may have already landed). Check the ticket before retrying.\n`;
+    case 'server-error':
+      return `  Tracker returned a server error (${classification.status}) for ${ticketKey}. Try again later.\n`;
+    default:
+      return `  Failed to write to ${ticketKey}: ${err.message}\n`;
+  }
+}
+
+function requireLicense(isLicensedFn, configDir, commandName, stream) {
+  if (isLicensedFn('pro', configDir)) return true;
+  showUpgradePrompt('pro', commandName, { stream });
+  return false;
+}
+
+function requireTicketKey(cmdArgs, usage, stream) {
+  const ticketKey = cmdArgs[0];
+  if (!ticketKey || ticketKey.startsWith('--') || !TICKET_KEY_PATTERN.test(ticketKey)) {
+    stream.write(usage);
+    return null;
+  }
+  return ticketKey;
+}
+
+function resolveTicketAdapter(ticketKey, cmdArgs, { configDir, resolveConnectionFn, resolveAdapterFn, stream }) {
+  const profileName = parseFlag(cmdArgs, 'profile');
+  const conn = resolveConnectionFn(ticketKey, { configDir, profileName });
+  if (!conn.baseUrl) {
+    stream.write(`  No connection configured for ${ticketKey}. Run \`ticketlens init\`.\n`);
+    return null;
+  }
+  return resolveAdapterFn(conn);
+}
+
+/**
+ * @param {string[]} cmdArgs - [ticketKey, ...flags], e.g. ["PROJ-1", '--body=Looks good']
+ * @returns {Promise<{ ok: boolean }>}
+ */
+export async function runTicketComment(cmdArgs, {
+  configDir = DEFAULT_CONFIG_DIR,
+  stream = process.stderr,
+  isLicensedFn = isLicensed,
+  resolveConnectionFn = resolveConnection,
+  resolveAdapterFn = resolveAdapter,
+  checkCooldownFn = checkCooldown,
+  recordActionFn = recordAction,
+  logActionFn = logAction,
+  actor = os.userInfo().username,
+} = {}) {
+  const usage = 'Usage: ticketlens comment TICKET-KEY --body="..."\n';
+  if (!requireLicense(isLicensedFn, configDir, 'ticketlens comment', stream)) return { ok: false };
+
+  const ticketKey = requireTicketKey(cmdArgs, usage, stream);
+  if (!ticketKey) return { ok: false };
+
+  const body = parseFlag(cmdArgs, 'body');
+  if (!body) {
+    stream.write(usage);
+    return { ok: false };
+  }
+
+  const cooldown = checkCooldownFn(ticketKey, 'comment', { configDir });
+  if (cooldown.active) {
+    stream.write(`  Skipped — a comment was already posted to ${ticketKey} ${Math.ceil(cooldown.remainingMs / 1000)}s ago. Wait a moment before retrying.\n`);
+    return { ok: false };
+  }
+
+  const adapter = resolveTicketAdapter(ticketKey, cmdArgs, { configDir, resolveConnectionFn, resolveAdapterFn, stream });
+  if (!adapter) return { ok: false };
+
+  try {
+    const result = await adapter.addComment(ticketKey, body);
+    recordActionFn(ticketKey, 'comment', { configDir });
+    logActionFn({ ticketKey, action: 'comment', actor, tracker: adapter.type, detail: { id: result.id } }, { configDir });
+    stream.write(`  Comment posted to ${ticketKey}${result.url ? ` (${result.url})` : ''}\n`);
+    return { ok: true };
+  } catch (err) {
+    stream.write(formatWriteFailure(ticketKey, err));
+    return { ok: false };
+  }
+}
+
+/**
+ * Discovery only — never mutates. Lists the tracker's current valid
+ * transition options for the ticket.
+ *
+ * @param {string[]} cmdArgs - [ticketKey]
+ * @returns {Promise<{ ok: boolean, options?: object[] }>}
+ */
+export async function runTicketTransitionList(cmdArgs, {
+  configDir = DEFAULT_CONFIG_DIR,
+  stream = process.stderr,
+  isLicensedFn = isLicensed,
+  resolveConnectionFn = resolveConnection,
+  resolveAdapterFn = resolveAdapter,
+} = {}) {
+  const usage = 'Usage: ticketlens transition TICKET-KEY [--target="..." --confirm]\n';
+  if (!requireLicense(isLicensedFn, configDir, 'ticketlens transition', stream)) return { ok: false };
+
+  const ticketKey = requireTicketKey(cmdArgs, usage, stream);
+  if (!ticketKey) return { ok: false };
+
+  const adapter = resolveTicketAdapter(ticketKey, cmdArgs, { configDir, resolveConnectionFn, resolveAdapterFn, stream });
+  if (!adapter) return { ok: false };
+
+  try {
+    const options = await adapter.getTransitions(ticketKey);
+    if (options.length === 0) {
+      stream.write(`  No valid transitions available for ${ticketKey}.\n`);
+      return { ok: true, options: [] };
+    }
+    stream.write(`  Valid transitions for ${ticketKey}:\n`);
+    for (const o of options) stream.write(`    - ${o.name}\n`);
+    stream.write(`  Run again with --target="<name>" --confirm to execute.\n`);
+    return { ok: true, options };
+  } catch (err) {
+    stream.write(formatWriteFailure(ticketKey, err));
+    return { ok: false };
+  }
+}
+
+/**
+ * Executes a transition. Requires both --target and --confirm — a target
+ * without --confirm is treated as incomplete input, never silently executed.
+ *
+ * @param {string[]} cmdArgs - [ticketKey, '--target=...', '--confirm']
+ * @returns {Promise<{ ok: boolean, reason?: string }>}
+ */
+export async function runTicketTransition(cmdArgs, {
+  configDir = DEFAULT_CONFIG_DIR,
+  stream = process.stderr,
+  isLicensedFn = isLicensed,
+  resolveConnectionFn = resolveConnection,
+  resolveAdapterFn = resolveAdapter,
+  checkCooldownFn = checkCooldown,
+  recordActionFn = recordAction,
+  logActionFn = logAction,
+  actor = os.userInfo().username,
+} = {}) {
+  const usage = 'Usage: ticketlens transition TICKET-KEY --target="..." --confirm\n';
+  if (!requireLicense(isLicensedFn, configDir, 'ticketlens transition', stream)) return { ok: false };
+
+  const ticketKey = requireTicketKey(cmdArgs, usage, stream);
+  if (!ticketKey) return { ok: false };
+
+  const target = parseFlag(cmdArgs, 'target');
+  if (!target) {
+    stream.write(usage);
+    return { ok: false };
+  }
+  if (!cmdArgs.includes('--confirm')) {
+    stream.write(`  Refusing to transition ${ticketKey} to "${target}" without --confirm. Re-run with --confirm once you've reviewed the target.\n`);
+    return { ok: false };
+  }
+
+  const cooldown = checkCooldownFn(ticketKey, 'transition', { configDir });
+  if (cooldown.active) {
+    stream.write(`  Skipped — ${ticketKey} was already transitioned ${Math.ceil(cooldown.remainingMs / 1000)}s ago. Wait a moment before retrying.\n`);
+    return { ok: false };
+  }
+
+  const adapter = resolveTicketAdapter(ticketKey, cmdArgs, { configDir, resolveConnectionFn, resolveAdapterFn, stream });
+  if (!adapter) return { ok: false };
+
+  try {
+    const result = await adapter.transition(ticketKey, target);
+    if (!result.executed) {
+      const optionsHint = result.options?.length ? ` Valid options: ${result.options.map(o => o.name).join(', ')}.` : '';
+      stream.write(`  Not transitioned — ${result.reason}.${optionsHint}\n`);
+      return { ok: false, reason: result.reason };
+    }
+    recordActionFn(ticketKey, 'transition', { configDir });
+    logActionFn({ ticketKey, action: 'transition', actor, tracker: adapter.type, detail: { to: result.to } }, { configDir });
+    stream.write(`  ${ticketKey} transitioned to "${result.to}".\n`);
+    return { ok: true };
+  } catch (err) {
+    stream.write(formatWriteFailure(ticketKey, err));
+    return { ok: false };
+  }
+}