ticketlens 0.26.0 → 0.30.0

package/README.md

@@ -411,7 +411,7 @@ Every note is scanned before saving — anything shaped like a real secret (API
 
 **Removing a note:** `ticketlens note delete --id="..." [--ticket=KEY]` removes a note from your local vault. Local only — if it was already pushed to a team, teammates who pulled it keep their copy; deleting it there too is a manager action from the Console (Admin > Recall).
 
-**Any MCP-capable AI harness:** `ticketlens mcp` starts a stdio [MCP](https://modelcontextprotocol.io) server exposing `recall_add`, `recall_search`, `ticket_comment`, `ticket_transition`, `ticket_assign`, and `ticket_duplicates` as native tools — any MCP-compatible AI assistant, not just Claude Code, can call them directly instead of constructing a shell command. It's a thin adapter over the exact same code as the CLI commands above — same Pro gate, same secret scan/local vault/tracker writes, same team sync — nothing is reimplemented. Point your harness's MCP config at it: `{ "command": "ticketlens", "args": ["mcp"] }` — or run `ticketlens mcp install` in a project to write that entry into its `.mcp.json` for you (creates the file if it doesn't exist, merges in if it does — never touches any other entry already there; `--dry-run` to preview first).
+**Any MCP-capable AI harness:** `ticketlens mcp` starts a stdio [MCP](https://modelcontextprotocol.io) server exposing `recall_add`, `recall_search`, `ticket_comment`, `ticket_transition`, `ticket_assign`, `ticket_duplicates`, `ticket_link`, `ticket_update`, and `ticket_create` as native tools — any MCP-compatible AI assistant, not just Claude Code, can call them directly instead of constructing a shell command. It's a thin adapter over the exact same code as the CLI commands above — same Pro gate, same secret scan/local vault/tracker writes, same team sync — nothing is reimplemented. Point your harness's MCP config at it: `{ "command": "ticketlens", "args": ["mcp"] }` — or run `ticketlens mcp install` in a project to write that entry into its `.mcp.json` for you (creates the file if it doesn't exist, merges in if it does — never touches any other entry already there; `--dry-run` to preview first).
 
 `note add`'s save confirmation and `recall`'s search results are styled by default in a terminal; add `--plain` to either for bare, pipe-safe output. `recall` always shows each note's file ID (e.g. `[1784135399545-fe01c4.md]`) so you can open it directly (`cat ~/.ticketlens/recall/<PREFIX>/<id>`), or pass `--full` to print the full body content inline instead.
 
@@ -419,7 +419,7 @@ Every note is scanned before saving — anything shaped like a real secret (API
 
 ---
 
-### Comment, Transition, Assign & Duplicates
+### Comment, Transition, Assign, Duplicates, Link, Update & Create
 
 ```bash
 ticketlens comment PROJ-123 --body="Looks good, merging."   # Post a comment to the tracker
@@ -427,9 +427,15 @@ ticketlens transition PROJ-123                              # List valid transit
 ticketlens transition PROJ-123 --target="Done" --confirm    # Execute the transition
 ticketlens assign PROJ-123 --to=me                           # Assign the ticket to yourself
 ticketlens duplicates PROJ-123                                # Find likely duplicates (read-only)
+ticketlens link PROJ-123 PROJ-456                             # List valid link types (read-only)
+ticketlens link PROJ-123 PROJ-456 --type="Duplicate" --confirm  # Execute the link
+ticketlens update PROJ-123 --title="Fix login on mobile"       # Update title/description/labels/priority
+ticketlens update PROJ-123 --add-labels=urgent,backend --remove-labels=stale
+ticketlens create --project=PROJ --type="Task" --summary="Fix login on mobile"  # Create a new ticket
+ticketlens create --project=ENG --summary="New Linear issue" --profile=linear-team
 ```
 
-Write directly to the ticket in its real tracker — Jira, GitHub, or Linear — from your terminal or an AI session via `ticket_comment`/`ticket_transition`/`ticket_assign`/`ticket_duplicates` MCP tools. Requires a Pro license.
+Write directly to the ticket in its real tracker — Jira, GitHub, or Linear — from your terminal or an AI session via `ticket_comment`/`ticket_transition`/`ticket_assign`/`ticket_duplicates`/`ticket_link`/`ticket_update`/`ticket_create` MCP tools. Requires a Pro license.
 
 `ticketlens transition` with just a ticket key lists the tracker's current valid options without changing anything (Jira: real workflow transitions for that issue; GitHub: open/closed; Linear: team-scoped workflow states). Add both `--target` and `--confirm` to execute — `--confirm` is a deliberate two-step gate: a behavioral nudge and forensic trail, not a hard security guarantee. Every write, once resolved, is re-validated against the tracker's current state immediately before executing — never a blind write against a stale option.
 
@@ -437,7 +443,15 @@ Write directly to the ticket in its real tracker — Jira, GitHub, or Linear —
 
 `ticketlens duplicates` is read-only — it never links or changes anything, just lists likely matches in the same project. No tracker (Jira/GitHub/Linear) scores similarity server-side, so ranking happens locally from title/description word overlap; treat a match as a nudge to check manually, not a verdict. `--threshold=N` (0–1, default 0.35) controls how loose a match counts.
 
-All three write actions (comment/transition/assign) have a short local debounce (10s) against an accidental double-fire (a flaky retry, hitting enter twice), and every successful write is appended to a local, append-only audit log (`~/.ticketlens/ticket-action-log.jsonl`). A write that times out is never retried automatically — unlike Recall notes, ticket writes aren't naturally idempotent, so a timed-out attempt is surfaced to you instead of silently repeated. `duplicates` has neither, since nothing is written.
+`ticketlens link SOURCE-KEY TARGET-KEY` links two tickets — direction matters: SOURCE "types" TARGET (e.g. `link A B --type=Duplicate` means A duplicates B, not the other way around). With just the two keys it lists the tracker's current valid link types without changing anything — always fetched live for Jira, since link type names are per-instance configurable there. GitHub is different from Jira/Linear: it has no generic link relationship, so linking on a GitHub-tracked ticket *closes SOURCE as a duplicate of TARGET* — a state change, not just a relationship add — and prints an explicit warning immediately before that happens, on top of the same `--confirm` gate.
+
+`ticketlens update TICKET-KEY` updates a narrow, named field set — title, description, labels, priority. At least one field is required. Labels are always add/remove (`--add-labels=a,b` / `--remove-labels=c`), never a wholesale replace — an unnamed existing label is left alone, never silently dropped. No `--confirm` needed: unlike transition/link, update has no discovery step and only makes reversible metadata edits, the same risk tier as `assign`. GitHub has no priority field on issues, so `--priority` against a GitHub-tracked ticket is refused up front. Each tracker's label mechanics genuinely differ — Jira and Linear apply everything in one atomic call; GitHub's title/description and each label operation are independent, so a call can partially succeed (e.g. the title updates but one label name doesn't resolve) — the result always reports exactly which fields landed.
+
+`ticketlens create` creates a new ticket with a fixed minimal field set — no arbitrary custom fields. Unlike every other write command, there's no existing ticket to target, so `--profile` (or your default profile) picks the tracker instead of a ticket key. `--project` is the Jira project key or Linear team key — required for both, ignored on GitHub since its target repo is already fixed by the profile. `--type` is Jira's issue type (e.g. `"Task"`, `"Bug"`) — required for Jira, ignored elsewhere. No `--confirm` gate, same risk tier as `update`/`assign` — but this is the highest-blast-radius command in the whole family: a bad `--project`/`--type` fabricates a real, hard-to-walk-back item in a live tracker, so an invalid value surfaces the tracker's own error rather than a silent guess.
+
+**A bad `--project`/`--type` gets a better error, automatically.** If create fails because the project or issue type doesn't exist, TicketLens fetches your tracker's real, current project list (and, for Jira, the real issue types for that project) and shows them alongside the failure — e.g. `Known creatable projects: CNV1, ECNT.` — rather than a bare tracker error. This is reactive only: it never runs on a successful create, never auto-retries the write, and is cached locally per profile for 24h so a burst of failed attempts doesn't re-fetch every time.
+
+All six write actions (comment/transition/assign/link/update/create) have a short local debounce (10s) against an accidental double-fire (a flaky retry, hitting enter twice), and every successful write is appended to a local, append-only audit log (`~/.ticketlens/ticket-action-log.jsonl`). A write that times out is never retried automatically — unlike Recall notes, ticket writes aren't naturally idempotent, so a timed-out attempt is surfaced to you instead of silently repeated. `duplicates` has neither, since nothing is written.
 
 ---
 
@@ -718,13 +732,19 @@ ticketlens mcp                                # Start the MCP stdio server (reca
 ticketlens mcp install                        # Register it into the current project's .mcp.json
 ticketlens mcp install --dry-run              # Preview the registration without writing
 
-# ── Comment, Transition, Assign & Duplicates ────────────────────────────────────
+# ── Comment, Transition, Assign, Duplicates, Link, Update & Create ──────────────
 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]
+ticketlens update CNV1-2 --title="New title"                # Update title/description/labels/priority [Pro]
+ticketlens update CNV1-2 --add-labels=urgent --remove-labels=stale  # Add/remove labels [Pro]
+ticketlens create --project=CNV1 --type="Task" --summary="New ticket"  # Create a new ticket [Pro]
+ticketlens create --project=ENG --summary="New issue" --profile=linear-team  # Create on a different profile [Pro]
 
 # ── Stats ──────────────────────────────────────────────────────────────────────
 ticketlens stats                              # Response-time metrics from local history
@@ -811,6 +831,9 @@ 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 update CNV1-2 --title="..."   # Update title/description/labels/priority
+ticketlens create --project=CNV1 --type="Task" --summary="..."  # Create a new ticket
 ticketlens activate YOUR-LICENSE-KEY     # Activate Pro license
 ```
 

package/bin/ticketlens.mjs

@@ -18,7 +18,7 @@ import { activateLicense, checkLicense, revalidateIfStale, isLicensed, showUpgra
 import { deleteProfile, loadProfiles, saveCredentialKey } from '../skills/jtb/scripts/lib/profile-resolver.mjs';
 import { run as runCache } from '../skills/jtb/scripts/lib/cache-manager.mjs';
 import {
-  printHelp, printProfiles,
+  printHelp, printProfiles, printHistoryHelp,
   printLoginHelp, printLogoutHelp, printSyncHelp,
   printActivateHelp, printLicenseHelp, printDeleteHelp,
   printProfilesHelp, printScheduleHelp,
@@ -28,7 +28,7 @@ import {
   printCollisionsHelp, printStatsHelp,
   printCloudKeysHelp,
   printNoteHelp, printRecallHelp, printMcpHelp,
-  printCommentHelp, printTransitionHelp, printAssignHelp, printDuplicatesHelp,
+  printCommentHelp, printTransitionHelp, printAssignHelp, printDuplicatesHelp, printLinkHelp, printUpdateHelp, printCreateHelp,
 } 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';
@@ -134,6 +134,7 @@ switch (command) {
   }
 
   case 'history': {
+    if (cmdArgs.includes('--help') || cmdArgs.includes('-h')) { printHistoryHelp(); break; }
     if (!isLicensed('pro')) { showUpgradePrompt('pro', 'ticketlens history'); break; }
     const ticketKey = cmdArgs[0];
     if (!ticketKey || ticketKey.startsWith('-')) {
@@ -790,6 +791,46 @@ switch (command) {
     break;
   }
 
+  case 'link': {
+    if (cmdArgs.includes('--help') || cmdArgs.includes('-h')) { printLinkHelp(); break; }
+    const { runTicketLinkList, runTicketLink } = await import('../skills/jtb/scripts/lib/ticket-command.mjs');
+    // No --type → discovery only, never mutates. --type present → execute
+    // (runTicketLink itself still refuses without --confirm).
+    const hasType = cmdArgs.some(a => a.startsWith('--type='));
+    const runFn = hasType ? runTicketLink : runTicketLinkList;
+    runFn(cmdArgs).then(({ ok }) => {
+      if (!ok) process.exitCode = 1;
+    }).catch(err => {
+      process.stderr.write(`Error: ${err.message}\n`);
+      process.exitCode = 1;
+    });
+    break;
+  }
+
+  case 'update': {
+    if (cmdArgs.includes('--help') || cmdArgs.includes('-h')) { printUpdateHelp(); break; }
+    const { runTicketUpdate } = await import('../skills/jtb/scripts/lib/ticket-command.mjs');
+    runTicketUpdate(cmdArgs).then(({ ok }) => {
+      if (!ok) process.exitCode = 1;
+    }).catch(err => {
+      process.stderr.write(`Error: ${err.message}\n`);
+      process.exitCode = 1;
+    });
+    break;
+  }
+
+  case 'create': {
+    if (cmdArgs.includes('--help') || cmdArgs.includes('-h')) { printCreateHelp(); break; }
+    const { runTicketCreate } = await import('../skills/jtb/scripts/lib/ticket-command.mjs');
+    runTicketCreate(cmdArgs).then(({ ok }) => {
+      if (!ok) process.exitCode = 1;
+    }).catch(err => {
+      process.stderr.write(`Error: ${err.message}\n`);
+      process.exitCode = 1;
+    });
+    break;
+  }
+
   case 'help':
   default: {
     const isInteractive = args.length === 0 && process.stdin.isTTY && process.stdout.isTTY && !process.env.CI;

package/package.json

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

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

@@ -29,6 +29,7 @@ export function parseGitHubRepo(baseUrl) {
 export function normalizeGitHubIssue(raw, comments = [], keyPrefix = 'GH') {
   return {
     key: `${keyPrefix}-${raw.number}`,
+    id: raw.id,
     summary: raw.title,
     type: 'Issue',
     status: raw.state,
@@ -240,5 +241,134 @@ export function createGitHubAdapter(conn, { fetcher = globalThis.fetch } = {}) {
         .filter(item => item.number !== sourceNumber)
         .map(item => normalizeGitHubIssue(item, [], keyPrefix));
     },
+
+    /**
+     * GitHub has no generic link-type concept — "duplicate" (via closing
+     * the source issue) is the only relationship it supports natively.
+     */
+    async getLinkTypes() {
+      return ['duplicate'];
+    },
+
+    /**
+     * GitHub's only real "link" action closes sourceKey as a duplicate of
+     * targetKey — asymmetric and state-changing, unlike Jira/Linear's pure
+     * relationship-add. Resolves targetKey's internal id via fetchTicket
+     * (GitHub's duplicate_issue_id wants the internal id, not the
+     * repo-local number).
+     */
+    async linkTo(sourceKey, targetKey, typeName, opts = {}) {
+      if (typeName.toLowerCase() !== 'duplicate') {
+        throw new Error(`GitHub only supports linking as a duplicate — got type "${typeName}".`);
+      }
+      const target = await this.fetchTicket(targetKey, opts);
+      const sourceNumber = parseInt(sourceKey.split('-').pop(), 10);
+      const res = await fetcher(`${GITHUB_API}/repos/${owner}/${repo}/issues/${sourceNumber}`, {
+        method: 'PATCH',
+        headers: { ...headers, 'Content-Type': 'application/json' },
+        body: JSON.stringify({ state: 'closed', state_reason: 'duplicate', duplicate_issue_id: target.id }),
+        signal: AbortSignal.timeout(opts.timeoutMs ?? 10_000),
+      });
+      if (!res.ok) await throwGitHubWriteError(res, 'linking', sourceKey);
+      return { executed: true, closedAsDuplicateOf: targetKey };
+    },
+
+    /**
+     * Unlike Jira/Linear's single atomic mutation, GitHub genuinely has no
+     * one-call way to do this: title/description share a PATCH, but labels
+     * use their own dedicated additive (POST) and per-label (DELETE)
+     * endpoints — never the full-replace PUT, which would force an unsafe
+     * read-then-write race. Each operation is independent and best-effort:
+     * one failing must never prevent the others from being attempted, and
+     * the caller needs to know exactly which fields actually landed.
+     */
+    async updateFields(key, { title, description, priority, addLabels, removeLabels } = {}, opts = {}) {
+      if (priority !== undefined) {
+        throw new Error('GitHub Issues have no native priority field — cannot update priority.');
+      }
+      const number = parseInt(key.split('-').pop(), 10);
+      const signal = () => AbortSignal.timeout(opts.timeoutMs ?? 10_000);
+      const applied = {};
+      const errors = {};
+
+      if (title !== undefined || description !== undefined) {
+        try {
+          const body = {};
+          if (title !== undefined) body.title = title;
+          if (description !== undefined) body.body = description;
+          const res = await fetcher(`${GITHUB_API}/repos/${owner}/${repo}/issues/${number}`, {
+            method: 'PATCH',
+            headers: { ...headers, 'Content-Type': 'application/json' },
+            body: JSON.stringify(body),
+            signal: signal(),
+          });
+          if (!res.ok) await throwGitHubWriteError(res, 'updating', key);
+          if (title !== undefined) applied.title = true;
+          if (description !== undefined) applied.description = true;
+        } catch (err) {
+          if (title !== undefined) errors.title = err;
+          if (description !== undefined) errors.description = err;
+        }
+      }
+
+      if (addLabels?.length) {
+        try {
+          const res = await fetcher(`${GITHUB_API}/repos/${owner}/${repo}/issues/${number}/labels`, {
+            method: 'POST',
+            headers: { ...headers, 'Content-Type': 'application/json' },
+            body: JSON.stringify({ labels: addLabels }),
+            signal: signal(),
+          });
+          if (!res.ok) await throwGitHubWriteError(res, 'adding labels to', key);
+          applied.addLabels = addLabels;
+        } catch (err) {
+          errors.addLabels = err;
+        }
+      }
+
+      if (removeLabels?.length) {
+        const removed = [];
+        const removeErrors = {};
+        for (const label of removeLabels) {
+          try {
+            const res = await fetcher(`${GITHUB_API}/repos/${owner}/${repo}/issues/${number}/labels/${encodeURIComponent(label)}`, {
+              method: 'DELETE',
+              headers,
+              signal: signal(),
+            });
+            // A 404 here means the label was already absent — the caller's
+            // goal ("this label is gone") is already true, so this is
+            // treated as success, not a failure to surface.
+            if (!res.ok && res.status !== 404) await throwGitHubWriteError(res, 'removing a label from', key);
+            removed.push(label);
+          } catch (err) {
+            removeErrors[label] = err;
+          }
+        }
+        if (removed.length) applied.removeLabels = removed;
+        if (Object.keys(removeErrors).length) errors.removeLabels = removeErrors;
+      }
+
+      return { applied, errors };
+    },
+
+    /**
+     * `project`/`type` are ignored — GitHub has no such concepts here: the
+     * target repo is fixed by the profile's baseUrl, and issues have no
+     * type field in this MVP scope.
+     */
+    async createTicket({ summary, description } = {}, opts = {}) {
+      const body = { title: summary };
+      if (description !== undefined) body.body = description;
+      const res = await fetcher(`${GITHUB_API}/repos/${owner}/${repo}/issues`, {
+        method: 'POST',
+        headers: { ...headers, 'Content-Type': 'application/json' },
+        body: JSON.stringify(body),
+        signal: AbortSignal.timeout(opts.timeoutMs ?? 10_000),
+      });
+      if (!res.ok) await throwGitHubWriteError(res, 'creating an issue in', `${owner}/${repo}`);
+      const raw = await res.json();
+      return { key: `${keyPrefix}-${raw.number}`, id: String(raw.id), url: raw.html_url ?? null };
+    },
   };
 }

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

@@ -1,4 +1,4 @@
-import { fetchTicket, fetchCurrentUser, searchTickets, fetchStatuses, postComment, getTransitions, postTransition, assignIssue, escapeJql } from '../jira-client.mjs';
+import { fetchTicket, fetchCurrentUser, searchTickets, fetchStatuses, fetchProjects, fetchIssueTypes, postComment, getTransitions, postTransition, assignIssue, escapeJql, getIssueLinkTypes, postIssueLink, updateIssue, createIssue } from '../jira-client.mjs';
 import { buildJiraEnv } from '../config.mjs';
 
 /**
@@ -83,5 +83,71 @@ export function createJiraAdapter(conn, { fetcher = globalThis.fetch } = {}) {
       const jql = `project = "${escapeJql(project)}" AND key != "${escapeJql(sourceKey)}" AND text ~ "${escapeJql(searchText)}" ORDER BY updated DESC`;
       return searchTickets(jql, { ...base, ...opts });
     },
+
+    /**
+     * Always fetched fresh — link type names are per-instance customizable
+     * in Jira, same "never trust a stale list" principle as getTransitions.
+     * Returns just names (matches GitHub/Linear's plain-string shape) so
+     * runTicketLinkList can render any tracker's list uniformly.
+     */
+    async getLinkTypes(opts = {}) {
+      const types = await getIssueLinkTypes({ ...base, ...opts });
+      return types.map(t => t.name);
+    },
+
+    /**
+     * Always re-fetches link types fresh and resolves `typeName` against
+     * them before executing — a caller can never blind-POST a stale or
+     * guessed type name, same principle as transition().
+     * sourceKey is the outwardIssue, targetKey is the inwardIssue — direction matters.
+     */
+    async linkTo(sourceKey, targetKey, typeName, opts = {}) {
+      const types = await getIssueLinkTypes({ ...base, ...opts });
+      const match = types.find(t => t.name.toLowerCase() === typeName.toLowerCase());
+      if (!match) {
+        return { executed: false, reason: 'not-found', options: types.map(t => t.name) };
+      }
+      await postIssueLink(sourceKey, targetKey, match.name, { ...base, ...opts });
+      return { executed: true };
+    },
+
+    /**
+     * Jira does this in a single atomic PUT (fields + update.labels in one
+     * request, confirmed via Jira's own docs) — unlike GitHub, there is no
+     * per-field partial-failure surface here: either the whole call
+     * succeeds and every requested field is applied, or it throws and
+     * ticket-command.mjs's existing formatWriteFailure handles it exactly
+     * like every other write. Priority-name validity is not pre-checked —
+     * an invalid name surfaces Jira's own 400 with details, same design
+     * choice already made for ticket_create's issuetype field.
+     */
+    async updateFields(key, { title, description, priority, addLabels, removeLabels } = {}, opts = {}) {
+      await updateIssue(key, { summary: title, description, priority, addLabels, removeLabels }, { ...base, ...opts });
+      const applied = {};
+      if (title !== undefined) applied.title = true;
+      if (description !== undefined) applied.description = true;
+      if (priority !== undefined) applied.priority = priority;
+      if (addLabels?.length) applied.addLabels = addLabels;
+      if (removeLabels?.length) applied.removeLabels = removeLabels;
+      return { applied, errors: {} };
+    },
+
+    /**
+     * project/type are passed straight through — never pre-validated
+     * client-side, same design choice already made for updateFields'
+     * priority field. An invalid issuetype surfaces Jira's own 400.
+     */
+    createTicket: ({ project, type, summary, description } = {}, opts = {}) =>
+      createIssue({ project, type, summary, description }, { ...base, ...opts }),
+
+    /**
+     * Real, currently-creatable projects for this token — used to enrich a
+     * ticket_create failure message with actual options, never to
+     * pre-validate before writing.
+     */
+    listCreatableProjects: (opts = {}) => fetchProjects({ ...base, ...opts }),
+
+    /** Real, currently-configured issue types for one project. */
+    listIssueTypes: (projectKey, opts = {}) => fetchIssueTypes(projectKey, { ...base, ...opts }),
   };
 }

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

@@ -4,6 +4,9 @@ const LINEAR_API = 'https://api.linear.app/graphql';
 
 const PRIORITY_LABELS = { 1: 'Urgent', 2: 'High', 3: 'Medium', 4: 'Low' };
 
+/** Linear's IssueRelationType enum — fixed schema-level values, confirmed via GraphQL introspection. */
+const LINK_TYPES = ['blocks', 'duplicate', 'related'];
+
 const ISSUE_FIELDS = `
   identifier
   title
@@ -87,6 +90,17 @@ async function fetchIssueStateInfo(key, { token, fetcher, signal }) {
   return node;
 }
 
+/** Splits a list of label names into those found in `byName` (with their resolved id) and those not. */
+function resolveLabelNames(names, byName) {
+  const resolved = [];
+  const missing = [];
+  for (const name of names) {
+    const id = byName.get(name.toLowerCase());
+    if (id) resolved.push({ id, name }); else missing.push(name);
+  }
+  return { resolved, missing };
+}
+
 async function fetchTeamWorkflowStates(teamId, { token, fetcher, signal }) {
   const data = await gql(
     `query ($teamId: ID!) {
@@ -295,5 +309,183 @@ export function createLinearAdapter(conn, { fetcher = globalThis.fetch } = {}) {
         .filter(node => node.identifier !== sourceKey)
         .map(normalizeLinearIssue);
     },
+
+    /** Fixed schema-level enum (confirmed via GraphQL introspection) — never per-instance configurable, unlike Jira's link types. */
+    async getLinkTypes() {
+      return LINK_TYPES;
+    },
+
+    /**
+     * Validates typeName against the fixed enum before ever touching the
+     * network — an invalid type must never reach gql(), which throws a
+     * plain Error with no .status, and would otherwise be misclassified
+     * as a network/timeout failure by classifyWriteFailure. Resolves both
+     * issues' internal UUIDs via fetchIssueStateInfo — issueRelationCreate
+     * needs the UUID, never the human identifier. Explicitly checks
+     * `success`: Linear can return HTTP 200 with no top-level GraphQL
+     * errors and still report success:false.
+     */
+    async linkTo(sourceKey, targetKey, typeName, opts = {}) {
+      const normalizedType = typeName.toLowerCase();
+      if (!LINK_TYPES.includes(normalizedType)) {
+        return { executed: false, reason: 'not-found', options: LINK_TYPES };
+      }
+      const signal = AbortSignal.timeout(opts.timeoutMs ?? 10_000);
+      const source = await fetchIssueStateInfo(sourceKey, { token, fetcher, signal });
+      const target = await fetchIssueStateInfo(targetKey, { token, fetcher, signal });
+      const data = await gql(
+        `mutation ($issueId: String!, $relatedIssueId: String!, $type: IssueRelationType!) {
+          issueRelationCreate(input: { issueId: $issueId, relatedIssueId: $relatedIssueId, type: $type }) {
+            success
+          }
+        }`,
+        { issueId: source.id, relatedIssueId: target.id, type: normalizedType },
+        { token, fetcher, signal },
+      );
+      if (!data.issueRelationCreate?.success) {
+        throw new Error(`Linear issueRelationCreate reported success:false linking ${sourceKey} to ${targetKey}`);
+      }
+      return { executed: true };
+    },
+
+    /**
+     * Unlike Jira's freeform label strings, Linear's addedLabelIds/
+     * removedLabelIds (IssueUpdateInput) take real label UUIDs and never
+     * auto-create a missing one — a name must be resolved against the
+     * issue's own team first (same shape as fetchTeamWorkflowStates).
+     * Resolution failures (unknown label name, unresolvable priority name)
+     * are collected into `errors` and simply excluded from the mutation
+     * input rather than blocking it — whatever DID resolve still lands in
+     * one atomic issueUpdate call. Empty input skips the mutation entirely
+     * (nothing valid to send). Priority is accepted as a display name for
+     * cross-tracker consistency and reverse-mapped via the same
+     * PRIORITY_LABELS table normalizeLinearIssue already uses for reads.
+     */
+    async updateFields(key, { title, description, priority, addLabels, removeLabels } = {}, opts = {}) {
+      const signal = AbortSignal.timeout(opts.timeoutMs ?? 10_000);
+      const info = await fetchIssueStateInfo(key, { token, fetcher, signal });
+
+      const input = {};
+      const applied = {};
+      const errors = {};
+
+      if (title !== undefined) input.title = title;
+      if (description !== undefined) input.description = description;
+
+      let resolvedPriorityLabel;
+      if (priority !== undefined) {
+        const normalized = priority.trim().toLowerCase();
+        if (normalized === 'none') {
+          input.priority = 0;
+          resolvedPriorityLabel = 'None';
+        } else {
+          const entry = Object.entries(PRIORITY_LABELS).find(([, label]) => label.toLowerCase() === normalized);
+          if (entry) {
+            input.priority = Number(entry[0]);
+            resolvedPriorityLabel = entry[1];
+          } else {
+            errors.priority = { reason: 'not-found', options: ['None', ...Object.values(PRIORITY_LABELS)] };
+          }
+        }
+      }
+
+      let addLabelsResolved, addLabelsMissing, removeLabelsResolved, removeLabelsMissing;
+      if (addLabels?.length || removeLabels?.length) {
+        const labelData = await gql(
+          `query ($teamId: ID!) { issueLabels(filter: { team: { id: { eq: $teamId } } }, first: 250) { nodes { id name } } }`,
+          { teamId: info.team.id },
+          { token, fetcher, signal },
+        );
+        const byName = new Map((labelData.issueLabels?.nodes ?? []).map(l => [l.name.toLowerCase(), l.id]));
+
+        if (addLabels?.length) {
+          ({ resolved: addLabelsResolved, missing: addLabelsMissing } = resolveLabelNames(addLabels, byName));
+          if (addLabelsResolved.length) input.addedLabelIds = addLabelsResolved.map(l => l.id);
+          if (addLabelsMissing.length) errors.addLabels = { reason: 'not-found', missing: addLabelsMissing };
+        }
+        if (removeLabels?.length) {
+          ({ resolved: removeLabelsResolved, missing: removeLabelsMissing } = resolveLabelNames(removeLabels, byName));
+          if (removeLabelsResolved.length) input.removedLabelIds = removeLabelsResolved.map(l => l.id);
+          if (removeLabelsMissing.length) errors.removeLabels = { reason: 'not-found', missing: removeLabelsMissing };
+        }
+      }
+
+      if (Object.keys(input).length === 0) {
+        return { applied, errors };
+      }
+
+      const data = await gql(
+        `mutation ($id: String!, $input: IssueUpdateInput!) { issueUpdate(id: $id, input: $input) { success } }`,
+        { id: info.id, input },
+        { token, fetcher, signal },
+      );
+      if (!data.issueUpdate?.success) {
+        throw new Error(`Linear issueUpdate reported success:false updating ${key}`);
+      }
+
+      if (title !== undefined) applied.title = true;
+      if (description !== undefined) applied.description = true;
+      if (input.priority !== undefined) applied.priority = resolvedPriorityLabel;
+      if (addLabelsResolved?.length) applied.addLabels = addLabelsResolved.map(l => l.name);
+      if (removeLabelsResolved?.length) applied.removeLabels = removeLabelsResolved.map(l => l.name);
+
+      return { applied, errors };
+    },
+
+    /**
+     * `project` is the team's short key (e.g. "ENG") — mutations need the
+     * UUID, never the key, so it's resolved via TeamFilter.key first
+     * (confirmed against Linear's own official generated GraphQL schema).
+     * No discovery call on an unresolvable key, same "surface a clear
+     * terminal error" choice already made for Jira's issuetype — there is
+     * no partial-creation concept here, unlike updateFields' best-effort
+     * shape. `type` has no Linear equivalent and is intentionally ignored.
+     */
+    async createTicket({ project, summary, description } = {}, opts = {}) {
+      const signal = AbortSignal.timeout(opts.timeoutMs ?? 10_000);
+      const teamData = await gql(
+        `query ($key: String!) { teams(filter: { key: { eq: $key } }, first: 1) { nodes { id } } }`,
+        { key: project },
+        { token, fetcher, signal },
+      );
+      const team = teamData.teams?.nodes?.[0];
+      if (!team) {
+        const err = new Error(`Linear team not found for project "${project}".`);
+        // Marked, not message-sniffed — ticket-command.mjs's cache-refresh
+        // enrichment needs a clean way to detect "the project/team didn't
+        // resolve" without parsing this string.
+        err.code = 'PROJECT_NOT_FOUND';
+        throw err;
+      }
+      const input = { teamId: team.id, title: summary };
+      if (description !== undefined) input.description = description;
+      const data = await gql(
+        `mutation ($input: IssueCreateInput!) { issueCreate(input: $input) { success issue { identifier id url } } }`,
+        { input },
+        { token, fetcher, signal },
+      );
+      if (!data.issueCreate?.success) {
+        throw new Error(`Linear issueCreate reported success:false creating an issue in team "${project}".`);
+      }
+      const issue = data.issueCreate.issue;
+      return { key: issue.identifier, id: issue.id, url: issue.url ?? null };
+    },
+
+    /**
+     * Real, currently-accessible teams for this token — unfiltered, used
+     * only to enrich a ticket_create failure message with actual options
+     * (Jira calls the equivalent concept "projects"; --project already
+     * conflates the two at the CLI level, so the shape matches for a
+     * uniform cache).
+     */
+    async listCreatableProjects(opts = {}) {
+      const signal = AbortSignal.timeout(opts.timeoutMs ?? 10_000);
+      const data = await gql(
+        `query { teams(first: 250) { nodes { key name } } }`,
+        {},
+        { token, fetcher, signal },
+      );
+      return (data.teams?.nodes ?? []).map(t => ({ key: t.key, name: t.name }));
+    },
   };
 }

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

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