ticketlens 0.26.0 → 0.27.0

package/README.md

@@ -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`, `recall_search`, `ticket_comment`, `ticket_transition`, `ticket_assign`, and `ticket_duplicates` 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).
+**Any MCP-capable AI harness:** `ticketlens mcp` starts a stdio [MCP](https://modelcontextprotocol.io) server exposing `recall_add`, `recall_search`, `ticket_comment`, `ticket_transition`, `ticket_assign`, `ticket_duplicates`, and `ticket_link` 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,7 +419,7 @@ Every note is scanned before saving — anything shaped like a real secret (API
 
 ---
 
-### Comment, Transition, Assign & Duplicates
+### Comment, Transition, Assign, Duplicates & Link
 
 ```bash
 ticketlens comment PROJ-123 --body="Looks good, merging."   # Post a comment to the tracker
@@ -427,9 +427,11 @@ ticketlens transition PROJ-123                              # List valid transit
 ticketlens transition PROJ-123 --target="Done" --confirm    # Execute the transition
 ticketlens assign PROJ-123 --to=me                           # Assign the ticket to yourself
 ticketlens duplicates PROJ-123                                # Find likely duplicates (read-only)
+ticketlens link PROJ-123 PROJ-456                             # List valid link types (read-only)
+ticketlens link PROJ-123 PROJ-456 --type="Duplicate" --confirm  # Execute the link
 ```
 
-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`/`ticket_duplicates` MCP tools. Requires a Pro license.
+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`/`ticket_duplicates`/`ticket_link` 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.
 
@@ -437,7 +439,9 @@ Write directly to the ticket in its real tracker — Jira, GitHub, or Linear —
 
 `ticketlens duplicates` is read-only — it never links or changes anything, just lists likely matches in the same project. No tracker (Jira/GitHub/Linear) scores similarity server-side, so ranking happens locally from title/description word overlap; treat a match as a nudge to check manually, not a verdict. `--threshold=N` (0–1, default 0.35) controls how loose a match counts.
 
-All three write actions (comment/transition/assign) 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. `duplicates` has neither, since nothing is written.
+`ticketlens link SOURCE-KEY TARGET-KEY` links two tickets — direction matters: SOURCE "types" TARGET (e.g. `link A B --type=Duplicate` means A duplicates B, not the other way around). With just the two keys it lists the tracker's current valid link types without changing anything — always fetched live for Jira, since link type names are per-instance configurable there. GitHub is different from Jira/Linear: it has no generic link relationship, so linking on a GitHub-tracked ticket *closes SOURCE as a duplicate of TARGET* — a state change, not just a relationship add — and prints an explicit warning immediately before that happens, on top of the same `--confirm` gate.
+
+All four write actions (comment/transition/assign/link) 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. `duplicates` has neither, since nothing is written.
 
 ---
 
@@ -718,13 +722,15 @@ ticketlens mcp                                # Start the MCP stdio server (reca
 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 & Duplicates ────────────────────────────────────
+# ── Comment, Transition, Assign, Duplicates & Link ──────────────────────────────
 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]
 ticketlens duplicates CNV1-2                                # Find likely duplicates (read-only) [Pro]
 ticketlens duplicates CNV1-2 --threshold=0.5                # Tighten the match threshold [Pro]
+ticketlens link CNV1-2 CNV1-3                               # List valid link types (read-only) [Pro]
+ticketlens link CNV1-2 CNV1-3 --type="Duplicate" --confirm  # Execute the link [Pro]
 
 # ── Stats ──────────────────────────────────────────────────────────────────────
 ticketlens stats                              # Response-time metrics from local history
@@ -811,6 +817,7 @@ 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 duplicates CNV1-2             # Find likely duplicates (read-only)
+ticketlens link CNV1-2 CNV1-3 --type="Duplicate" --confirm  # Link two tickets
 ticketlens activate YOUR-LICENSE-KEY     # Activate Pro license
 ```
 

package/bin/ticketlens.mjs

