@enrichlayer/el-linear 1.26.0 → 1.28.0

package/README.md

@@ -247,6 +247,16 @@ A full reference with every key documented lives in [config.example.json](./conf
 UUIDs come from the Linear UI (URL bars, settings pages) or via el-linear
 itself: `el-linear teams list --raw | jq '.[] | {key, id}'`, etc.
 
+### Gate telemetry (optional)
+
+`issues create` has a duplicate-detection gate. el-linear can record each
+fire/override decision to a local JSONL file so you can measure the gate's
+**override-rate** and tell whether it's too aggressive. It is **off by default**
+and writes nothing unless you opt in (e.g. `export EL_TELEMETRY_DIR=<path>`);
+there is no server or database, and `EL_TELEMETRY_DISABLED=1` forces it off.
+Full opt-in rules, the event schema, and a `jq` reader are in
+[docs/telemetry.md](./docs/telemetry.md).
+
 ### Networking (IPv4 preference)
 
 el-linear talks only to `api.linear.app` (Cloudflare, dual-stack). On a network

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,8 +6,10 @@ 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 { emitGateEvent } from "../utils/gate-telemetry.js";
 import { createGraphQLAttachmentsService } from "../utils/graphql-attachments-service.js";
 import { createGraphQLService, } from "../utils/graphql-service.js";
 import { createIssuesService } from "../utils/issues-service-bootstrap.js";
@@ -451,6 +453,94 @@ 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 `--skip-validation` and
+ * `config.validation.duplicateDetection: false` / `validation.enabled: false`.
+ * `--allow-duplicate` does NOT skip the search — the gate still runs and, on a
+ * would-fire, records an `overridden` telemetry event (DEV-4834) before
+ * proceeding, so `el-telemetry gates` can measure the override-rate. (A blocked
+ * fire records `blocked`.) `--skip-validation` is a blanket bypass and emits
+ * nothing — it's not a gate-specific override, so counting it would dilute the
+ * signal. 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.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) {
+        // The "pass --allow-duplicate" hint only makes sense when the caller
+        // hasn't already passed it (under --allow-duplicate we ran the search
+        // only to detect a would-fire for telemetry, and we proceed regardless).
+        const silenceHint = options.allowDuplicate
+            ? ""
+            : " Pass --allow-duplicate to silence.";
+        outputWarning(`Duplicate-detection search failed (${err instanceof Error ? err.message : String(err)}); proceeding without the dup check.${silenceHint}`);
+        return;
+    }
+    if (!Array.isArray(candidates) || candidates.length === 0) {
+        return;
+    }
+    const matches = scoreDuplicateCandidates(title, candidates, threshold);
+    if (matches.length === 0) {
+        return;
+    }
+    // The gate would fire. Record the decision so `el-telemetry gates` can
+    // compute override-rate (DEV-4834): `overridden` when the user passed
+    // --allow-duplicate and we proceed anyway, `blocked` when we stop creation.
+    const gateEvent = {
+        gate: "issues-create-dup",
+        topScore: matches[0].score,
+        candidateCount: matches.length,
+    };
+    if (options.allowDuplicate) {
+        await emitGateEvent("el-linear", "issues create", {
+            ...gateEvent,
+            outcome: "overridden",
+        });
+        return;
+    }
+    await emitGateEvent("el-linear", "issues create", {
+        ...gateEvent,
+        outcome: "blocked",
+    });
+    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 +556,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 +1112,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,76 @@
+/**
+ * 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 English stopwords, tool-name /
+ * CLI-scaffolding boilerplate (DEV-4830), 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,187 @@
+/**
+ * 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",
+]);
+/**
+ * Tool-name and CLI-scaffolding boilerplate — DEV-4830. These tokens appear in
+ * a large fraction of this workspace's titles ("Add --X flag to el-linear
+ * issues create", "… el-git pipeline watch", …) regardless of topic, so they
+ * inflate Jaccard between genuinely-distinct issues that merely touch the same
+ * command surface. A retrospective precision sweep over 288 DEV titles showed
+ * the "Add --X flag to el-linear issues create" family scoring 0.45–0.60 (all
+ * false positives) purely on shared boilerplate; dropping these tokens pushes
+ * that family to 0.17–0.25 while every genuine duplicate stayed ≥ 0.35 (the
+ * motivating DEV-4816↔DEV-4818 pair holds at 0.40). Total fires 29 → 19.
+ *
+ * Note the el-tool prefixes split on `-` first, so `el-linear` arrives here as
+ * `el` + `linear`; both fragments are listed. Topical words that happen to be
+ * tool *suffixes* (`research`, `telemetry`, `audit`, …) are deliberately NOT
+ * listed — they carry real signal in non-tool issues.
+ */
+const BOILERPLATE_STOPWORDS = new Set([
+    "el",
+    "cli",
+    "command",
+    "commands",
+    "subcommand",
+    "flag",
+    "flags",
+    "option",
+    "options",
+    "arg",
+    "args",
+    "linear",
+    "git",
+    "issue",
+    "issues",
+    "create",
+    "update",
+]);
+/**
+ * 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 English stopwords, tool-name /
+ * CLI-scaffolding boilerplate (DEV-4830), 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) &&
+        !BOILERPLATE_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/gate-telemetry.d.ts

@@ -0,0 +1,40 @@
+/** Resolve where the ledger lives — for a *reader* locating the file (mirrors
+ * el-telemetry's `GATE_EVENTS_PATH`). This is NOT the emit decision: it ignores
+ * the opt-in policy, so never write through it — `emitGateEvent` goes through
+ * {@link decideGateLedger}, which may veto writing entirely. */
+export declare function gateEventsPath(): string;
+/**
+ * Decide whether gate telemetry is enabled and, if so, the ledger path —
+ * returning `null` (no-op) otherwise. Pure (no env / fs reads) so the opt-in
+ * policy is exhaustively testable.
+ *
+ * Policy (open-source-safe):
+ * - `disabled` (`EL_TELEMETRY_DISABLED`) → off. Hard opt-out, wins over all.
+ * - `explicitDir` (`EL_TELEMETRY_DIR` set) → on. An explicit destination is an
+ *   explicit opt-in; the dir is created on demand.
+ * - otherwise → on **only if the default dir already exists**, i.e. the user
+ *   already runs the EL telemetry tooling that created it. A fresh open-source
+ *   install has no such dir, so nothing is ever written for them.
+ */
+export declare function decideGateLedger(opts: {
+    disabled: boolean;
+    explicitDir?: string;
+    defaultDir: string;
+    defaultDirExists: boolean;
+}): string | null;
+export interface GateEvent {
+    /** Stable gate id, e.g. `issues-create-dup`. */
+    gate: string;
+    outcome: "blocked" | "overridden";
+    /** Highest candidate similarity that triggered the gate (0–1). */
+    topScore?: number;
+    /** How many candidates crossed the threshold. */
+    candidateCount?: number;
+}
+/**
+ * Best-effort append of a gate event to the local ledger — but only when
+ * telemetry is opted in ({@link gateLedgerIfEnabled}); otherwise a silent
+ * no-op, so an open-source install with no telemetry writes nothing. **Never
+ * throws** — telemetry must not block issue creation.
+ */
+export declare function emitGateEvent(name: string, subcommand: string, event: GateEvent): Promise<void>;

