@enrichlayer/el-linear 1.26.0 → 1.27.0

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
 ```
 
@@ -186,17 +202,15 @@ el-linear issues search "keywords from proposed title" --include-closed 2>&1
 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. Treat it as a hard step,
-not a hint:
-
-1. **Surface the IDs to the user verbatim.** Show the `relation_candidates:`
-   line (or paraphrase it preserving every ID + the example reply). Do **not**
-   skip ahead to `issues relate`.
-2. **Wait for an explicit reply naming the IDs to link** (e.g. `link DEV-2134
-   and ALL-672`) or a clear skip (`no links`).
-3. **Only the user-named IDs** go into the next `el-linear issues relate
-   <source> --related-to "<ids>"` call. Never pass IDs the user did not name,
-   even if your earlier search obviously surfaced them.
+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*

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";
@@ -451,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);
@@ -466,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.
@@ -1009,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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enrichlayer/el-linear",
-  "version": "1.26.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",