@@ -28,7 +28,7 @@ import {
   printCollisionsHelp, printStatsHelp,
   printCloudKeysHelp,
   printNoteHelp, printRecallHelp, printMcpHelp,
-  printCommentHelp, printTransitionHelp, printAssignHelp, printDuplicatesHelp,
+  printCommentHelp, printTransitionHelp, printAssignHelp, printDuplicatesHelp, printLinkHelp,
 } 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';
@@ -790,6 +790,22 @@ switch (command) {
     break;
   }
 
+  case 'link': {
+    if (cmdArgs.includes('--help') || cmdArgs.includes('-h')) { printLinkHelp(); break; }
+    const { runTicketLinkList, runTicketLink } = await import('../skills/jtb/scripts/lib/ticket-command.mjs');
+    // No --type → discovery only, never mutates. --type present → execute
+    // (runTicketLink itself still refuses without --confirm).
+    const hasType = cmdArgs.some(a => a.startsWith('--type='));
+    const runFn = hasType ? runTicketLink : runTicketLinkList;
+    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.26.0",
+  "version": "0.27.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/scripts/lib/adapters/github-adapter.mjs

@@ -29,6 +29,7 @@ export function parseGitHubRepo(baseUrl) {
 export function normalizeGitHubIssue(raw, comments = [], keyPrefix = 'GH') {
   return {
     key: `${keyPrefix}-${raw.number}`,
+    id: raw.id,
     summary: raw.title,
     type: 'Issue',
     status: raw.state,
@@ -240,5 +241,36 @@ export function createGitHubAdapter(conn, { fetcher = globalThis.fetch } = {}) {
         .filter(item => item.number !== sourceNumber)
         .map(item => normalizeGitHubIssue(item, [], keyPrefix));
     },
+
+    /**
+     * GitHub has no generic link-type concept — "duplicate" (via closing
+     * the source issue) is the only relationship it supports natively.
+     */
+    async getLinkTypes() {
+      return ['duplicate'];
+    },
+
+    /**
+     * GitHub's only real "link" action closes sourceKey as a duplicate of
+     * targetKey — asymmetric and state-changing, unlike Jira/Linear's pure
+     * relationship-add. Resolves targetKey's internal id via fetchTicket
+     * (GitHub's duplicate_issue_id wants the internal id, not the
+     * repo-local number).
+     */
+    async linkTo(sourceKey, targetKey, typeName, opts = {}) {
+      if (typeName.toLowerCase() !== 'duplicate') {
+        throw new Error(`GitHub only supports linking as a duplicate — got type "${typeName}".`);
+      }
+      const target = await this.fetchTicket(targetKey, opts);
+      const sourceNumber = parseInt(sourceKey.split('-').pop(), 10);
+      const res = await fetcher(`${GITHUB_API}/repos/${owner}/${repo}/issues/${sourceNumber}`, {
+        method: 'PATCH',
+        headers: { ...headers, 'Content-Type': 'application/json' },
+        body: JSON.stringify({ state: 'closed', state_reason: 'duplicate', duplicate_issue_id: target.id }),
+        signal: AbortSignal.timeout(opts.timeoutMs ?? 10_000),
+      });
+      if (!res.ok) await throwGitHubWriteError(res, 'linking', sourceKey);
+      return { executed: true, closedAsDuplicateOf: targetKey };
+    },
   };
 }

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

@@ -1,4 +1,4 @@
-import { fetchTicket, fetchCurrentUser, searchTickets, fetchStatuses, postComment, getTransitions, postTransition, assignIssue, escapeJql } from '../jira-client.mjs';
+import { fetchTicket, fetchCurrentUser, searchTickets, fetchStatuses, postComment, getTransitions, postTransition, assignIssue, escapeJql, getIssueLinkTypes, postIssueLink } from '../jira-client.mjs';
 import { buildJiraEnv } from '../config.mjs';
 
 /**
@@ -83,5 +83,32 @@ export function createJiraAdapter(conn, { fetcher = globalThis.fetch } = {}) {
       const jql = `project = "${escapeJql(project)}" AND key != "${escapeJql(sourceKey)}" AND text ~ "${escapeJql(searchText)}" ORDER BY updated DESC`;
       return searchTickets(jql, { ...base, ...opts });
     },
+
+    /**
+     * Always fetched fresh — link type names are per-instance customizable
+     * in Jira, same "never trust a stale list" principle as getTransitions.
+     * Returns just names (matches GitHub/Linear's plain-string shape) so
+     * runTicketLinkList can render any tracker's list uniformly.
+     */
+    async getLinkTypes(opts = {}) {
+      const types = await getIssueLinkTypes({ ...base, ...opts });
+      return types.map(t => t.name);
+    },
+
+    /**
+     * Always re-fetches link types fresh and resolves `typeName` against
+     * them before executing — a caller can never blind-POST a stale or
+     * guessed type name, same principle as transition().
+     * sourceKey is the outwardIssue, targetKey is the inwardIssue — direction matters.
+     */
+    async linkTo(sourceKey, targetKey, typeName, opts = {}) {
+      const types = await getIssueLinkTypes({ ...base, ...opts });
+      const match = types.find(t => t.name.toLowerCase() === typeName.toLowerCase());
+      if (!match) {
+        return { executed: false, reason: 'not-found', options: types.map(t => t.name) };
+      }
+      await postIssueLink(sourceKey, targetKey, match.name, { ...base, ...opts });
+      return { executed: true };
+    },
   };
 }

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

