ticketlens 0.25.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`, and `ticket_assign` as native tools — any MCP-compatible AI assistant, not just Claude Code, can call them directly instead of constructing a shell command. It's a thin adapter over the exact same code as the CLI commands above — same Pro gate, same secret scan/local vault/tracker writes, same team sync — nothing is reimplemented. Point your harness's MCP config at it: `{ "command": "ticketlens", "args": ["mcp"] }` — or run `ticketlens mcp install` in a project to write that entry into its `.mcp.json` for you (creates the file if it doesn't exist, merges in if it does — never touches any other entry already there; `--dry-run` to preview first).
+**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,22 +419,29 @@ Every note is scanned before saving — anything shaped like a real secret (API
 
 ---
 
-### Comment, Transition & Assign
+### Comment, Transition, Assign, Duplicates & Link
 
 ```bash
 ticketlens comment PROJ-123 --body="Looks good, merging."   # Post a comment to the tracker
 ticketlens transition PROJ-123                              # List valid transitions (read-only)
 ticketlens transition PROJ-123 --target="Done" --confirm    # Execute the transition
 ticketlens assign PROJ-123 --to=me                           # Assign the ticket to yourself
+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` 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.
 
 `ticketlens assign` is self-assign only for now — `--to` must be `me`. Assigning to someone else needs a per-tracker user-lookup step this doesn't do yet, so it's deliberately out of scope until that's built.
 
-All three actions have a short local debounce (10s) against an accidental double-fire (a flaky retry, hitting enter twice), and every successful write is appended to a local, append-only audit log (`~/.ticketlens/ticket-action-log.jsonl`). A write that times out is never retried automatically — unlike Recall notes, ticket writes aren't naturally idempotent, so a timed-out attempt is surfaced to you instead of silently repeated.
+`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.
+
+`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.
 
 ---
 
@@ -715,11 +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 ─────────────────────────────────────────────
+# ── 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
@@ -805,6 +816,8 @@ ticketlens mcp                           # Start the MCP stdio server (recall/ti
 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,
+  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';
@@ -778,6 +778,34 @@ switch (command) {
     break;
   }
 
+  case 'duplicates': {
+    if (cmdArgs.includes('--help') || cmdArgs.includes('-h')) { printDuplicatesHelp(); break; }
+    const { runTicketDuplicates } = await import('../skills/jtb/scripts/lib/ticket-command.mjs');
+    runTicketDuplicates(cmdArgs).then(({ ok }) => {
+      if (!ok) process.exitCode = 1;
+    }).catch(err => {
+      process.stderr.write(`Error: ${err.message}\n`);
+      process.exitCode = 1;
+    });
+    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.25.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": {
@@ -17,7 +17,7 @@
     "skills/jtb/scripts/fetch-my-tickets.mjs"
   ],
   "scripts": {
-    "test": "node --test skills/jtb/scripts/test/*.test.mjs",
+    "test": "node --test 'skills/jtb/scripts/test/**/*.test.mjs'",
     "postinstall": "node scripts/postinstall.mjs",
     "prepublishOnly": "node scripts/preflight.mjs",
     "publish:beta": "node scripts/publish.mjs --tag=beta",

package/skills/jtb/SKILL.md

@@ -1,4 +1,4 @@
-<!-- jtb-skill-version: 0.25.0 -->
+<!-- jtb-skill-version: 0.26.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.
@@ -264,26 +264,29 @@ Recall notes are stored locally at `~/.ticketlens/recall/`. On a Pro account wit
 
 ---
 
-## Comment, Transition & Assign — write back to the tracker (Pro)
+## Comment, Transition, Assign & Duplicates — write back to the tracker (Pro)
 
-Unlike Recall (a local note about a ticket), these write directly to the ticket's real tracker — Jira, GitHub, or Linear. Only dispatch when the user has actually asked for the ticket to be commented on, moved, or assigned — never as a routine end-of-session action the way Recall capture is.
+Unlike Recall (a local note about a ticket), comment/transition/assign write directly to the ticket's real tracker — Jira, GitHub, or Linear. Only dispatch a write when the user has actually asked for the ticket to be commented on, moved, or assigned — never as a routine end-of-session action the way Recall capture is. `duplicates` is read-only and safe to run more freely — it never mutates anything.
 
 ```bash
 ticketlens comment PROD-1234 --body="Fixed in a2f9c1, deployed to staging."
 ticketlens transition PROD-1234                              # list valid transitions — read-only
 ticketlens transition PROD-1234 --target="Done" --confirm    # execute
 ticketlens assign PROD-1234 --to=me                          # assign to yourself
