ticketlens 0.25.0 → 0.26.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`, 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).
 
 `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,25 @@ Every note is scanned before saving — anything shaped like a real secret (API
 
 ---
 
-### Comment, Transition & Assign
+### Comment, Transition, Assign & Duplicates
 
 ```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)
 ```
 
-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` 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.
+
+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.
 
 ---
 
@@ -715,11 +718,13 @@ 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 ────────────────────────────────────
 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]
 
 # ── Stats ──────────────────────────────────────────────────────────────────────
 ticketlens stats                              # Response-time metrics from local history
@@ -805,6 +810,7 @@ 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 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,
 } 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,18 @@ 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 '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.26.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
@@ -208,5 +210,35 @@ 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));
+    },
   };
 }

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

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

@@ -1,3 +1,5 @@
+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' };
@@ -257,5 +259,41 @@ 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);
+    },
   };
 }

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

@@ -142,6 +142,10 @@ export function parseCommand(args) {
     return { command: 'assign', args: args.slice(1) };
   }
 
+  if (first === 'duplicates') {
+    return { command: 'duplicates', 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,7 @@ 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')} delete ${s.dim('<PROFILE-NAME>')}       Remove a profile`,
     `    ${s.brand('ticketlens')} activate ${s.dim('<KEY>')}              Activate a license key`,
@@ -597,11 +598,12 @@ 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')} — 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.`,
     `  Long-running — exits when the client closes stdin.`,
     '',
     `  ${s.bold('OPTIONS')}`,
@@ -702,6 +704,32 @@ 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 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.

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 } from './ticket-command.mjs';
 
 const PROTOCOL_VERSION = '2025-11-25';
 
@@ -90,6 +90,18 @@ 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'],
+    },
+  },
 ];
 
 function jsonRpcResult(id, result) {
@@ -209,6 +221,18 @@ 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 };
+}
+
 async function handleToolsCall(params, deps) {
   const { name, arguments: args = {} } = params ?? {};
   if (name === 'recall_add') return callRecallAdd(args, deps);
@@ -216,10 +240,11 @@ 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);
   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 }) {
   let msg;
   try {
     msg = JSON.parse(raw);
@@ -249,7 +274,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 });
       return jsonRpcResult(id, result);
     } catch (err) {
       return jsonRpcError(id ?? null, -32603, `Internal error: ${err.message}`);
@@ -276,6 +301,7 @@ export function runMcpServer({
   runTicketTransitionListFn = runTicketTransitionList,
   runTicketTransitionFn = runTicketTransition,
   runTicketAssignFn = runTicketAssign,
+  runTicketDuplicatesFn = runTicketDuplicates,
 } = {}) {
   // 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 +321,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 });
       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,30 @@ 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.
+ */
+function formatDuplicatesFailure(ticketKey, err) {
+  const classification = classifyWriteFailure(err);
+  switch (classification.kind) {
+    case 'rate-limited': {
+      const wait = classification.detail.retryAfterSeconds ?? null;
+      return wait
+        ? `  Rate limited by the tracker — retry checking ${ticketKey} after ~${wait}s.\n`
+        : `  Rate limited by the tracker — try checking ${ticketKey} again later.\n`;
+    }
+    case 'network-or-timeout':
+      return `  Network error or timeout checking ${ticketKey} for duplicates. Try again.\n`;
+    case 'server-error':
+      return `  Tracker returned a server error (${classification.status}) checking ${ticketKey} for duplicates. Try again later.\n`;
+    default:
+      return `  Error checking ${ticketKey} for duplicates: ${err.message}\n`;
+  }
+}
+
 function requireLicense(isLicensedFn, configDir, commandName, stream) {
   if (isLicensedFn('pro', configDir)) return true;
   showUpgradePrompt('pro', commandName, { stream });
@@ -288,3 +313,58 @@ 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 };
+  }
+}