@@ -4,6 +4,9 @@ const LINEAR_API = 'https://api.linear.app/graphql';
 
 const PRIORITY_LABELS = { 1: 'Urgent', 2: 'High', 3: 'Medium', 4: 'Low' };
 
+/** Linear's IssueRelationType enum — fixed schema-level values, confirmed via GraphQL introspection. */
+const LINK_TYPES = ['blocks', 'duplicate', 'related'];
+
 const ISSUE_FIELDS = `
   identifier
   title
@@ -295,5 +298,43 @@ export function createLinearAdapter(conn, { fetcher = globalThis.fetch } = {}) {
         .filter(node => node.identifier !== sourceKey)
         .map(normalizeLinearIssue);
     },
+
+    /** Fixed schema-level enum (confirmed via GraphQL introspection) — never per-instance configurable, unlike Jira's link types. */
+    async getLinkTypes() {
+      return LINK_TYPES;
+    },
+
+    /**
+     * Validates typeName against the fixed enum before ever touching the
+     * network — an invalid type must never reach gql(), which throws a
+     * plain Error with no .status, and would otherwise be misclassified
+     * as a network/timeout failure by classifyWriteFailure. Resolves both
+     * issues' internal UUIDs via fetchIssueStateInfo — issueRelationCreate
+     * needs the UUID, never the human identifier. Explicitly checks
+     * `success`: Linear can return HTTP 200 with no top-level GraphQL
+     * errors and still report success:false.
+     */
+    async linkTo(sourceKey, targetKey, typeName, opts = {}) {
+      const normalizedType = typeName.toLowerCase();
+      if (!LINK_TYPES.includes(normalizedType)) {
+        return { executed: false, reason: 'not-found', options: LINK_TYPES };
+      }
+      const signal = AbortSignal.timeout(opts.timeoutMs ?? 10_000);
+      const source = await fetchIssueStateInfo(sourceKey, { token, fetcher, signal });
+      const target = await fetchIssueStateInfo(targetKey, { token, fetcher, signal });
+      const data = await gql(
+        `mutation ($issueId: String!, $relatedIssueId: String!, $type: IssueRelationType!) {
+          issueRelationCreate(input: { issueId: $issueId, relatedIssueId: $relatedIssueId, type: $type }) {
+            success
+          }
+        }`,
+        { issueId: source.id, relatedIssueId: target.id, type: normalizedType },
+        { token, fetcher, signal },
+      );
+      if (!data.issueRelationCreate?.success) {
+        throw new Error(`Linear issueRelationCreate reported success:false linking ${sourceKey} to ${targetKey}`);
+      }
+      return { executed: true };
+    },
   };
 }

package/skills/jtb/scripts/lib/api-utils.mjs

@@ -3,7 +3,7 @@
  * Centralised here to avoid triplicating the regex and warning logic.
  */
 
-export const DEFAULT_API_BASE = 'https://api.ticketlens.app';
+export const DEFAULT_API_BASE = 'http://api.ticketlens.test';
 export const DEFAULT_SITE_BASE = 'https://ticketlens.app';
 
 // Matches localhost, 127.0.0.1, and any hostname ending in .test or .local,

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

@@ -146,6 +146,10 @@ export function parseCommand(args) {
     return { command: 'duplicates', args: args.slice(1) };
   }
 
+  if (first === 'link') {
+    return { command: 'link', 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

@@ -58,6 +58,7 @@ export function printHelp({ stream = process.stdout } = {}) {
     `    ${s.brand('ticketlens')} transition ${s.dim('<TICKET-KEY> [--target=... --confirm]')}  Move ticket status  ${s.dim('[Pro]')}`,
     `    ${s.brand('ticketlens')} assign ${s.dim('<TICKET-KEY> --to=me')}      Assign a ticket to yourself  ${s.dim('[Pro]')}`,
     `    ${s.brand('ticketlens')} duplicates ${s.dim('<TICKET-KEY> [--threshold=N]')}  Find likely duplicate tickets  ${s.dim('[Pro]')}`,
+    `    ${s.brand('ticketlens')} link ${s.dim('<SOURCE> <TARGET> [--type=... --confirm]')}  Link two tickets  ${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`,
@@ -598,12 +599,13 @@ export function printMcpHelp({ stream = process.stdout } = {}) {
     '',
     `  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')}, ${s.cyan('ticket_assign')}, ${s.cyan('ticket_duplicates')} — 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')}/${s.cyan('assign')}/${s.cyan('duplicates')} above: same Pro gate, same`,
-    `  local vault/tracker writes, same team sync. ${s.cyan('ticket_transition')} is destructive when`,
-    `  called with \`target\`+\`confirm: true\`; ${s.cyan('ticket_assign')} is currently self-assign only;`,
-    `  ${s.cyan('ticket_duplicates')} is read-only.`,
+    `  ${s.cyan('ticket_transition')}, ${s.cyan('ticket_assign')}, ${s.cyan('ticket_duplicates')}, ${s.cyan('ticket_link')} — 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')}/${s.cyan('assign')}/${s.cyan('duplicates')}/${s.cyan('link')} above: same Pro gate,`,
+    `  same local vault/tracker writes, same team sync. ${s.cyan('ticket_transition')} is destructive`,
+    `  when called with \`target\`+\`confirm: true\`; ${s.cyan('ticket_assign')} is currently self-assign`,
+    `  only; ${s.cyan('ticket_duplicates')} is read-only; ${s.cyan('ticket_link')} on GitHub closes the source`,
+    `  issue as a duplicate — different semantics than Jira/Linear's relationship-only add.`,
     `  Long-running — exits when the client closes stdin.`,
     '',
     `  ${s.bold('OPTIONS')}`,
