@enrichlayer/el-linear 1.25.0 → 1.27.0

package/README.md

@@ -766,6 +766,39 @@ existing markdown or Slack links, angle-bracket autolinks, and bare URLs, so
 it's safe to pipe documents that already contain a mix of formatted links
 and bare identifiers.
 
+## Relation-candidate confirmation prompt
+
+When `el-linear search` or `el-linear issues search` returns results that
+carry issue identifiers (the "I just ran a duplicate/related check" shape),
+the JSON envelope embeds a structured `_warnings` line:
+
+```json
+{
+  "data": [{ "identifier": "DEV-2134", "title": "…" }, /* … */],
+  "meta": { "count": 3, "query": "auth flicker" },
+  "_warnings": [
+    "relation_candidates: Found 3 candidate related issues (DEV-2134, FIN-77, ALL-672). To link them as related: reply with the IDs you want linked (e.g. \"link DEV-2134 and FIN-77\"). To skip linking: reply \"no links\". (Agent-inferred IDs are blocked by auto-mode; user-named IDs pass — DEV-4494.)"
+  ]
+}
+```
+
+Why it exists: Claude Code's auto-mode permission classifier blocks
+`el-linear issues relate <source> --related-to "<ids>"` calls when the IDs
+were inferred by the agent from its own search rather than typed by the
+user — because each listed peer is a write target. The prompt nudges the
+caller (typically an agent driving the `linear-operations` skill) to surface
+the candidates verbatim and have the user name which IDs to link; any
+subsequent `issues relate` call then carries user-specified IDs and the
+guard passes naturally. **The fix is not to weaken the guard** — see
+[DEV-4494](https://linear.app/verticalint/issue/DEV-4494/) for the original
+incident (PYT-213 triage, 2026-06-04).
+
+The `relation_candidates:` prefix is a stable token so a skill or harness
+can grep for it without parsing free-form prose, matching the existing
+`results_truncated:` convention. Non-issue rows (projects, documents,
+initiatives) are ignored; the warning is suppressed when no result carries
+an identifier.
+
 ## Use with Claude Code
 
 el-linear ships a Claude Code skill at `claude-skills/linear-operations/SKILL.md`.

package/claude-skills/linear-operations/SKILL.md

@@ -160,11 +160,27 @@ and outreach tracked in one place.
 
 **Search before creating. No exceptions.**
 
+> **Now enforced at the CLI ([DEV-4823](https://linear.app/verticalint/issue/DEV-4823/)).** `el-linear issues create` runs a deterministic
+> duplicate-detection gate *before* the create POST: it tokenizes the title,
+> searches the salient keywords (including closed issues), scores candidates
+> by Jaccard title-overlap, and **blocks (exit non-zero) — listing the
+> matches (id · title · state · assignee)** — when one crosses the similarity
+> threshold (default `0.35`, set `validation.duplicateThreshold` to tune). This
+> is the deterministic backstop for the manual check below — don't skip the
+> manual review just because the gate exists (it catches title-keyword dupes,
+> not semantic ones with different wording). To proceed past a flagged dupe,
+> use `--allow-duplicate` (the narrow, correct flag for this gate);
+> `--skip-validation` also bypasses it but skips all field validation too, so
+> prefer `--allow-duplicate`. Disable just the gate with
+> `validation.duplicateDetection: false` (field validation still runs);
+> `validation.enabled: false` turns off all validation.
+
 ```bash
 # --include-closed is required so previously-completed duplicates surface.
 # `issues search` defaults to open states (DEV-4478); the duplicate check
 # intentionally widens to Done/Canceled because a closed-out duplicate is
-# still a duplicate.
+# still a duplicate. (`issues create` runs this same widened search itself
+# as the DEV-4823 gate — this manual step is for the semantic/judgment pass.)
 el-linear issues search "keywords from proposed title" --include-closed 2>&1
 ```
 
@@ -181,6 +197,43 @@ el-linear issues search "keywords from proposed title" --include-closed 2>&1
    el-linear issues create "Title" --team ENG --related-to "ENG-456,ENG-789" ... 2>&1
    ```
 
+### Surfacing relation candidates — explicit user reply required ([DEV-4494](https://linear.app/verticalint/issue/DEV-4494/))
+
+When `el-linear issues search` (or the cross-resource `search`) returns rows
+carrying issue identifiers, the JSON envelope embeds a `_warnings` line
+starting with `relation_candidates:` that enumerates the candidate IDs and
+asks the user to reply with which ones to link, and states the skip phrase.
+
+That warning is the authoritative instruction — surface it to the user
+verbatim and follow it literally: **do not call `el-linear issues relate`
+until the user replies naming the IDs to link.** Only user-named IDs go into
+the `issues relate <source> --related-to "<ids>"` call — never pass an ID the
+user did not name, even one your own search obviously surfaced. The CLI emits
+the full procedure (every candidate ID, the example reply, the skip phrase) in
+that one line, so follow it rather than re-deriving or paraphrasing it away.
+
+Why this matters: Claude Code's auto-mode permission classifier blocks
+`issues relate --related-to "<ids>"` when the IDs were *agent-inferred*
+(came from your own search) rather than *user-specified* (typed by the human),
+because each listed peer is a write target. Routing the IDs through an
+explicit human reply converts them from agent-inferred → user-specified;
+the existing search step (above) stays intact; auto-mode's guard is not
+weakened. The fix is the loop shape, not the guard.
+
+Anti-patterns:
+
+- **Calling `issues relate` directly off your own search output** — even if
+  the IDs are real and the candidates look obvious, this is the exact path
+  the auto-mode guard refuses.
+- **Splitting one relate call into N single-ID calls** to "look smaller" —
+  same provenance problem, same block, just multiplied.
+- **Asking the user a yes/no question** ("Should I link these?") instead of
+  having them name the IDs — yes answers stay agent-inferred, the reply
+  must carry the IDs to convert them to user-specified.
+
+If `--include-closed` search returns no matches, no `relation_candidates:`
+warning is emitted (nothing to confirm) and the flow proceeds normally.
+
 ### Viewing existing relations
 
 ```bash

package/dist/commands/issues.js

@@ -6,6 +6,7 @@ import { resolveAssignee, resolveLabels, resolveMember, resolveTeam, } from "../
 import { resolveDefaultStatus } from "../config/status-defaults.js";
 import { enforceTerms } from "../config/term-enforcer.js";
 import { GET_ISSUE_RELATIONS_QUERY, GET_ISSUE_STATE_HISTORY_QUERY, } from "../queries/issues.js";
+import { DEFAULT_DUPLICATE_THRESHOLD, formatDuplicateBlock, scoreDuplicateCandidates, tokenizeTitle, } from "../utils/duplicate-detection.js";
 import { createFileService } from "../utils/file-service.js";
 import { applyFooter } from "../utils/footer.js";
 import { createGraphQLAttachmentsService } from "../utils/graphql-attachments-service.js";
@@ -14,6 +15,7 @@ import { createIssuesService } from "../utils/issues-service-bootstrap.js";
 import { createLinearService, } from "../utils/linear-service.js";
 import { logger } from "../utils/logger.js";
 import { handleAsyncCommand, outputSuccess, outputWarning, warnIfTruncated, } from "../utils/output.js";
+import { buildRelationCandidatePrompt } from "../utils/relation-candidate-prompt.js";
 import { getRootOpts } from "../utils/root-opts.js";
 import { formatCsv, formatMarkdown, formatTable, } from "../utils/table-formatter.js";
 import { parsePositiveInt, parsePriorityFilter, splitList, validatePriority, } from "../utils/validators.js";
@@ -269,6 +271,15 @@ async function handleSearchIssues(query, options, command) {
         outputWarning("excluded terminal states (Done / Canceled) by default; pass --include-closed to include them");
     }
     warnIfTruncated(result.length, limit);
+    // DEV-4494: surface the explicit "reply with the IDs to link" prompt
+    // whenever an issue search returns candidate identifiers. The
+    // `linear-operations` skill consumes this `_warnings` line and shows it
+    // to the user so any subsequent `issues relate` call is user-specified
+    // rather than agent-inferred (which auto-mode blocks).
+    const relationPrompt = buildRelationCandidatePrompt(result);
+    if (relationPrompt) {
+        outputWarning(relationPrompt);
+    }
     outputIssues(result, options.format, options.fields, { query });
 }
 /**
@@ -441,6 +452,64 @@ function buildDescriptionWithAttachments(baseDescription, uploadResults) {
     }
     return description;
 }
+/**
+ * DEV-4823: create-time duplicate-detection gate. Searches the title's
+ * salient keywords (including closed issues), scores candidates by Jaccard
+ * title-overlap, and throws — listing the matches — when one is at/above the
+ * configured similarity threshold.
+ *
+ * Bypassed by `--allow-duplicate`, `--skip-validation`, and
+ * `config.validation.duplicateDetection: false` / `validation.enabled: false`.
+ * The search itself is best-effort: a network/API failure warns and proceeds
+ * rather than blocking legitimate issue creation on infra trouble.
+ */
+async function enforceNoDuplicateIssue(title, options, issuesService) {
+    if (options.allowDuplicate || options.skipValidation) {
+        return;
+    }
+    const validation = loadConfig().validation;
+    // Master switch (validation.enabled) defaults on; the dup-specific toggle
+    // defaults on too, so the gate is active out of the box.
+    if (validation?.enabled === false ||
+        validation?.duplicateDetection === false) {
+        return;
+    }
+    const keywords = [...tokenizeTitle(title)];
+    if (keywords.length === 0) {
+        // Nothing distinctive to search on — can't meaningfully detect a dupe.
+        return;
+    }
+    const threshold = typeof validation?.duplicateThreshold === "number"
+        ? validation.duplicateThreshold
+        : DEFAULT_DUPLICATE_THRESHOLD;
+    let candidates;
+    try {
+        candidates = await issuesService.searchIssues({
+            query: keywords.join(" "),
+            // Include Done/Canceled — a closed-out duplicate is still a duplicate
+            // (the motivating DEV-4816 was already Canceled).
+            excludeTerminalStates: false,
+            // Linear ranks the full-text matches; cap the window at 50 so a real
+            // dupe on a high-traffic keyword set is unlikely to rank out of view,
+            // while keeping the single search cheap. The gate is a best-effort
+            // backstop to the manual dup check, not the sole guard — recall need
+            // not be exhaustive.
+            limit: 50,
+        });
+    }
+    catch (err) {
+        outputWarning(`Duplicate-detection search failed (${err instanceof Error ? err.message : String(err)}); proceeding without the dup check. Pass --allow-duplicate to silence.`);
+        return;
+    }
+    if (!Array.isArray(candidates) || candidates.length === 0) {
+        return;
+    }
+    const matches = scoreDuplicateCandidates(title, candidates, threshold);
+    if (matches.length === 0) {
+        return;
+    }
+    throw new Error(`Issue creation blocked: ${formatDuplicateBlock(matches)}`);
+}
 async function handleCreateIssue(title, options, command) {
     const rootOpts = getRootOpts(command);
     const { teamInput, teamId, assigneeId, delegateId, labelIds, status, subscriberIds, priority, } = await resolveCreateInputs(title ?? "", options, rootOpts);
@@ -456,6 +525,19 @@ async function handleCreateIssue(title, options, command) {
         noFooter,
     }) ?? "";
     const { graphQLService, linearService, issuesService } = await createIssuesService(rootOpts);
+    // DEV-4823: deterministic duplicate-detection gate. Runs before the create
+    // POST, searches the title's salient keywords (including closed issues),
+    // and throws — listing candidates — when a high-similarity issue already
+    // exists. Bypassed by --allow-duplicate and --skip-validation (it's a
+    // validation-class check). Reuses the issuesService just created.
+    //
+    // Gap: with --from-template and no title override, `title` is undefined
+    // (Linear copies the template's title server-side), so the gate can't run
+    // — the template-resolved title isn't known client-side. Template-
+    // instantiated issues are rarer; the manual dup check still applies there.
+    if (title) {
+        await enforceNoDuplicateIssue(title, options, issuesService);
+    }
     // Wrap valid issue identifiers as markdown links before creating, so the description
     // saved on Linear has clickable refs from the start. Self-reference can't apply here
     // because the issue doesn't exist yet — pass undefined.
@@ -999,7 +1081,8 @@ export function setupIssuesCommands(program) {
         .option("--due-date <date>", "due date (YYYY-MM-DD)")
         .option("--checkout", "create and checkout a git branch named after the issue")
         .option("--no-claim", "with --checkout, skip assigning the issue to the current Linear user and moving it to the first started state")
-        .option("--skip-validation", "skip all validation (labels, description, assignee, project)")
+        .option("--skip-validation", "skip all validation (labels, description, assignee, project, duplicate detection)")
+        .option("--allow-duplicate", "skip the duplicate-detection gate and create even if a similar issue already exists")
         .option("--no-auto-link", "skip auto-linking issue references found in the description")
         .option("--footer <text>", "text appended to the description (overrides config.messageFooter)")
         .option("--no-footer", "skip the configured messageFooter for this issue")

package/dist/commands/search.js

@@ -1,7 +1,8 @@
 import { resolveTeam, resolveUserDisplayName } from "../config/resolver.js";
 import { SEMANTIC_SEARCH_QUERY } from "../queries/search.js";
 import { createGraphQLService } from "../utils/graphql-service.js";
-import { handleAsyncCommand, outputSuccess } from "../utils/output.js";
+import { handleAsyncCommand, outputSuccess, outputWarning, } from "../utils/output.js";
+import { buildRelationCandidatePrompt } from "../utils/relation-candidate-prompt.js";
 import { getRootOpts } from "../utils/root-opts.js";
 import { parsePositiveInt } from "../utils/validators.js";
 const TEMPLATES_QUERY = `
@@ -180,9 +181,19 @@ export function setupSearchCommands(program) {
             const templates = templateResult.templates ?? [];
             data = [...data, ...searchTemplates(templates, query)];
         }
+        const finalData = data.slice(0, limit);
+        // DEV-4494: when results carry issue identifiers, nudge the
+        // caller to surface them to the user verbatim and have the
+        // user name which IDs to link via `issues relate`. Keeps
+        // agent-inferred IDs out of relate calls without weakening
+        // auto-mode's guard.
+        const relationPrompt = buildRelationCandidatePrompt(finalData);
+        if (relationPrompt) {
+            outputWarning(relationPrompt);
+        }
         outputSuccess({
-            data: data.slice(0, limit),
-            meta: { count: Math.min(data.length, limit), query },
+            data: finalData,
+            meta: { count: finalData.length, query },
         });
     }));
 }

package/dist/config/config.d.ts

@@ -55,6 +55,18 @@ export interface ElLinearConfig {
          * built-in overrides (DEV-4084).
          */
         teamTypeLabels?: Record<string, string[]>;
+        /**
+         * Toggle the create-time duplicate-detection gate (DEV-4823). Defaults
+         * to `true` when validation is enabled. Set `false` to keep field
+         * validation (labels/description/…) while turning off the dup search.
+         */
+        duplicateDetection?: boolean;
+        /**
+         * Jaccard title-similarity threshold (0–1) above which a pre-existing
+         * issue is treated as a duplicate and blocks creation. Defaults to
+         * `DEFAULT_DUPLICATE_THRESHOLD` (0.35). Lower = more aggressive.
+         */
+        duplicateThreshold?: number;
     };
     /**
      * Optional override for the Linear workspace URL key (the part after

package/dist/utils/duplicate-detection.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Duplicate-issue detection — DEV-4823.
+ *
+ * Turns the MANDATORY-but-skippable duplicate check from the
+ * `linear-operations` skill into a deterministic create-time gate, mirroring
+ * the one `projects create` already has (DEV-3604). Before the create POST,
+ * `issues create` searches the title's salient keywords and refuses (listing
+ * the candidates) when a high-similarity open/recently-closed issue already
+ * exists.
+ *
+ * The skill prose is skippable; this isn't. On 2026-06-19 a single session
+ * filed two duplicates of in-flight work (DEV-4816 duped DEV-4818, opposite
+ * decided approaches) because it claim-checked the *new* issue's branch
+ * instead of searching for a pre-existing issue on the same topic. The
+ * claim-check (`scripts/issue-claimed.mjs`, DEV-4666) only catches collisions
+ * on the new issue's own id/branch — not a topically-identical issue with a
+ * different number. This gate closes that gap.
+ *
+ * Scoring reuses the Jaccard keyword-overlap heuristic from the
+ * `agent-efficiency-auditor` (DEV-4155): tokenize both titles, drop
+ * stopwords/numbers, and score by |intersection| / |union| of the token sets.
+ */
+import type { LinearIssue } from "../types/linear.js";
+/**
+ * Default similarity threshold above which a candidate is treated as a
+ * duplicate. Tuned against real workspace data so the motivating
+ * DEV-4816 ↔ DEV-4818 pair (Jaccard 0.40 with the tokenization below) and the
+ * genuine sibling DEV-3604 (0.44) fire, while merely same-domain issues do
+ * not: two unrelated "Migrate …" titles sharing only the verb sit at ~0.14,
+ * and a different-problem tooling issue sharing only boilerplate tokens
+ * (`el-linear`/`issues`/`create`) measured 0.31 — both below 0.35.
+ * Overridable via `config.validation.duplicateThreshold`.
+ */
+export declare const DEFAULT_DUPLICATE_THRESHOLD = 0.35;
+/** A scored duplicate candidate, ready to print in the block. */
+export interface DuplicateCandidate {
+    identifier: string;
+    title: string;
+    state: string;
+    assignee: string;
+    /** Jaccard similarity in [0, 1], rounded to 2 dp for display. */
+    score: number;
+}
+/**
+ * Tokenize a title into a set of salient lowercase keywords.
+ *
+ * Splits on any run of non-alphanumeric characters (so `scripts/*.mjs` →
+ * `scripts`, `mjs`), lowercases, then drops stopwords, pure numbers
+ * (`52 files` → `files`), and single-character tokens. Returns a Set so
+ * downstream set algebra is direct.
+ *
+ * Scope: ASCII `[a-z0-9]` only — a title written entirely in a non-Latin
+ * script (Cyrillic, CJK, …) tokenizes to the empty set, so the gate fails
+ * open (no candidates, never a false positive) and the manual dup check
+ * carries it. Acceptable given the workspace's title language.
+ */
+export declare function tokenizeTitle(title: string): Set<string>;
+/**
+ * Jaccard similarity of two token sets: |intersection| / |union|.
+ * Returns 0 when either set is empty (no signal to compare).
+ */
+export declare function jaccardSimilarity(a: Set<string>, b: Set<string>): number;
+/**
+ * Score candidate issues against a proposed title and return those at or above
+ * `threshold`, sorted by descending similarity (highest first). Candidates
+ * with an unparseable/empty title are skipped. `score` is rounded to 2 dp for
+ * stable display and tests.
+ */
+export declare function scoreDuplicateCandidates(title: string, candidates: LinearIssue[], threshold?: number): DuplicateCandidate[];
+/**
+ * Render the human/agent-facing block listing duplicate candidates, matching
+ * the shape of the validation "Suggestions:" blocks (id · title · state ·
+ * assignee). Used as the body of the thrown error when the gate fires.
+ */
+export declare function formatDuplicateBlock(candidates: DuplicateCandidate[]): string;

package/dist/utils/duplicate-detection.js

@@ -0,0 +1,148 @@
+/**
+ * Duplicate-issue detection — DEV-4823.
+ *
+ * Turns the MANDATORY-but-skippable duplicate check from the
+ * `linear-operations` skill into a deterministic create-time gate, mirroring
+ * the one `projects create` already has (DEV-3604). Before the create POST,
+ * `issues create` searches the title's salient keywords and refuses (listing
+ * the candidates) when a high-similarity open/recently-closed issue already
+ * exists.
+ *
+ * The skill prose is skippable; this isn't. On 2026-06-19 a single session
+ * filed two duplicates of in-flight work (DEV-4816 duped DEV-4818, opposite
+ * decided approaches) because it claim-checked the *new* issue's branch
+ * instead of searching for a pre-existing issue on the same topic. The
+ * claim-check (`scripts/issue-claimed.mjs`, DEV-4666) only catches collisions
+ * on the new issue's own id/branch — not a topically-identical issue with a
+ * different number. This gate closes that gap.
+ *
+ * Scoring reuses the Jaccard keyword-overlap heuristic from the
+ * `agent-efficiency-auditor` (DEV-4155): tokenize both titles, drop
+ * stopwords/numbers, and score by |intersection| / |union| of the token sets.
+ */
+/**
+ * Default similarity threshold above which a candidate is treated as a
+ * duplicate. Tuned against real workspace data so the motivating
+ * DEV-4816 ↔ DEV-4818 pair (Jaccard 0.40 with the tokenization below) and the
+ * genuine sibling DEV-3604 (0.44) fire, while merely same-domain issues do
+ * not: two unrelated "Migrate …" titles sharing only the verb sit at ~0.14,
+ * and a different-problem tooling issue sharing only boilerplate tokens
+ * (`el-linear`/`issues`/`create`) measured 0.31 — both below 0.35.
+ * Overridable via `config.validation.duplicateThreshold`.
+ */
+export const DEFAULT_DUPLICATE_THRESHOLD = 0.35;
+/**
+ * Function words and issue-boilerplate tokens that carry no topical signal.
+ * Dropping them keeps the Jaccard score driven by the distinctive nouns
+ * (`scripts`, `mjs`, `typescript`) rather than by glue words every title
+ * shares. Type-indicating verbs (`add`, `fix`, `migrate`, …) are deliberately
+ * NOT stopworded: `migrate` is a genuine topical signal in the motivating
+ * dupe pair, and two unrelated "Add X" issues already score low because their
+ * *other* tokens differ — keeping the verb inflates the score by at most one
+ * shared token, not enough to false-positive.
+ */
+const STOPWORDS = new Set([
+    "a",
+    "an",
+    "and",
+    "as",
+    "at",
+    "but",
+    "by",
+    "for",
+    "from",
+    "in",
+    "into",
+    "of",
+    "off",
+    "on",
+    "or",
+    "out",
+    "over",
+    "per",
+    "the",
+    "then",
+    "to",
+    "via",
+    "vs",
+    "with",
+    "without",
+]);
+/**
+ * Tokenize a title into a set of salient lowercase keywords.
+ *
+ * Splits on any run of non-alphanumeric characters (so `scripts/*.mjs` →
+ * `scripts`, `mjs`), lowercases, then drops stopwords, pure numbers
+ * (`52 files` → `files`), and single-character tokens. Returns a Set so
+ * downstream set algebra is direct.
+ *
+ * Scope: ASCII `[a-z0-9]` only — a title written entirely in a non-Latin
+ * script (Cyrillic, CJK, …) tokenizes to the empty set, so the gate fails
+ * open (no candidates, never a false positive) and the manual dup check
+ * carries it. Acceptable given the workspace's title language.
+ */
+export function tokenizeTitle(title) {
+    const tokens = title
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter((t) => t.length >= 2 && !STOPWORDS.has(t) && !/^\d+$/.test(t));
+    return new Set(tokens);
+}
+/**
+ * Jaccard similarity of two token sets: |intersection| / |union|.
+ * Returns 0 when either set is empty (no signal to compare).
+ */
+export function jaccardSimilarity(a, b) {
+    if (a.size === 0 || b.size === 0) {
+        return 0;
+    }
+    let intersection = 0;
+    for (const token of a) {
+        if (b.has(token)) {
+            intersection++;
+        }
+    }
+    const union = a.size + b.size - intersection;
+    return union === 0 ? 0 : intersection / union;
+}
+/**
+ * Score candidate issues against a proposed title and return those at or above
+ * `threshold`, sorted by descending similarity (highest first). Candidates
+ * with an unparseable/empty title are skipped. `score` is rounded to 2 dp for
+ * stable display and tests.
+ */
+export function scoreDuplicateCandidates(title, candidates, threshold = DEFAULT_DUPLICATE_THRESHOLD) {
+    const titleTokens = tokenizeTitle(title);
+    if (titleTokens.size === 0) {
+        return [];
+    }
+    const scored = [];
+    for (const issue of candidates) {
+        const score = jaccardSimilarity(titleTokens, tokenizeTitle(issue.title));
+        if (score >= threshold) {
+            scored.push({
+                identifier: issue.identifier,
+                title: issue.title,
+                state: issue.state?.name ?? "—",
+                assignee: issue.assignee?.name ?? "—",
+                score: Math.round(score * 100) / 100,
+            });
+        }
+    }
+    scored.sort((a, b) => b.score - a.score);
+    return scored;
+}
+/**
+ * Render the human/agent-facing block listing duplicate candidates, matching
+ * the shape of the validation "Suggestions:" blocks (id · title · state ·
+ * assignee). Used as the body of the thrown error when the gate fires.
+ */
+export function formatDuplicateBlock(candidates) {
+    const lines = candidates.map((c) => `    ${c.identifier} · ${c.title} · ${c.state} · ${c.assignee}  (similarity ${c.score})`);
+    return (`Possible duplicate issue${candidates.length > 1 ? "s" : ""} found ` +
+        "(by title-keyword overlap):\n" +
+        `${lines.join("\n")}\n\n` +
+        "  If one of these is the same work, comment on it instead of creating a new issue.\n" +
+        "  If this is genuinely distinct, re-run with --allow-duplicate to proceed " +
+        "(and consider --related-to to link the related issue).");
+}

package/dist/utils/relation-candidate-prompt.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Relation-candidate confirmation prompt — DEV-4494.
+ *
+ * When `el-linear search` or `el-linear issues search` returns results that
+ * carry issue identifiers (the "I just ran a dup-check" shape), we emit a
+ * structured `_warnings` line that nudges the *caller* (typically a Claude
+ * agent driving `linear-operations`) to surface the IDs to the user verbatim
+ * and wait for an explicit reply naming which ones to link.
+ *
+ * Why the explicit reply matters
+ * ------------------------------
+ * Claude Code's auto-mode permission classifier blocks
+ * `el-linear issues relate <source> --related-to "<ids>"` when the IDs were
+ * inferred by the agent from its own search rather than typed by the user —
+ * because creating a relation writes onto *every* listed peer issue, and the
+ * IDs must be user-specified, not agent-inferred, to clear the guard.
+ *
+ * The fix isn't to weaken the guard. It's to tighten the loop: surface the
+ * candidates, ask the human to name which IDs to link, and only THEN call
+ * `issues relate` — at which point the IDs are user-specified by
+ * construction and the guard passes naturally.
+ *
+ * This module produces the warning. The actual UX is enforced by the
+ * `linear-operations` skill (it consumes the warning and shows it to the
+ * user) and by the existing auto-mode guard (it continues to block
+ * agent-inferred relate calls).
+ *
+ * Reference: https://linear.app/verticalint/issue/DEV-4494/
+ */
+/**
+ * Extract issue identifiers from a heterogeneous result array.
+ *
+ * Accepts the union of shapes used across the search commands:
+ * - `issues search` rows (`LinearIssue`) carry `identifier` at the top level
+ * - cross-resource `search` rows transform to `{ type: "issue", identifier }`
+ *   for issue rows; non-issue rows (`project`, `document`, …) have no
+ *   identifier and are skipped.
+ *
+ * Deduplicates and preserves insertion order so the prompt enumerates IDs
+ * in the same order they appear on screen.
+ */
+export declare function extractCandidateIdentifiers(rows: unknown[]): string[];
+/**
+ * Build the relation-candidate confirmation warning string, or `null` when
+ * the result set has no identifier-bearing rows (nothing to confirm).
+ *
+ * Shape (single line, structured-prose so a skill can match on the prefix):
+ *
+ *     relation_candidates: Found N candidate related issues (DEV-1, DEV-2, …).
+ *     To link them as related: reply with the IDs you want linked
+ *     (e.g. "link DEV-1 and DEV-2"). To skip linking: reply "no links".
+ *
+ * The `relation_candidates:` prefix matches the existing `results_truncated:`
+ * convention in `outputWarning` callers — a stable token a skill / agent
+ * harness can grep for without parsing free-form prose.
+ */
+export declare function buildRelationCandidatePrompt(rows: unknown[]): string | null;

package/dist/utils/relation-candidate-prompt.js

@@ -0,0 +1,94 @@
+/**
+ * Relation-candidate confirmation prompt — DEV-4494.
+ *
+ * When `el-linear search` or `el-linear issues search` returns results that
+ * carry issue identifiers (the "I just ran a dup-check" shape), we emit a
+ * structured `_warnings` line that nudges the *caller* (typically a Claude
+ * agent driving `linear-operations`) to surface the IDs to the user verbatim
+ * and wait for an explicit reply naming which ones to link.
+ *
+ * Why the explicit reply matters
+ * ------------------------------
+ * Claude Code's auto-mode permission classifier blocks
+ * `el-linear issues relate <source> --related-to "<ids>"` when the IDs were
+ * inferred by the agent from its own search rather than typed by the user —
+ * because creating a relation writes onto *every* listed peer issue, and the
+ * IDs must be user-specified, not agent-inferred, to clear the guard.
+ *
+ * The fix isn't to weaken the guard. It's to tighten the loop: surface the
+ * candidates, ask the human to name which IDs to link, and only THEN call
+ * `issues relate` — at which point the IDs are user-specified by
+ * construction and the guard passes naturally.
+ *
+ * This module produces the warning. The actual UX is enforced by the
+ * `linear-operations` skill (it consumes the warning and shows it to the
+ * user) and by the existing auto-mode guard (it continues to block
+ * agent-inferred relate calls).
+ *
+ * Reference: https://linear.app/verticalint/issue/DEV-4494/
+ */
+/** Cap how many candidate IDs the prompt enumerates inline. */
+const MAX_CANDIDATES_IN_PROMPT = 10;
+/**
+ * Extract issue identifiers from a heterogeneous result array.
+ *
+ * Accepts the union of shapes used across the search commands:
+ * - `issues search` rows (`LinearIssue`) carry `identifier` at the top level
+ * - cross-resource `search` rows transform to `{ type: "issue", identifier }`
+ *   for issue rows; non-issue rows (`project`, `document`, …) have no
+ *   identifier and are skipped.
+ *
+ * Deduplicates and preserves insertion order so the prompt enumerates IDs
+ * in the same order they appear on screen.
+ */
+export function extractCandidateIdentifiers(rows) {
+    const seen = new Set();
+    const out = [];
+    for (const row of rows) {
+        if (row === null || typeof row !== "object")
+            continue;
+        const r = row;
+        const id = typeof r.identifier === "string" ? r.identifier : undefined;
+        if (!id)
+            continue;
+        if (seen.has(id))
+            continue;
+        seen.add(id);
+        out.push(id);
+    }
+    return out;
+}
+/**
+ * Build the relation-candidate confirmation warning string, or `null` when
+ * the result set has no identifier-bearing rows (nothing to confirm).
+ *
+ * Shape (single line, structured-prose so a skill can match on the prefix):
+ *
+ *     relation_candidates: Found N candidate related issues (DEV-1, DEV-2, …).
+ *     To link them as related: reply with the IDs you want linked
+ *     (e.g. "link DEV-1 and DEV-2"). To skip linking: reply "no links".
+ *
+ * The `relation_candidates:` prefix matches the existing `results_truncated:`
+ * convention in `outputWarning` callers — a stable token a skill / agent
+ * harness can grep for without parsing free-form prose.
+ */
+export function buildRelationCandidatePrompt(rows) {
+    const ids = extractCandidateIdentifiers(rows);
+    if (ids.length === 0)
+        return null;
+    const shown = ids.slice(0, MAX_CANDIDATES_IN_PROMPT);
+    const overflow = ids.length - shown.length;
+    const idList = overflow > 0
+        ? `${shown.join(", ")}, … (+${overflow} more)`
+        : shown.join(", ");
+    // Build two concrete example IDs from the head of the list so the
+    // "reply with the IDs you want linked" example is realistic for the
+    // caller's actual search rather than a fixed placeholder. Single-result
+    // case still reads naturally ("link DEV-1").
+    const example = shown.length >= 2 ? `link ${shown[0]} and ${shown[1]}` : `link ${shown[0]}`;
+    const noun = ids.length === 1 ? "candidate related issue" : "candidate related issues";
+    return (`relation_candidates: Found ${ids.length} ${noun} (${idList}). ` +
+        `To link them as related: reply with the IDs you want linked ` +
+        `(e.g. "${example}"). To skip linking: reply "no links". ` +
+        `(Agent-inferred IDs are blocked by auto-mode; user-named IDs pass — DEV-4494.)`);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enrichlayer/el-linear",
-  "version": "1.25.0",
+  "version": "1.27.0",
   "description": "A pragmatic CLI for Linear.app — deterministic team/label/member resolution, structured issue validation, configurable term enforcement, and a GraphQL escape hatch.",
   "main": "dist/main.js",
   "types": "dist/main.d.ts",