@enrichlayer/el-linear 1.27.0 → 1.29.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/batch.js

@@ -1,4 +1,4 @@
-import { resolveAssignee, resolveLabels, resolveMember, resolveTeam, } from "../config/resolver.js";
+import { resolveAssignee, resolveLabels, resolveMemberWithRegistry, resolveTeam, } from "../config/resolver.js";
 import { createIssuesService } from "../utils/issues-service-bootstrap.js";
 import { logger } from "../utils/logger.js";
 import { handleAsyncCommand, outputSuccess, outputWarning, } from "../utils/output.js";
@@ -45,7 +45,7 @@ async function resolveTargetIssues(options, rootOpts) {
                 ? await resolveAssignee(filters.assignee, rootOpts)
                 : undefined,
             delegateId: filters.delegate
-                ? resolveMember(filters.delegate)
+                ? await resolveMemberWithRegistry(filters.delegate)
                 : undefined,
             project: filters.project
                 ? { kind: "id", id: filters.project }

package/dist/commands/issues.js

@@ -2,13 +2,14 @@ import { execFileSync } from "node:child_process";
 import { loadConfig } from "../config/config.js";
 import { enrichProjectResolverError, enrichValidationErrors, } from "../config/error-enrichment.js";
 import { enforceValidation, validateIssueCreation, } from "../config/issue-validation.js";
-import { resolveAssignee, resolveLabels, resolveMember, resolveTeam, } from "../config/resolver.js";
+import { resolveAssignee, resolveLabels, resolveMemberWithRegistry, resolveTeam, } from "../config/resolver.js";
 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";
@@ -209,7 +210,7 @@ async function handleListIssues(options, command) {
                 ? await resolveAssignee(options.assignee, rootOpts)
                 : undefined,
             delegateId: options.delegate
-                ? resolveMember(options.delegate)
+                ? await resolveMemberWithRegistry(options.delegate)
                 : undefined,
             project: resolveProjectFlag(options.project),
             labelNames: options.labels ? splitList(options.labels) : undefined,
@@ -255,7 +256,7 @@ async function handleSearchIssues(query, options, command) {
             ? await resolveAssignee(options.assignee, rootOpts)
             : undefined,
         delegateId: options.delegate
-            ? resolveMember(options.delegate)
+            ? await resolveMemberWithRegistry(options.delegate)
             : undefined,
         project: resolveProjectFlag(options.project),
         status: explicitStatus,
@@ -383,7 +384,7 @@ async function resolveCreateInputs(title, options, rootOpts) {
         ? await resolveAssignee(effectiveAssignee, rootOpts)
         : undefined;
     const delegateId = options.delegate
-        ? resolveMember(options.delegate)
+        ? await resolveMemberWithRegistry(options.delegate)
         : undefined;
     let labelIds = [];
     if (options.labels) {
@@ -406,7 +407,10 @@ async function resolveCreateInputs(title, options, rootOpts) {
     });
     let subscriberIds;
     if (options.subscriber) {
-        subscriberIds = splitList(options.subscriber).map((s) => resolveMember(s));
+        // --subscriber resolves through the opt-in registry too (DEV-4880),
+        // matching --assignee / --delegate. Each entry falls back to config on a
+        // miss; resolveMemberWithRegistry is fail-open and dormant when unconfigured.
+        subscriberIds = await Promise.all(splitList(options.subscriber).map((s) => resolveMemberWithRegistry(s)));
     }
     const priority = effectivePriorityInput
         ? validatePriority(effectivePriorityInput)
@@ -458,13 +462,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 +507,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 +523,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) {
@@ -812,7 +846,7 @@ async function handleUpdateIssue(issueId, options, command) {
     const delegateId = options.clearDelegate
         ? null
         : options.delegate
-            ? resolveMember(options.delegate)
+            ? await resolveMemberWithRegistry(options.delegate)
             : undefined;
     const updateArgs = buildUpdateArgs(issueId, options, assigneeId, delegateId);
     const result = await withProjectResolverEnrichment(() => issuesService.updateIssue(updateArgs, options.labelBy || "adding"), {

package/dist/config/registry-resolve.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Optional, opt-in resolution against the company-wide identity registry
+ * (DEV-4827 / DEV-4871). EL-only: this activates **solely** when
+ * `EL_IDENTITY_URL` is set. el-linear is MIT/open-source — a non-EL install
+ * leaves this dormant (no network, no config, nothing written), and the package
+ * never takes a dependency on EL-internal infrastructure. It mirrors the
+ * env-gated CF-Access pattern of the tools `@enrichlayer/el-identity` client but
+ * is kept self-contained so the OSS package carries no private dependency.
+ *
+ * The registry is an *enhancement* for EL users: callers try it first, then fall
+ * back to the bundled config (`resolveMember`). It must never throw or break a
+ * command because the registry is unreachable.
+ */
+/** True only when the registry is explicitly configured (opt-in). */
+export declare function isRegistryConfigured(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Resolve any identifier (alias, handle, email, name, Linear UUID) to a Linear
+ * UUID via the registry's `GET /api/people/resolve`. Returns `null` when the
+ * registry is not configured, when nothing matches, or on **any** failure
+ * (unreachable / timeout / CF-Access challenge / malformed response) — the
+ * caller falls back to the config-based resolver. Never throws.
+ */
+export declare function resolveViaRegistry(identifier: string, env?: NodeJS.ProcessEnv, fetchImpl?: typeof fetch): Promise<string | null>;

package/dist/config/registry-resolve.js

@@ -0,0 +1,59 @@
+/**
+ * Optional, opt-in resolution against the company-wide identity registry
+ * (DEV-4827 / DEV-4871). EL-only: this activates **solely** when
+ * `EL_IDENTITY_URL` is set. el-linear is MIT/open-source — a non-EL install
+ * leaves this dormant (no network, no config, nothing written), and the package
+ * never takes a dependency on EL-internal infrastructure. It mirrors the
+ * env-gated CF-Access pattern of the tools `@enrichlayer/el-identity` client but
+ * is kept self-contained so the OSS package carries no private dependency.
+ *
+ * The registry is an *enhancement* for EL users: callers try it first, then fall
+ * back to the bundled config (`resolveMember`). It must never throw or break a
+ * command because the registry is unreachable.
+ */
+const URL_ENV = "EL_IDENTITY_URL";
+const CF_ID_ENV = "EL_IDENTITY_CF_ACCESS_CLIENT_ID";
+const CF_SECRET_ENV = "EL_IDENTITY_CF_ACCESS_CLIENT_SECRET";
+const TIMEOUT_MS = 8000;
+/** True only when the registry is explicitly configured (opt-in). */
+export function isRegistryConfigured(env = process.env) {
+    return Boolean(env[URL_ENV]?.trim());
+}
+/**
+ * Resolve any identifier (alias, handle, email, name, Linear UUID) to a Linear
+ * UUID via the registry's `GET /api/people/resolve`. Returns `null` when the
+ * registry is not configured, when nothing matches, or on **any** failure
+ * (unreachable / timeout / CF-Access challenge / malformed response) — the
+ * caller falls back to the config-based resolver. Never throws.
+ */
+export async function resolveViaRegistry(identifier, env = process.env, fetchImpl = fetch) {
+    const base = env[URL_ENV]?.trim();
+    if (!base) {
+        return null;
+    }
+    const headers = { Accept: "application/json" };
+    const cfId = env[CF_ID_ENV];
+    const cfSecret = env[CF_SECRET_ENV];
+    if (cfId && cfSecret) {
+        headers["CF-Access-Client-Id"] = cfId;
+        headers["CF-Access-Client-Secret"] = cfSecret;
+    }
+    const url = `${base.replace(/\/+$/, "")}/api/people/resolve?identifier=${encodeURIComponent(identifier)}`;
+    try {
+        const res = await fetchImpl(url, {
+            headers,
+            // A 3xx is a Cloudflare Access SSO bounce, not a result — `redirect:
+            // "manual"` surfaces it as a non-ok status we treat as a miss.
+            redirect: "manual",
+            signal: AbortSignal.timeout(TIMEOUT_MS),
+        });
+        if (!res.ok) {
+            return null;
+        }
+        const record = (await res.json());
+        return record?.linearId ?? null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/config/resolver.d.ts

@@ -13,6 +13,17 @@ export declare function resolveMember(input: string): string;
  * Falls back to resolveMember for all other inputs.
  */
 export declare function resolveAssignee(input: string, rootOpts: Record<string, unknown>): Promise<string>;
+/**
+ * Resolve a member identifier (alias / handle / name) to a UUID, consulting the
+ * opt-in identity registry first when configured, then the bundled config
+ * (`resolveMember`). The shared async resolution path behind `--assignee` and
+ * `--delegate` (DEV-4871 / DEV-4872).
+ *
+ * EL-only and env-gated on `EL_IDENTITY_URL`; fail-open — when unconfigured, on
+ * a miss, or on any failure it falls back to config, so a non-EL install and an
+ * unreachable registry both behave exactly as before. Never throws.
+ */
+export declare function resolveMemberWithRegistry(input: string): Promise<string>;
 /**
  * Resolve a user's display name from their UUID via config fullNames map.
  * Returns the full name if found, otherwise returns the original name.

package/dist/config/resolver.js

@@ -2,6 +2,7 @@ import { createGraphQLService } from "../utils/graphql-service.js";
 import { outputWarning } from "../utils/output.js";
 import { isUuid, isUuidPrefix } from "../utils/uuid.js";
 import { loadConfig } from "./config.js";
+import { isRegistryConfigured, resolveViaRegistry, } from "./registry-resolve.js";
 /**
  * Resolve a team key/name/alias to its UUID.
  * Case-insensitive: "fe" → FE UUID, "frontend" → FE UUID via alias.
@@ -98,6 +99,25 @@ export async function resolveAssignee(input, rootOpts) {
         }
         return result.viewer.id;
     }
+    return resolveMemberWithRegistry(input);
+}
+/**
+ * Resolve a member identifier (alias / handle / name) to a UUID, consulting the
+ * opt-in identity registry first when configured, then the bundled config
+ * (`resolveMember`). The shared async resolution path behind `--assignee` and
+ * `--delegate` (DEV-4871 / DEV-4872).
+ *
+ * EL-only and env-gated on `EL_IDENTITY_URL`; fail-open — when unconfigured, on
+ * a miss, or on any failure it falls back to config, so a non-EL install and an
+ * unreachable registry both behave exactly as before. Never throws.
+ */
+export async function resolveMemberWithRegistry(input) {
+    if (isRegistryConfigured()) {
+        const viaRegistry = await resolveViaRegistry(input);
+        if (viaRegistry) {
+            return viaRegistry;
+        }
+    }
     return resolveMember(input);
 }
 /**

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/dist/utils/graphql-issues-service.js

@@ -1,3 +1,4 @@
+import { isRegistryConfigured, resolveViaRegistry, } from "../config/registry-resolve.js";
 import { resolveUserDisplayName } from "../config/resolver.js";
 import { ARCHIVE_ISSUE_MUTATION, BATCH_GET_ISSUES_QUERY, BATCH_RESOLVE_FOR_CREATE_QUERY, BATCH_RESOLVE_FOR_SEARCH_QUERY, BATCH_RESOLVE_FOR_UPDATE_QUERY, buildResolveLabelsByNameQuery, CREATE_ISSUE_MUTATION, DELETE_ISSUE_MUTATION, FILTERED_SEARCH_ISSUES_QUERY, GET_ISSUE_BY_ID_QUERY, GET_ISSUE_BY_IDENTIFIER_QUERY, GET_ISSUE_CLAIM_CONTEXT_QUERY, GET_ISSUE_START_CONTEXT_QUERY, GET_ISSUE_TEAM_QUERY, GET_ISSUES_QUERY, SEARCH_ISSUES_QUERY, TEAM_STARTED_STATUSES_QUERY, UPDATE_ISSUE_MUTATION, } from "../queries/issues.js";
 import { CREATE_LABEL_MUTATION } from "../queries/labels.js";
@@ -1048,6 +1049,15 @@ export class GraphQLIssuesService {
         if (!assigneeId || isUuid(assigneeId)) {
             return assigneeId;
         }
+        // Opt-in registry resolution (DEV-4872): try the identity registry first,
+        // falling back to the Linear-API user lookup below on a miss. EL-only,
+        // env-gated, fail-open — a non-EL install never reaches the network here.
+        if (isRegistryConfigured()) {
+            const viaRegistry = await resolveViaRegistry(assigneeId);
+            if (viaRegistry) {
+                return viaRegistry;
+            }
+        }
         // A plain name (no `@`) resolves via the user lookup — same as
         // `resolveDelegateId`. Without this, a non-config full name like
         // "Yury Tsukerman" fell through unchanged and was sent to the
@@ -1068,6 +1078,14 @@ export class GraphQLIssuesService {
         if (!delegateId || isUuid(delegateId)) {
             return delegateId;
         }
+        // Opt-in registry resolution (DEV-4872): registry-first, Linear-API
+        // fallback. EL-only, env-gated, fail-open.
+        if (isRegistryConfigured()) {
+            const viaRegistry = await resolveViaRegistry(delegateId);
+            if (viaRegistry) {
+                return viaRegistry;
+            }
+        }
         if (!delegateId.includes("@")) {
             return this.linearService.resolveUserId(delegateId);
         }

package/package.json

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