@@ -730,6 +732,39 @@ export function printDuplicatesHelp({ stream = process.stdout } = {}) {
   stream.write(lines.join('\n') + '\n');
 }
 
+export function printLinkHelp({ stream = process.stdout } = {}) {
+  const s = createStyler({ isTTY: stream.isTTY });
+  const lines = [
+    '',
+    `  ${s.bold(s.brand('ticketlens'))} ${s.bold('link')} ${s.dim('SOURCE-KEY TARGET-KEY [--type="..." --confirm]')}  ${s.dim('[Pro]')}`,
+    '',
+    `  Link two tickets in their tracker (Jira/GitHub/Linear). ${s.dim('[Pro]')}`,
+    `  Called with just SOURCE and TARGET, lists the tracker's current valid`,
+    `  link types without changing anything. Add ${s.brand('--type')} and ${s.brand('--confirm')} together to execute.`,
+    '',
+    `  ${s.bold('Direction matters')}: SOURCE "types" TARGET — e.g. \`link A B --type=Duplicate\` means`,
+    `  A duplicates B, not the other way around.`,
+    '',
+    `  ${s.bold('GitHub is different')}: it has no generic link relationship. Linking on a`,
+    `  GitHub-tracked ticket CLOSES SOURCE as a duplicate of TARGET — a state`,
+    `  change, not just a relationship add like Jira/Linear.`,
+    '',
+    `  ${s.bold('OPTIONS')}`,
+    '',
+    `    ${s.brand('--type')}=${s.dim('NAME')}    Link type ${s.dim('(from the list, case-insensitive; GitHub only supports "duplicate")')}`,
+    `    ${s.brand('--confirm')}     Required alongside --type 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 link PROD-123 PROD-456`,
+    `    ${s.dim('$')} ticketlens link PROD-123 PROD-456 --type="Duplicate" --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

@@ -502,6 +502,61 @@ export async function postTransition(ticketKey, transitionId, opts = {}) {
   }
 }
 
+/**
+ * Lists this Jira instance's issue link types (id/name/inward/outward).
+ * Link type names are per-instance customizable — never hardcode or cache
+ * this list; callers must re-fetch fresh before every link, same principle
+ * as getTransitions().
+ */
+export async function getIssueLinkTypes(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}/issueLinkType`;
+
+  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 issue link types`);
+    err.status = response.status;
+    throw err;
+  }
+  const raw = await response.json();
+  return (raw.issueLinkTypes ?? []).map(t => ({ id: t.id, name: t.name, inward: t.inward, outward: t.outward }));
+}
+
+/**
+ * Creates a link between two issues. `sourceKey` is the outwardIssue (the
+ * subject of the type's outward verb, e.g. "Duplicates"), `targetKey` is
+ * the inwardIssue — direction matters and is the caller's responsibility
+ * to get right (ticket-command.mjs documents the convention).
+ */
+export async function postIssueLink(sourceKey, targetKey, typeName, 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}/issueLink`;
+
+  const fetchOpts = {
+    method: 'POST',
+    headers: { ...buildAuthHeader(env), 'Content-Type': 'application/json' },
+    body: JSON.stringify({ type: { name: typeName }, outwardIssue: { key: sourceKey }, inwardIssue: { key: targetKey } }),
+  };
+  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} linking ${sourceKey} to ${targetKey}`);
+    err.status = response.status;
+    err.details = details;
+    throw err;
+  }
+}
+
 /**
  * Sets the issue's assignee. `assignee` is sent verbatim — the caller
  * (jira-adapter.mjs) resolves the right shape for the API version:

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

@@ -23,7 +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, runTicketAssign, runTicketDuplicates } from './ticket-command.mjs';
+import { runTicketComment, runTicketTransitionList, runTicketTransition, runTicketAssign, runTicketDuplicates, runTicketLinkList, runTicketLink } from './ticket-command.mjs';
 
 const PROTOCOL_VERSION = '2025-11-25';
 
@@ -102,6 +102,20 @@ const TOOLS = [
       required: ['ticket'],
     },
   },
+  {
+    name: 'ticket_link',
+    description: 'List or execute a link between two tickets in their tracker (Jira/GitHub/Linear). Called with only `ticket`/`target`, lists the tracker\'s current valid link types without changing anything. Destructive when `type` and `confirm: true` are both given — writes directly to the live tracker. Direction matters: `ticket` "types" `target` (e.g. ticket duplicates target). On GitHub, executing CLOSES `ticket` as a duplicate of `target` — a state change, not just a relationship add like Jira/Linear. Requires a TicketLens Pro license.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        ticket: { type: 'string', description: 'Source ticket key, e.g. PROJ-123 — the one that "types" target.' },
+        target: { type: 'string', description: 'Target ticket key, e.g. PROJ-456.' },
+        type: { type: 'string', description: 'Link type name (from the list). Omit to just list the tracker\'s current valid options. GitHub only supports "duplicate".' },
+        confirm: { type: 'boolean', description: 'Must be true, alongside `type`, to actually execute the link — a nudge and audit trail, not just a formality.' },
+      },
+      required: ['ticket', 'target'],
+    },
+  },
 ];
 
 function jsonRpcResult(id, result) {
@@ -233,6 +247,32 @@ async function callTicketDuplicates(args, { configDir, runTicketDuplicatesFn })
   return ok ? { content } : { isError: true, content };
 }
 
+/**
+ * No `type` → discovery only, dispatched to the read-only list function —
+ * never touches the mutating path. `type` present → dispatched to the
+ * executing function, which itself still refuses without `confirm: true`
+ * (the MCP layer doesn't pre-empt that check, same as ticket_transition).
+ */
+async function callTicketLink(args, { configDir, runTicketLinkListFn, runTicketLinkFn }) {
+  if (!args.ticket) {
+    return { isError: true, content: [{ type: 'text', text: 'Missing required argument: ticket' }] };
+  }
+  if (!args.target) {
+    return { isError: true, content: [{ type: 'text', text: 'Missing required argument: target' }] };
+  }
+  const capture = capturingStream();
+  if (!args.type) {
+    const { ok } = await runTicketLinkListFn([args.ticket, args.target], { configDir, stream: capture });
+    const content = [{ type: 'text', text: capture.text }];
+    return ok ? { content } : { isError: true, content };
+  }
+  const cmdArgs = [args.ticket, args.target, `--type=${args.type}`];
+  if (args.confirm === true) cmdArgs.push('--confirm');
+  const { ok } = await runTicketLinkFn(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);
@@ -241,10 +281,11 @@ async function handleToolsCall(params, deps) {
   if (name === 'ticket_transition') return callTicketTransition(args, deps);
   if (name === 'ticket_assign') return callTicketAssign(args, deps);
   if (name === 'ticket_duplicates') return callTicketDuplicates(args, deps);
+  if (name === 'ticket_link') return callTicketLink(args, deps);
   return { isError: true, content: [{ type: 'text', text: `Unknown tool: ${name}` }] };
 }
 
-async function handleMessage(raw, { configDir, runNoteAddFn, runRecallFn, runTicketCommentFn, runTicketTransitionListFn, runTicketTransitionFn, runTicketAssignFn, runTicketDuplicatesFn }) {
+async function handleMessage(raw, { configDir, runNoteAddFn, runRecallFn, runTicketCommentFn, runTicketTransitionListFn, runTicketTransitionFn, runTicketAssignFn, runTicketDuplicatesFn, runTicketLinkListFn, runTicketLinkFn }) {
   let msg;
   try {
     msg = JSON.parse(raw);
@@ -274,7 +315,7 @@ async function handleMessage(raw, { configDir, runNoteAddFn, runRecallFn, runTic
 
   if (method === 'tools/call') {
     try {
-      const result = await handleToolsCall(params, { configDir, runNoteAddFn, runRecallFn, runTicketCommentFn, runTicketTransitionListFn, runTicketTransitionFn, runTicketAssignFn, runTicketDuplicatesFn });
+      const result = await handleToolsCall(params, { configDir, runNoteAddFn, runRecallFn, runTicketCommentFn, runTicketTransitionListFn, runTicketTransitionFn, runTicketAssignFn, runTicketDuplicatesFn, runTicketLinkListFn, runTicketLinkFn });
       return jsonRpcResult(id, result);
     } catch (err) {
       return jsonRpcError(id ?? null, -32603, `Internal error: ${err.message}`);
@@ -302,6 +343,8 @@ export function runMcpServer({
   runTicketTransitionFn = runTicketTransition,
   runTicketAssignFn = runTicketAssign,
   runTicketDuplicatesFn = runTicketDuplicates,
+  runTicketLinkListFn = runTicketLinkList,
+  runTicketLinkFn = runTicketLink,
 } = {}) {
   // A client can disconnect mid-write (EPIPE) at any time on a long-lived
   // process — an unhandled 'error' event on either stream would otherwise
@@ -321,7 +364,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, runTicketCommentFn, runTicketTransitionListFn, runTicketTransitionFn, runTicketAssignFn, runTicketDuplicatesFn });
+      const response = await handleMessage(line, { configDir, runNoteAddFn, runRecallFn, runTicketCommentFn, runTicketTransitionListFn, runTicketTransitionFn, runTicketAssignFn, runTicketDuplicatesFn, runTicketLinkListFn, runTicketLinkFn });
       if (response) stdout.write(response);
     }).catch(() => {});
   });

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

@@ -68,26 +68,35 @@ function formatWriteFailure(ticketKey, err) {
  * Read-path counterpart to formatWriteFailure — reuses the same
  * classification (rate-limit/timeout/server-error metadata is real and
  * worth keeping, not specific to writes) but with read-appropriate wording,
- * since "duplicates" never writes anything.
+ * parameterized by what's being checked (e.g. "for duplicates", "for link
+ * options") since neither duplicates nor link-list ever writes anything.
  */
-function formatDuplicatesFailure(ticketKey, err) {
+function formatReadFailure(ticketKey, err, actionPhrase) {
   const classification = classifyWriteFailure(err);
   switch (classification.kind) {
     case 'rate-limited': {
       const wait = classification.detail.retryAfterSeconds ?? null;
       return wait
-        ? `  Rate limited by the tracker — retry checking ${ticketKey} after ~${wait}s.\n`
-        : `  Rate limited by the tracker — try checking ${ticketKey} again later.\n`;
+        ? `  Rate limited by the tracker — retry checking ${ticketKey} ${actionPhrase} after ~${wait}s.\n`
+        : `  Rate limited by the tracker — try checking ${ticketKey} ${actionPhrase} again later.\n`;
     }
     case 'network-or-timeout':
-      return `  Network error or timeout checking ${ticketKey} for duplicates. Try again.\n`;
+      return `  Network error or timeout checking ${ticketKey} ${actionPhrase}. Try again.\n`;
     case 'server-error':
-      return `  Tracker returned a server error (${classification.status}) checking ${ticketKey} for duplicates. Try again later.\n`;
+      return `  Tracker returned a server error (${classification.status}) checking ${ticketKey} ${actionPhrase}. Try again later.\n`;
     default:
-      return `  Error checking ${ticketKey} for duplicates: ${err.message}\n`;
+      return `  Error checking ${ticketKey} ${actionPhrase}: ${err.message}\n`;
   }
 }
 
+function formatDuplicatesFailure(ticketKey, err) {
+  return formatReadFailure(ticketKey, err, 'for duplicates');
+}
+
+function formatLinkListFailure(ticketKey, err) {
+  return formatReadFailure(ticketKey, err, 'for link options');
+}
+
 function requireLicense(isLicensedFn, configDir, commandName, stream) {
   if (isLicensedFn('pro', configDir)) return true;
   showUpgradePrompt('pro', commandName, { stream });
@@ -368,3 +377,131 @@ export async function runTicketDuplicates(cmdArgs, {
     return { ok: false };
   }
 }
+
+/**
+ * Discovery only — never mutates. Lists the tracker's current available
+ * link types for sourceKey→targetKey. Jira's list is always fetched live
+ * (per-instance customizable — never cached, same principle as
+ * getTransitions). GitHub's "list" is really a single-item warning: its
+ * only link action closes sourceKey as a duplicate of targetKey, a
+ * materially louder operation than Jira/Linear's pure relationship-add,
+ * so that asymmetry is surfaced here before a caller ever reaches --confirm.
+ *
+ * @param {string[]} cmdArgs - [sourceKey, targetKey]
+ * @returns {Promise<{ ok: boolean, types?: string[] }>}
+ */
+export async function runTicketLinkList(cmdArgs, {
+  configDir = DEFAULT_CONFIG_DIR,
+  stream = process.stderr,
+  isLicensedFn = isLicensed,
+  resolveConnectionFn = resolveConnection,
+  resolveAdapterFn = resolveAdapter,
+} = {}) {
+  const usage = 'Usage: ticketlens link SOURCE-KEY TARGET-KEY [--type="..." --confirm]\n';
+  if (!requireLicense(isLicensedFn, configDir, 'ticketlens link', stream)) return { ok: false };
+
+  const sourceKey = requireTicketKey(cmdArgs, usage, stream);
+  if (!sourceKey) return { ok: false };
+  const targetKey = requireTicketKey(cmdArgs.slice(1), usage, stream);
+  if (!targetKey) return { ok: false };
+
+  const adapter = resolveTicketAdapter(sourceKey, cmdArgs, { configDir, resolveConnectionFn, resolveAdapterFn, stream });
+  if (!adapter) return { ok: false };
+
+  try {
+    const types = await adapter.getLinkTypes();
+    if (types.length === 0) {
+      stream.write(`  No link types available for ${sourceKey} → ${targetKey} on ${adapter.type}.\n`);
+      return { ok: true, types: [] };
+    }
+    stream.write(`  Available link types for ${sourceKey} → ${targetKey} (${adapter.type}):\n`);
+    for (const t of types) stream.write(`    - ${t}\n`);
+    if (adapter.type === 'github') {
+      stream.write(`  Note: GitHub has no generic link relationship — linking will CLOSE ${sourceKey} as a duplicate of ${targetKey}.\n`);
+    }
+    stream.write(`  Run again with --type="<name>" --confirm to execute — ${sourceKey} will be recorded as the one that "types" ${targetKey}.\n`);
+    return { ok: true, types };
+  } catch (err) {
+    stream.write(formatLinkListFailure(sourceKey, err));
+    return { ok: false };
+  }
+}
+
+/**
+ * Executes a link. Requires both --type and --confirm — a type without
+ * confirm is incomplete input, never silently executed. Cooldown is keyed
+ * on the source:target pair (not sourceKey alone) so a second link to a
+ * different target isn't blocked by the debounce window; the audit log
+ * keeps ticketKey as the single valid sourceKey (logAction throws on
+ * anything else) with targetKey/type carried in detail instead.
+ *
+ * @param {string[]} cmdArgs - [sourceKey, targetKey, '--type=...', '--confirm']
+ * @returns {Promise<{ ok: boolean, reason?: string }>}
+ */
+export async function runTicketLink(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 link SOURCE-KEY TARGET-KEY --type="..." --confirm\n';
+  if (!requireLicense(isLicensedFn, configDir, 'ticketlens link', stream)) return { ok: false };
+
+  const sourceKey = requireTicketKey(cmdArgs, usage, stream);
+  if (!sourceKey) return { ok: false };
+  const targetKey = requireTicketKey(cmdArgs.slice(1), usage, stream);
+  if (!targetKey) return { ok: false };
+
+  const type = parseFlag(cmdArgs, 'type');
+  if (!type) {
+    stream.write(usage);
+    return { ok: false };
+  }
+  if (!cmdArgs.includes('--confirm')) {
+    stream.write(`  Refusing to link ${sourceKey} to ${targetKey} as "${type}" without --confirm. Re-run with --confirm once you've reviewed the target.\n`);
+    return { ok: false };
+  }
+
+  const cooldownKey = `${sourceKey}:${targetKey}`;
+  const cooldown = checkCooldownFn(cooldownKey, 'link', { configDir });
+  if (cooldown.active) {
+    stream.write(`  Skipped — ${sourceKey} was already linked to ${targetKey} ${Math.ceil(cooldown.remainingMs / 1000)}s ago. Wait a moment before retrying.\n`);
+    return { ok: false };
+  }
+
+  const adapter = resolveTicketAdapter(sourceKey, cmdArgs, { configDir, resolveConnectionFn, resolveAdapterFn, stream });
+  if (!adapter) return { ok: false };
+
+  if (adapter.type === 'github' && type.toLowerCase() !== 'duplicate') {
+    stream.write(`  GitHub only supports linking as a duplicate — no generic link types. Got type "${type}".\n`);
+    return { ok: false };
+  }
+  if (adapter.type === 'github') {
+    stream.write(`  Note: this will CLOSE ${sourceKey} as a duplicate of ${targetKey} on GitHub.\n`);
+  }
+
+  try {
+    const result = await adapter.linkTo(sourceKey, targetKey, type);
+    if (!result.executed) {
+      const optionsHint = result.options?.length ? ` Valid options: ${result.options.join(', ')}.` : '';
+      stream.write(`  Not linked — ${result.reason}.${optionsHint}\n`);
+      return { ok: false, reason: result.reason };
+    }
+    recordActionFn(cooldownKey, 'link', { configDir });
+    logActionFn({ ticketKey: sourceKey, action: 'link', actor, tracker: adapter.type, detail: { targetKey, type } }, { configDir });
+    stream.write(
+      adapter.type === 'github'
+        ? `  ${sourceKey} closed as a duplicate of ${targetKey}.\n`
+        : `  ${sourceKey} linked to ${targetKey} as "${type}".\n`,
+    );
+    return { ok: true };
+  } catch (err) {
+    stream.write(formatWriteFailure(sourceKey, err));
+    return { ok: false };
+  }
+}