package/dist/utils/gate-telemetry.js

@@ -0,0 +1,100 @@
+import { existsSync } from "node:fs";
+import { appendFile, mkdir } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+/**
+ * Deterministic-gate fire/override telemetry (DEV-4834, sub of DEV-4831).
+ *
+ * The `issues create` duplicate-detection gate (DEV-4823) records each decision
+ * it makes as a `gate` event so a reader (the Enrich Layer `el-telemetry gates`
+ * command, or any JSONL consumer) can compute the gate's override-rate
+ * (overridden / total) and tell whether the threshold is noisy.
+ *
+ * **Opt-in.** el-linear is open-source; most installs have no telemetry, and we
+ * must never write files a user didn't ask for. Emission is therefore OFF by
+ * default and turns on only when telemetry is actually configured — see
+ * {@link decideGateLedger}. The ledger is a plain local JSONL file
+ * (`gate-events.jsonl`); there is no server or database. el-linear can't import
+ * `el-telemetry` (separate package), so it writes by **path-contract** — the
+ * same approach `el-hook` uses. The path mirrors `el-telemetry`'s
+ * `GATE_EVENTS_PATH`; keep the two in sync. Format + reader are documented in
+ * `docs/telemetry.md`.
+ */
+/** The default ledger directory when `EL_TELEMETRY_DIR` is not set. */
+function defaultTelemetryDir() {
+    return join(homedir(), ".cache", "el-telemetry");
+}
+/** Resolve where the ledger lives — for a *reader* locating the file (mirrors
+ * el-telemetry's `GATE_EVENTS_PATH`). This is NOT the emit decision: it ignores
+ * the opt-in policy, so never write through it — `emitGateEvent` goes through
+ * {@link decideGateLedger}, which may veto writing entirely. */
+export function gateEventsPath() {
+    const dir = process.env.EL_TELEMETRY_DIR || defaultTelemetryDir();
+    return join(dir, "gate-events.jsonl");
+}
+/**
+ * Decide whether gate telemetry is enabled and, if so, the ledger path —
+ * returning `null` (no-op) otherwise. Pure (no env / fs reads) so the opt-in
+ * policy is exhaustively testable.
+ *
+ * Policy (open-source-safe):
+ * - `disabled` (`EL_TELEMETRY_DISABLED`) → off. Hard opt-out, wins over all.
+ * - `explicitDir` (`EL_TELEMETRY_DIR` set) → on. An explicit destination is an
+ *   explicit opt-in; the dir is created on demand.
+ * - otherwise → on **only if the default dir already exists**, i.e. the user
+ *   already runs the EL telemetry tooling that created it. A fresh open-source
+ *   install has no such dir, so nothing is ever written for them.
+ */
+export function decideGateLedger(opts) {
+    if (opts.disabled) {
+        return null;
+    }
+    if (opts.explicitDir) {
+        return join(opts.explicitDir, "gate-events.jsonl");
+    }
+    if (!opts.defaultDirExists) {
+        return null;
+    }
+    return join(opts.defaultDir, "gate-events.jsonl");
+}
+/** Wire {@link decideGateLedger} to the real environment + filesystem. */
+function gateLedgerIfEnabled() {
+    const defaultDir = defaultTelemetryDir();
+    return decideGateLedger({
+        disabled: Boolean(process.env.EL_TELEMETRY_DISABLED),
+        explicitDir: process.env.EL_TELEMETRY_DIR,
+        defaultDir,
+        defaultDirExists: existsSync(defaultDir),
+    });
+}
+/**
+ * Best-effort append of a gate event to the local ledger — but only when
+ * telemetry is opted in ({@link gateLedgerIfEnabled}); otherwise a silent
+ * no-op, so an open-source install with no telemetry writes nothing. **Never
+ * throws** — telemetry must not block issue creation.
+ */
+export async function emitGateEvent(name, subcommand, event) {
+    const path = gateLedgerIfEnabled();
+    if (!path) {
+        return;
+    }
+    try {
+        await mkdir(dirname(path), { recursive: true });
+        const record = {
+            ts: new Date().toISOString(),
+            kind: "gate",
+            name,
+            subcommand,
+            metadata: {
+                gate: event.gate,
+                outcome: event.outcome,
+                top_score: event.topScore,
+                candidate_count: event.candidateCount,
+            },
+        };
+        await appendFile(path, `${JSON.stringify(record)}\n`, "utf8");
+    }
+    catch {
+        // best-effort — telemetry never blocks issue creation
+    }
+}

package/package.json

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