+ticketlens duplicates PROD-1234                               # find likely duplicates — read-only
 ```
 
 `transition` called with just a ticket key never mutates anything — it lists the tracker's current valid options (Jira: real workflow transitions for that issue; GitHub: open/closed; Linear: team-scoped workflow states). Only add `--target` **and** `--confirm` once the target has actually been confirmed with the user — `--confirm` is a deliberate two-step gate, not a formality to route around. Never guess a `--target` value; always list first, then use one of the names shown.
 
 `assign` is self-assign only — `--to` must be `me`. There is no way to assign to anyone else yet; don't attempt a workaround (e.g. via `comment`) if the user asks for that — tell them it isn't supported.
 
-All three actions have a short local debounce (10s) against an accidental double-fire, and every write is appended to a local audit log (`~/.ticketlens/ticket-action-log.jsonl`). A write that times out is never retried automatically — surface the failure to the user rather than silently re-attempting, since a ticket write isn't naturally idempotent the way a Recall note save is.
+`duplicates` lists likely-duplicate tickets in the same project, ranked by local title/description overlap — no tracker scores similarity server-side, so treat a match as a nudge for the user to check manually, never as a confirmed duplicate to act on unprompted (e.g. don't auto-close or auto-comment based on a match). `--threshold=N` (0–1, default 0.35) tightens or loosens what counts as a match.
 
-**Pick exactly one path per action — never both.** If this harness has TicketLens's MCP server configured (`ticketlens mcp` — `ticket_comment`/`ticket_transition`/`ticket_assign` as native tools, see `ticketlens mcp --help`), prefer calling those tools directly over the bash commands above — same license gate, same cooldown, same audit log. Fall back to the bash form only when the MCP tools aren't available.
+The three write actions (comment/transition/assign) 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. `duplicates` has neither, since nothing is written.
 
-Requires a Pro license — on Free, all three no-op with an upgrade hint on stderr.
+**Pick exactly one path per action — never both.** If this harness has TicketLens's MCP server configured (`ticketlens mcp` — `ticket_comment`/`ticket_transition`/`ticket_assign`/`ticket_duplicates` as native tools, see `ticketlens mcp --help`), prefer calling those tools directly over the bash commands above — same license gate, same cooldown, same audit log. Fall back to the bash form only when the MCP tools aren't available.
+
+Requires a Pro license — on Free, all four no-op with an upgrade hint on stderr.
 
 ---
 

package/skills/jtb/scripts/fetch-my-tickets.mjs

@@ -10,6 +10,7 @@ import { assembleTriageSummary } from './lib/brief-assembler.mjs';
 import { styleTriageSummary } from './lib/styled-assembler.mjs';
 import { resolveConnection, loadProfiles, saveProfile } from './lib/profile-resolver.mjs';
 import { resolveAdapter } from './lib/resolve-adapter.mjs';
+import { escapeJql } from './lib/jira-client.mjs';
 import { incrementTriageRun, readAndResetActivity } from './lib/activity-counter.mjs';
 import { DEFAULT_CONFIG_DIR } from './lib/config.mjs';
 import { writeFileSync, mkdirSync, statSync } from 'node:fs';
@@ -42,10 +43,6 @@ async function defaultDigestDeliverer(payload, { cliToken } = {}) {
   return true;
 }
 
-function escapeJql(s) {
-  return s.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
-}
-
 export async function run(args, envOrOpts = process.env, fetcher = globalThis.fetch, configDir = undefined) {
   // Support both legacy positional form run(args, env, fetcher, configDir)
   // and new opts-object form run(args, { env, fetcher, configDir, exporter, isLicensed, showUpgradePrompt, print })

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

@@ -1,3 +1,5 @@
+import { tokenize } from '../duplicate-scorer.mjs';
+
 /**
  * Parses owner and repo from a GitHub profile baseUrl.
  * Expected format: https://github.com/OWNER/REPO
@@ -27,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,
@@ -208,5 +211,66 @@ export function createGitHubAdapter(conn, { fetcher = globalThis.fetch } = {}) {
       if (!res.ok) await throwGitHubWriteError(res, 'assigning', key);
       return { assignee: me.displayName ?? me.login };
     },
+
+    /**
+     * Candidate search for duplicate-ticket detection via GitHub's search
+     * endpoint (distinct from the issues-list endpoint `searchTickets` uses,
+     * which hardcodes "assigned to me" and ignores its query argument).
+     * Excludes the source issue and returns unranked candidates —
+     * duplicate-scorer.mjs does the actual similarity ranking.
+     *
+     * Never interpolates raw ticket text into `q` — GitHub parses the
+     * decoded query with its own qualifier grammar (`repo:`, `org:`, `is:`,
+     * etc, space-delimited), and multiple `repo:`/`org:` qualifiers are
+     * OR'd together. A crafted title/description containing e.g.
+     * `repo:otherorg/private-repo` would widen the search to a repo outside
+     * this profile's scope — a confused-deputy query-injection, not just a
+     * cosmetic bug. tokenize() strips all non-letter/digit characters
+     * (including `:`), so no qualifier syntax survives into `q`, and its
+     * cap keeps the query well under GitHub's search length limit.
+     */
+    async findCandidates(text, sourceKey, opts = {}) {
+      const sourceNumber = parseInt(sourceKey.split('-').pop(), 10);
+      const terms = tokenize(text).slice(0, 8).join(' ');
+      const q = `repo:${owner}/${repo} is:issue ${terms}`;
+      const url = `${GITHUB_API}/search/issues?q=${encodeURIComponent(q)}`;
+      const res = await fetcher(url, { headers, signal: AbortSignal.timeout(opts.timeoutMs ?? 10_000) });
+      if (!res.ok) await throwGitHubWriteError(res, 'searching', sourceKey);
+      const raw = await res.json();
+      return raw.items
+        .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 } 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';
 
 /**
@@ -7,6 +7,8 @@ import { buildJiraEnv } from '../config.mjs';
  * trusts a caller-supplied id without confirming it's still a real,
  * currently-valid option for this exact issue right now.
  */
+const SEARCH_TEXT_CHAR_LIMIT = 300;
+
 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);
@@ -64,5 +66,49 @@ export function createJiraAdapter(conn, { fetcher = globalThis.fetch } = {}) {
       await assignIssue(key, { [field]: value }, { ...base, ...opts });
       return { assignee: me.displayName ?? value };
     },
+
+    /**
+     * Candidate search for duplicate-ticket detection. Scoped to the same
+     * project as `sourceKey` (derived from its own prefix) and excludes it
+     * from results. Jira has no server-side similarity scoring — this only
+     * narrows the candidate pool; ranking happens in duplicate-scorer.mjs.
+     */
+    async findCandidates(text, sourceKey, opts = {}) {
+      const hyphenIndex = sourceKey.lastIndexOf('-');
+      if (hyphenIndex < 1) {
+        throw new Error(`Cannot derive a project key from "${sourceKey}" — expected PROJECT-123.`);
+      }
+      const project = sourceKey.slice(0, hyphenIndex);
+      const searchText = text.slice(0, SEARCH_TEXT_CHAR_LIMIT);
+      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

@@ -1,7 +1,12 @@
+import { tokenize } from '../duplicate-scorer.mjs';
+
 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
@@ -257,5 +262,79 @@ export function createLinearAdapter(conn, { fetcher = globalThis.fetch } = {}) {
       }
       return { assignee: me.displayName ?? me.id };
     },
+
+    /**
+     * Candidate search for duplicate-ticket detection. Linear's `contains`/
+     * `containsIgnoreCase` filters are literal substring matches, not
+     * full-text search (confirmed — Linear has no built-in similarity
+     * matching) — passing the whole source text as one substring filter
+     * would almost never match anything. Instead ORs across the
+     * significant tokens, ANDed with a team scope derived from the source
+     * key's prefix. Ranking happens in duplicate-scorer.mjs.
+     */
+    async findCandidates(text, sourceKey, opts = {}) {
+      const terms = tokenize(text).slice(0, 5);
+      if (terms.length === 0) return [];
+      const hyphenIndex = sourceKey.lastIndexOf('-');
+      if (hyphenIndex < 1) {
+        throw new Error(`Cannot derive a team key from "${sourceKey}" — expected TEAM-123.`);
+      }
+      const signal = AbortSignal.timeout(opts.timeoutMs ?? 10_000);
+      const prefix = sourceKey.slice(0, hyphenIndex);
+      const filter = {
+        team: { key: { eq: prefix } },
+        or: terms.map(term => ({ title: { containsIgnoreCase: term } })),
+      };
+      const data = await gql(
+        `query ($filter: IssueFilter) {
+          issues(filter: $filter, first: 50) {
+            nodes { ${ISSUE_FIELDS} }
+          }
+        }`,
+        { filter },
+        { token, fetcher, signal },
+      );
+      return (data.issues?.nodes ?? [])
+        .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

@@ -142,6 +142,14 @@ export function parseCommand(args) {
     return { command: 'assign', args: args.slice(1) };
   }
 
+  if (first === 'duplicates') {
+    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/duplicate-scorer.mjs

@@ -0,0 +1,69 @@
+/**
+ * Zero-dependency duplicate-ticket scoring. No tracker (Jira/GitHub/Linear)
+ * offers server-side similarity scoring — only exact/substring text filters —
+ * so candidate ranking happens here via Jaccard set overlap on tokenized text.
+ */
+
+const STOPWORDS = new Set([
+  'the', 'a', 'an', 'to', 'of', 'in', 'on', 'for', 'and', 'or', 'is', 'are',
+  'this', 'that', 'with', 'as', 'at', 'by', 'from', 'it', 'be', 'was', 'were',
+  'has', 'have', 'had', 'not', 'but', 'if', 'will', 'can', 'do', 'does',
+]);
+
+const TITLE_WEIGHT = 2;
+const DESCRIPTION_WEIGHT = 1;
+const DESCRIPTION_CHAR_LIMIT = 500;
+
+/**
+ * Lowercases, strips punctuation, drops stopwords and sub-2-char tokens,
+ * and de-duplicates. Returns a plain array (order not significant — callers
+ * treat it as a set).
+ */
+export function tokenize(text) {
+  if (!text) return [];
+  const words = text.toLowerCase().replace(/[^\p{L}\p{N}\s]/gu, ' ').split(/\s+/).filter(Boolean);
+  const seen = new Set();
+  for (const w of words) {
+    if (w.length >= 2 && !STOPWORDS.has(w)) seen.add(w);
+  }
+  return [...seen];
+}
+
+/**
+ * Intersection-over-union. Two empty sets are defined as 0 similarity, not 1 —
+ * an empty-vs-empty match is a lack of signal, not a confirmed duplicate.
+ */
+export function jaccardSimilarity(tokensA, tokensB) {
+  const setA = new Set(tokensA);
+  const setB = new Set(tokensB);
+  if (setA.size === 0 && setB.size === 0) return 0;
+  let intersection = 0;
+  for (const t of setA) {
+    if (setB.has(t)) intersection += 1;
+  }
+  const union = setA.size + setB.size - intersection;
+  return union === 0 ? 0 : intersection / union;
+}
+
+function weightedScore(source, candidate) {
+  const titleScore = jaccardSimilarity(tokenize(source.summary), tokenize(candidate.summary));
+  const descScore = jaccardSimilarity(
+    tokenize((source.description ?? '').slice(0, DESCRIPTION_CHAR_LIMIT)),
+    tokenize((candidate.description ?? '').slice(0, DESCRIPTION_CHAR_LIMIT)),
+  );
+  return (titleScore * TITLE_WEIGHT + descScore * DESCRIPTION_WEIGHT) / (TITLE_WEIGHT + DESCRIPTION_WEIGHT);
+}
+
+/**
+ * Ranks candidates against the source ticket, excludes the source itself
+ * (defense-in-depth — callers already exclude it at the query level) and
+ * anything below `threshold`, sorted highest score first, capped at `limit`.
+ */
+export function scoreCandidates(source, candidates, { threshold = 0.35, limit = 5 } = {}) {
+  return candidates
+    .filter(c => c.key !== source.key)
+    .map(c => ({ key: c.key, summary: c.summary, score: weightedScore(source, c) }))
+    .filter(c => c.score >= threshold)
+    .sort((a, b) => b.score - a.score)
+    .slice(0, limit);
+}

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

@@ -57,6 +57,8 @@ export function printHelp({ stream = process.stdout } = {}) {
     `    ${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')} 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`,
@@ -597,11 +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')} — 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')} 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_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')}`,
@@ -702,6 +706,65 @@ export function printAssignHelp({ stream = process.stdout } = {}) {
   stream.write(lines.join('\n') + '\n');
 }
 
