@enrichlayer/el-linear 1.27.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/dist/commands/issues.js

@@ -9,6 +9,7 @@ import { GET_ISSUE_RELATIONS_QUERY, GET_ISSUE_STATE_HISTORY_QUERY, } from "../qu
 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";
@@ -458,13 +459,18 @@ function buildDescriptionWithAttachments(baseDescription, uploadResults) {
  * title-overlap, and throws — listing the matches — when one is at/above the
  * configured similarity threshold.
  *
- * Bypassed by `--allow-duplicate`, `--skip-validation`, and
+ * Bypassed by `--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.
+ * `--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.allowDuplicate || options.skipValidation) {
+    if (options.skipValidation) {
         return;
     }
     const validation = loadConfig().validation;
@@ -498,7 +504,13 @@ async function enforceNoDuplicateIssue(title, options, issuesService) {
         });
     }
     catch (err) {
-        outputWarning(`Duplicate-detection search failed (${err instanceof Error ? err.message : String(err)}); proceeding without the dup check. Pass --allow-duplicate to silence.`);
+        // 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) {
@@ -508,6 +520,25 @@ async function enforceNoDuplicateIssue(title, options, issuesService) {
     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) {

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

@@ -45,9 +45,10 @@ export interface DuplicateCandidate {
  * 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.
+ * `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

package/dist/utils/duplicate-detection.js

@@ -68,13 +68,49 @@ const STOPWORDS = new Set([
     "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 stopwords, pure numbers
- * (`52 files` → `files`), and single-character tokens. Returns a Set so
- * downstream set algebra is direct.
+ * `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
@@ -85,7 +121,10 @@ export function tokenizeTitle(title) {
     const tokens = title
         .toLowerCase()
         .split(/[^a-z0-9]+/)
-        .filter((t) => t.length >= 2 && !STOPWORDS.has(t) && !/^\d+$/.test(t));
+        .filter((t) => t.length >= 2 &&
+        !STOPWORDS.has(t) &&
+        !BOILERPLATE_STOPWORDS.has(t) &&
+        !/^\d+$/.test(t));
     return new Set(tokens);
 }
 /**

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.27.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",