+export function printDuplicatesHelp({ stream = process.stdout } = {}) {
+  const s = createStyler({ isTTY: stream.isTTY });
+  const lines = [
+    '',
+    `  ${s.bold(s.brand('ticketlens'))} ${s.bold('duplicates')} ${s.dim('TICKET-KEY [--threshold=0.35]')}  ${s.dim('[Pro]')}`,
+    '',
+    `  Find likely duplicate tickets in the same project (Jira/GitHub/Linear). ${s.dim('[Pro]')}`,
+    `  Read-only — lists possible matches, never links or changes anything.`,
+    `  No tracker scores similarity server-side, so ranking happens locally`,
+    `  from title/description overlap. Not exact — treat it as a nudge to check.`,
+    '',
+    `  ${s.bold('OPTIONS')}`,
+    '',
+    `    ${s.brand('--threshold')}=${s.dim('N')}   Minimum match score 0–1 to report ${s.dim('(default 0.35)')}`,
+    `    ${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 duplicates PROD-123`,
+    `    ${s.dim('$')} ticketlens duplicates PROD-123 --threshold=0.5`,
+    '',
+  ];
+  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

@@ -13,6 +13,14 @@ function toText(value) {
   return adfToText(value);
 }
 
+/**
+ * Escapes a value for safe interpolation into a double-quoted JQL string
+ * literal. Single source of truth — do not duplicate in callers.
+ */
+export function escapeJql(s) {
+  return s.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+}
+
 /**
  * Extracts the active sprint name from customfield_10020.
  * Cloud v3: array of sprint objects — prefers active, falls back to last.
@@ -494,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 } from './ticket-command.mjs';
+import { runTicketComment, runTicketTransitionList, runTicketTransition, runTicketAssign, runTicketDuplicates, runTicketLinkList, runTicketLink } from './ticket-command.mjs';
 
 const PROTOCOL_VERSION = '2025-11-25';
 
@@ -90,6 +90,32 @@ const TOOLS = [
       required: ['ticket', 'to'],
     },
   },
+  {
+    name: 'ticket_duplicates',
+    description: 'Find likely duplicate tickets in the same project (Jira/GitHub/Linear). Read-only — never links or changes anything; no tracker scores similarity server-side, so ranking is local and approximate. Requires a TicketLens Pro license.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        ticket: { type: 'string', description: 'Ticket key, e.g. PROJ-123.' },
+        threshold: { type: 'number', description: 'Minimum match score 0-1 to report. Defaults to 0.35.' },
+      },
+      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) {
@@ -209,6 +235,44 @@ async function callTicketAssign(args, { configDir, runTicketAssignFn }) {
   return ok ? { content } : { isError: true, content };
 }
 
+async function callTicketDuplicates(args, { configDir, runTicketDuplicatesFn }) {
+  if (!args.ticket) {
+    return { isError: true, content: [{ type: 'text', text: 'Missing required argument: ticket' }] };
+  }
+  const cmdArgs = [args.ticket];
+  if (args.threshold !== undefined) cmdArgs.push(`--threshold=${args.threshold}`);
+  const capture = capturingStream();
+  const { ok } = await runTicketDuplicatesFn(cmdArgs, { configDir, stream: capture });
+  const content = [{ type: 'text', text: capture.text }];
+  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);
@@ -216,10 +280,12 @@ async function handleToolsCall(params, deps) {
   if (name === 'ticket_comment') return callTicketComment(args, 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 }) {
+async function handleMessage(raw, { configDir, runNoteAddFn, runRecallFn, runTicketCommentFn, runTicketTransitionListFn, runTicketTransitionFn, runTicketAssignFn, runTicketDuplicatesFn, runTicketLinkListFn, runTicketLinkFn }) {
   let msg;
   try {
     msg = JSON.parse(raw);
@@ -249,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 });
+      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}`);
@@ -276,6 +342,9 @@ export function runMcpServer({
   runTicketTransitionListFn = runTicketTransitionList,
   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
@@ -295,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 });
+      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/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, addComment: Function, getTransitions: Function, transition: Function, assignToSelf: Function }}
+ * @returns {{ type: string, fetchTicket: Function, fetchCurrentUser: Function, searchTickets: Function, fetchStatuses: Function, addComment: Function, getTransitions: Function, transition: Function, assignToSelf: Function, findCandidates: Function }}
  */
 export function resolveAdapter(conn, opts = {}) {
   const type = detectTrackerType(conn?.baseUrl);

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

@@ -17,6 +17,7 @@ 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';
+import { scoreCandidates } from './duplicate-scorer.mjs';
 
 function parseFlag(cmdArgs, name) {
   return cmdArgs.find(a => a.startsWith(`--${name}=`))?.slice(name.length + 3);
@@ -63,6 +64,39 @@ 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,
+ * parameterized by what's being checked (e.g. "for duplicates", "for link
+ * options") since neither duplicates nor link-list ever writes anything.
+ */
+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} ${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} ${actionPhrase}. Try again.\n`;
+    case 'server-error':
+      return `  Tracker returned a server error (${classification.status}) checking ${ticketKey} ${actionPhrase}. Try again later.\n`;
+    default:
+      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 });
@@ -288,3 +322,186 @@ export async function runTicketAssign(cmdArgs, {
     return { ok: false };
   }
 }
+
+/**
+ * Read-only — no cooldown, no action-log entry. Nothing is mutated, so
+ * there's nothing to debounce or audit, unlike comment/transition/assign.
+ *
+ * @param {string[]} cmdArgs - [ticketKey, ...flags], e.g. ["PROJ-1", '--threshold=0.4']
+ * @returns {Promise<{ ok: boolean, results?: Array<{key: string, summary: string, score: number}> }>}
+ */
+export async function runTicketDuplicates(cmdArgs, {
+  configDir = DEFAULT_CONFIG_DIR,
+  stream = process.stderr,
+  isLicensedFn = isLicensed,
+  resolveConnectionFn = resolveConnection,
+  resolveAdapterFn = resolveAdapter,
+} = {}) {
+  const usage = 'Usage: ticketlens duplicates TICKET-KEY [--threshold=0.35]\n';
+  if (!requireLicense(isLicensedFn, configDir, 'ticketlens duplicates', stream)) return { ok: false };
+
+  const ticketKey = requireTicketKey(cmdArgs, usage, stream);
+  if (!ticketKey) return { ok: false };
+
+  const thresholdArg = parseFlag(cmdArgs, 'threshold');
+  let threshold;
+  if (thresholdArg !== undefined) {
+    threshold = Number(thresholdArg);
+    if (Number.isNaN(threshold) || threshold < 0 || threshold > 1) {
+      stream.write(`  --threshold must be a number between 0 and 1 (got "${thresholdArg}").\n`);
+      return { ok: false };
+    }
+  }
+
+  const adapter = resolveTicketAdapter(ticketKey, cmdArgs, { configDir, resolveConnectionFn, resolveAdapterFn, stream });
+  if (!adapter) return { ok: false };
+
+  try {
+    const source = await adapter.fetchTicket(ticketKey);
+    const searchText = [source.summary, source.description].filter(Boolean).join(' ');
+    const candidates = await adapter.findCandidates(searchText, ticketKey);
+    const scoreOpts = threshold !== undefined ? { threshold } : {};
+    const results = scoreCandidates({ key: ticketKey, summary: source.summary, description: source.description }, candidates, scoreOpts);
+
+    if (results.length === 0) {
+      stream.write(`  No likely duplicates found for ${ticketKey}.\n`);
+      return { ok: true, results: [] };
+    }
+    stream.write(`  Possible duplicates of ${ticketKey}:\n`);
+    for (const r of results) {
+      stream.write(`    ${r.key} (${Math.round(r.score * 100)}% match) — ${r.summary}\n`);
+    }
+    return { ok: true, results };
+  } catch (err) {
+    stream.write(formatDuplicatesFailure(ticketKey, err));
+    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 };
+  }
+}