@enrichlayer/el-linear 1.41.0 → 1.42.0

package/dist/commands/issues.js

@@ -9,7 +9,7 @@ import { formatSopParentBlock, getSopLabelGateConfig, hasSopLabel, isUnresolvabl
 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, DEFAULT_HARD_BLOCK_THRESHOLD, formatDuplicateBlock, scoreDuplicateCandidates, tokenizeTitle, } from "../utils/duplicate-detection.js";
+import { bypassesDuplicateHardBlock, DEFAULT_DUPLICATE_THRESHOLD, DEFAULT_HARD_BLOCK_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";
@@ -589,7 +589,12 @@ async function enforceNoDuplicateIssue(title, options, issuesService) {
     // The gate would hard-block. 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.
-    if (options.allowDuplicate) {
+    //
+    // The escape set lives in `bypassesDuplicateHardBlock` rather than inline so
+    // the remedy copy in `formatDuplicateBlock` is derived from the same source
+    // this decision reads (DEV-6205 — the message previously named a flag the
+    // gate never consulted).
+    if (bypassesDuplicateHardBlock(options)) {
         await emitGateEvent("el-linear", "issues create", {
             ...gateEvent,
             outcome: "overridden",

package/dist/commands/read-shortcut.js

@@ -73,14 +73,21 @@ export async function readIssues(issueIds, options, command) {
     const rootOpts = getRootOpts(command);
     const { graphQLService, issuesService } = await createIssuesService(rootOpts);
     const fileService = await createFileService(rootOpts);
-    const fieldName = typeof options.field === "string" ? options.field : null;
-    const bodyOnly = options.body === true;
-    const sectionsRaw = typeof options.sections === "string" ? options.sections : null;
+    // `issues` owns these options for its no-subcommand shorthand, while
+    // `issues read` registers the same options on the child command. Commander
+    // stores a duplicated flag on the parent even when it appears after `read`,
+    // so the action callback's local options can be empty. Merge the command
+    // hierarchy here, with local values winning, so every read route shares the
+    // same deterministic option contract.
+    const readOptions = { ...command.optsWithGlobals(), ...options };
+    const fieldName = typeof readOptions.field === "string" ? readOptions.field : null;
+    const bodyOnly = readOptions.body === true;
+    const sectionsRaw = typeof readOptions.sections === "string" ? readOptions.sections : null;
     // DEV-4476: --with opt-in includes (currently `relations`). Throws on
     // unknown values via parseWithIncludes — fail fast in the CLI per the
     // deterministic-CLI doctrine.
-    const includes = typeof options.with === "string"
-        ? parseWithIncludes(options.with)
+    const includes = typeof readOptions.with === "string"
+        ? parseWithIncludes(readOptions.with)
         : { relations: false };
     if (fieldName && sectionsRaw) {
         throw new Error("--field and --sections are mutually exclusive. Use --field for a single section (plain-text output) or --sections for multiple (JSON map).");

package/dist/config/config.d.ts

@@ -36,6 +36,31 @@ export interface ElLinearConfig {
     };
     teamAliases: Record<string, string>;
     teams: Record<string, string>;
+    /**
+     * Optional identity-resolver hook (DEV-5628). `resolver` is an argv array —
+     * el-linear appends the identifier as the final element and reads a Linear
+     * user UUID off stdout:
+     *
+     *   "identity": { "resolver": ["el-identity", "resolve"] }
+     *
+     * Use it when your org has a people registry that knows things Linear does
+     * not (that `jd` is a person; that a GitLab handle and a Linear handle are one human).
+     *
+     * It is a COMMAND rather than a URL + credentials on purpose: el-linear is
+     * MIT and most installs are not ours, so it must not bake in anybody's auth
+     * scheme. The credential lives entirely inside whatever you point this at —
+     * Vault, Infisical, 1Password, a plain env var, SSO. Adding a backend is
+     * writing a different script, not patching this package.
+     *
+     * Entirely optional and fail-open: unconfigured, or on any failure,
+     * resolution falls through to Linear's own user lookup exactly as before.
+     * See `identity-resolver.ts` for the output contract.
+     */
+    identity?: {
+        resolver?: string[];
+        /** Milliseconds before the resolver is treated as a miss (default 8000). */
+        resolverTimeoutMs?: number;
+    };
     /**
      * Term-enforcement rules. Each rule has a canonical form and a list of
      * rejected forms; rejected forms in issue titles/descriptions are flagged

package/dist/config/config.js

@@ -139,6 +139,21 @@ export function loadConfig() {
         : {};
     // teamConfigPath inside a team config file would be circular; strip it.
     delete teamRaw.teamConfigPath;
+    // `identity.resolver` names a BINARY el-linear will spawn. The team layer is
+    // data, not code: it arrives from a different repository via `git pull` (or,
+    // for an OSS user, from whatever repo they pointed `teamConfigPath` at), and
+    // nobody reviews a config file expecting it to hand them a subprocess. Letting
+    // it choose the executable would turn "clone this repo and run el-linear" into
+    // arbitrary code execution on every `--assignee` resolution.
+    //
+    // So the resolver is honored ONLY from the personal config (or the env var) —
+    // files the operator owns. Same reasoning as teamConfigPath above, which is
+    // stripped for the same "the team layer doesn't get to decide this" reason.
+    //
+    // An organization that wants to ship a resolver to its developers writes it
+    // into their personal config at setup time; that keeps the decision with the
+    // machine's owner instead of with whoever can land a commit upstream.
+    delete teamRaw.identity;
     // Merge order: defaults → team config → personal config.
     // Arrays (terms, defaultLabels, etc.) are concatenated so personal entries
     // extend team entries rather than replace them.

package/dist/config/identity-resolver.d.ts

@@ -0,0 +1,40 @@
+import type { ElLinearConfig } from "./config.js";
+/** Test seam — the memo would otherwise leak between cases in one vitest process. */
+export declare function clearResolverMemoForTests(): void;
+/**
+ * The configured resolver argv, or `null` when the hook is off.
+ *
+ * Env wins over config so a single invocation can point at a different resolver
+ * (or disable one) without editing files: `EL_LINEAR_IDENTITY_RESOLVER=""` is an
+ * explicit off switch.
+ */
+export declare function resolverCommand(config: Pick<ElLinearConfig, "identity">, env?: NodeJS.ProcessEnv): string[] | null;
+/** True when an identity resolver is configured (env or config). */
+export declare function isResolverConfigured(config: Pick<ElLinearConfig, "identity">, env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Pull a Linear user UUID out of whatever the resolver printed.
+ *
+ * Deliberately generous about the shape, because the point of this hook is that
+ * anyone can write the resolver — demanding one exact JSON envelope would make
+ * the "just shell out to your own script" promise a lie. Accepted:
+ *
+ *   - a bare UUID:                     `3f2a…`
+ *   - `{"linearId": "3f2a…"}`     (the el-identity record shape)
+ *   - `{"data": {"linearId": "…"}}`    (an el-* CLI `{data, meta}` envelope)
+ *   - `{"id": "3f2a…"}`           (the obvious alternative spelling)
+ *
+ * Anything else — including a *non*-UUID string, which is the shape a confused
+ * resolver most plausibly emits — is a miss. We would rather fall through to
+ * Linear's own lookup than hand a bogus id to the API and produce an opaque
+ * "Argument Validation Error" (the DEV-4312 failure, in a new costume).
+ */
+export declare function parseResolverOutput(stdout: string): string | null;
+/**
+ * Run the configured resolver for `identifier`. Returns the Linear user UUID, or
+ * `null` on any miss/failure. Never throws.
+ *
+ * Synchronous (`spawnSync`) on purpose: resolution sits on the critical path of
+ * `--assignee` for a short-lived CLI, the callers are already `async` so nothing
+ * is starved, and it keeps the failure modes to exactly one place.
+ */
+export declare function resolveViaCommand(identifier: string, config: Pick<ElLinearConfig, "identity">, env?: NodeJS.ProcessEnv): string | null;

package/dist/config/identity-resolver.js

@@ -0,0 +1,253 @@
+import { spawnSync } from "node:child_process";
+/**
+ * Optional **identity resolver hook** (DEV-5628).
+ *
+ * Some organizations keep a people registry that knows things Linear does not:
+ * that `jd` is a person, that a GitLab handle and a Linear handle belong to the
+ * same human. el-linear can consult it — but it must never learn *how* to reach it.
+ *
+ * So the hook is a **command**, not an HTTP client:
+ *
+ *   identity.resolver = ["el-identity", "resolve"]
+ *
+ * el-linear appends the identifier as the final argv element, runs the command,
+ * and reads a Linear user UUID off stdout. That is the entire contract.
+ *
+ * Why a command rather than a URL + credentials (which is what
+ * `registry-resolve.ts` does, and why that path stayed dormant): el-linear is
+ * MIT and published on npm. Most installs are not Enrich Layer. Baking in an
+ * auth scheme means baking in *somebody's* auth scheme — and the moment we did,
+ * the next organization would need Infisical, or 1Password, or a plain env var,
+ * or SSO. A command has no such problem: the credential lives entirely inside
+ * whatever the operator points this at. Adding a new secret backend is writing a
+ * different script, not patching this package.
+ *
+ * The command is trusted (the operator configured it) but the *identifier* is
+ * not, so it is passed as an argv element with `shell: false` — a name like
+ * `"; rm -rf /"` is an argument, never a command.
+ *
+ * Fail-open by design: unconfigured, a miss, a non-zero exit, a timeout, an
+ * unparseable answer, or a missing binary all return `null`, and the caller
+ * falls through to Linear's own user lookup (which resolves names and emails
+ * perfectly well — see `LinearService.resolveUserId`). This hook is an
+ * *enhancement*, so a broken resolver must degrade to plain el-linear rather
+ * than break every command. It never throws.
+ */
+/** Env override — a whitespace-separated command, e.g. `el-identity resolve`. */
+const RESOLVER_ENV = "EL_LINEAR_IDENTITY_RESOLVER";
+/** A resolver that hasn't answered in this long is not going to. */
+const DEFAULT_TIMEOUT_MS = 8000;
+/**
+ * Per-process memo. A single command can resolve the same person several times —
+ * `--subscriber a,b,a`, or an assignee who is also a subscriber — and each miss
+ * costs a full subprocess round-trip (seconds, against a network-backed
+ * resolver). Nothing here is cached across processes: el-linear is short-lived,
+ * and a stale identity cache on disk is exactly the drift this hook exists to
+ * remove.
+ */
+const memo = new Map();
+/** Test seam — the memo would otherwise leak between cases in one vitest process. */
+export function clearResolverMemoForTests() {
+    memo.clear();
+}
+/**
+ * Resolve the effective timeout.
+ *
+ * `?? DEFAULT` is not enough: Node treats `timeout <= 0` as *no timeout*, and `0`
+ * is the most natural thing to type when you mean "off". That would turn the
+ * documented fail-open contract into an unkillable hang inside a synchronous
+ * call — the one failure mode the surrounding try/catch cannot save you from.
+ */
+function resolveTimeoutMs(config) {
+    const configured = config.identity?.resolverTimeoutMs;
+    return typeof configured === "number" && configured > 0
+        ? configured
+        : DEFAULT_TIMEOUT_MS;
+}
+/**
+ * The environment handed to the resolver.
+ *
+ * It inherits the ambient env on purpose — reaching its own secret backend
+ * (Vault, Infisical, 1Password, a plain env var) is the entire point, so
+ * scrubbing wholesale would defeat the design. But the resolver has no business
+ * with *Linear's* token: it resolves people, it never talks to Linear. Dropping
+ * it keeps the CLI's most sensitive secret out of the blast radius of a
+ * compromised — or merely over-logging — resolver.
+ */
+function resolverEnv(env) {
+    const { LINEAR_API_TOKEN: _dropped, ...rest } = env;
+    return rest;
+}
+/**
+ * Debug-gated diagnosis. Every failure here is a silent `null` by design, which
+ * is right for the user but miserable for the operator whose resolver is broken:
+ * all they see is an unexplained pause. `EL_LINEAR_DEBUG=1` is this repo's
+ * existing convention for "tell me what actually happened", and stderr never
+ * corrupts the JSON on stdout.
+ */
+function debugMiss(reason, env) {
+    if (!env.EL_LINEAR_DEBUG)
+        return;
+    process.stderr.write(`el-linear: identity resolver miss — ${reason}\n`);
+}
+/**
+ * The configured resolver argv, or `null` when the hook is off.
+ *
+ * Env wins over config so a single invocation can point at a different resolver
+ * (or disable one) without editing files: `EL_LINEAR_IDENTITY_RESOLVER=""` is an
+ * explicit off switch.
+ */
+export function resolverCommand(config, env = process.env) {
+    const fromEnv = env[RESOLVER_ENV];
+    if (fromEnv !== undefined) {
+        const argv = fromEnv.trim().split(/\s+/).filter(Boolean);
+        return argv.length > 0 ? argv : null;
+    }
+    const configured = config.identity?.resolver;
+    if (!configured || configured.length === 0) {
+        return null;
+    }
+    return configured;
+}
+/** True when an identity resolver is configured (env or config). */
+export function isResolverConfigured(config, env = process.env) {
+    return resolverCommand(config, env) !== null;
+}
+/**
+ * Pull a Linear user UUID out of whatever the resolver printed.
+ *
+ * Deliberately generous about the shape, because the point of this hook is that
+ * anyone can write the resolver — demanding one exact JSON envelope would make
+ * the "just shell out to your own script" promise a lie. Accepted:
+ *
+ *   - a bare UUID:                     `3f2a…`
+ *   - `{"linearId": "3f2a…"}`     (the el-identity record shape)
+ *   - `{"data": {"linearId": "…"}}`    (an el-* CLI `{data, meta}` envelope)
+ *   - `{"id": "3f2a…"}`           (the obvious alternative spelling)
+ *
+ * Anything else — including a *non*-UUID string, which is the shape a confused
+ * resolver most plausibly emits — is a miss. We would rather fall through to
+ * Linear's own lookup than hand a bogus id to the API and produce an opaque
+ * "Argument Validation Error" (the DEV-4312 failure, in a new costume).
+ */
+export function parseResolverOutput(stdout) {
+    const trimmed = stdout.trim();
+    if (!trimmed) {
+        return null;
+    }
+    if (UUID_RE.test(trimmed)) {
+        return trimmed;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(trimmed);
+    }
+    catch {
+        return null;
+    }
+    const candidate = pickLinearId(parsed);
+    return candidate && UUID_RE.test(candidate) ? candidate : null;
+}
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+function pickLinearId(parsed) {
+    if (typeof parsed === "string") {
+        return parsed;
+    }
+    if (!parsed || typeof parsed !== "object") {
+        return null;
+    }
+    const obj = parsed;
+    for (const key of ["linearId", "id"]) {
+        const value = obj[key];
+        if (typeof value === "string") {
+            return value;
+        }
+    }
+    // One level of `{data: …}` unwrapping — the el-* CLI envelope.
+    if (obj.data && typeof obj.data === "object") {
+        return pickLinearId(obj.data);
+    }
+    return null;
+}
+/**
+ * Run the configured resolver for `identifier`. Returns the Linear user UUID, or
+ * `null` on any miss/failure. Never throws.
+ *
+ * Synchronous (`spawnSync`) on purpose: resolution sits on the critical path of
+ * `--assignee` for a short-lived CLI, the callers are already `async` so nothing
+ * is starved, and it keeps the failure modes to exactly one place.
+ */
+export function resolveViaCommand(identifier, config, env = process.env) {
+    const argv = resolverCommand(config, env);
+    if (!argv) {
+        return null;
+    }
+    const [command, ...args] = argv;
+    if (!command) {
+        return null;
+    }
+    // A leading `-` is never a valid Linear identifier, but it IS a flag to the
+    // resolver's own option parser — `--assignee "--output=/tmp/x"` would be
+    // presented to it as one. There is no shell escape here (argv, not a shell),
+    // but el-linear is increasingly driven by agents over untrusted issue text, so
+    // close the class for free rather than trust every resolver to be careful.
+    if (identifier.startsWith("-")) {
+        debugMiss(`refusing flag-shaped identifier "${identifier}"`, env);
+        return null;
+    }
+    const cached = memo.get(identifier);
+    if (cached !== undefined) {
+        return cached;
+    }
+    const resolved = spawnResolver(command, args, identifier, config, env);
+    memo.set(identifier, resolved);
+    return resolved;
+}
+function spawnResolver(command, args, identifier, config, env) {
+    try {
+        const result = spawnSync(command, [...args, identifier], {
+            encoding: "utf8",
+            timeout: resolveTimeoutMs(config),
+            // `spawnSync` waits for the child to fully exit after its timeout. Its
+            // default kill signal is SIGTERM, which a broken resolver can trap or
+            // ignore forever — defeating this hook's fail-open timeout. The resolver
+            // is an isolated lookup helper, so force it down when its time budget is
+            // exhausted rather than letting it wedge the whole CLI.
+            killSignal: "SIGKILL",
+            // The identifier is untrusted input; never hand it to a shell. This also
+            // means a Windows npm shim (`el-identity.cmd`) will NOT be found — see
+            // the Windows note in docs/configuration.md. Turning `shell: true` on to
+            // fix that would hand the untrusted identifier to cmd.exe, which is a
+            // far worse trade.
+            shell: false,
+            // stdin closed: a resolver that decides to prompt must not hang the CLI.
+            stdio: ["ignore", "pipe", "pipe"],
+            env: resolverEnv(env),
+        });
+        // BOTH conditions are load-bearing; do not "simplify" this to one.
+        //   - a plain timeout      → error ETIMEDOUT, status null
+        //   - a maxBuffer overflow → error ENOBUFS,   status null
+        //   - a child that leaves a grandchild holding the stdout pipe
+        //                          → error ETIMEDOUT, status **0**
+        // Checking only `status` would let that last case through as a success and
+        // parse whatever partial output happened to be buffered.
+        if (result.error) {
+            debugMiss(`${command}: ${result.error.message}`, env);
+            return null;
+        }
+        if (result.status !== 0) {
+            const stderr = (result.stderr ?? "").trim().split("\n")[0] ?? "";
+            debugMiss(`${command} exited ${result.status}${stderr ? `: ${stderr}` : ""}`, env);
+            return null;
+        }
+        const parsed = parseResolverOutput(result.stdout ?? "");
+        if (!parsed) {
+            debugMiss(`${command} printed no usable Linear UUID for "${identifier}"`, env);
+        }
+        return parsed;
+    }
+    catch (err) {
+        debugMiss(err instanceof Error ? err.message : String(err), env);
+        return null;
+    }
+}

package/dist/config/resolver.d.ts

@@ -14,14 +14,29 @@ export declare function resolveMember(input: string): string;
  */
 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).
+ * Resolve a member identifier (alias / handle / name) to a UUID. The shared
+ * async resolution path behind `--assignee` and `--delegate` (DEV-4871 /
+ * DEV-4872 / DEV-5628).
  *
- * 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.
+ * Order, most authoritative first:
+ *
+ *   1. **The identity-resolver hook** (`identity.resolver`, DEV-5628) — an
+ *      operator-supplied command. This is the one to reach for: it can answer
+ *      for aliases and cross-system handles Linear has never heard of, and it
+ *      owns its own credentials, so el-linear carries no auth scheme.
+ *   2. **The HTTP registry** (`EL_IDENTITY_URL`, DEV-4871) — the older,
+ *      env-gated path. Superseded by (1), which needs no URL or CF-Access
+ *      credentials in the environment. Kept because it ships and someone may
+ *      rely on it.
+ *   3. **The bundled config** (`resolveMember`) — a local lookup table.
+ *
+ * All three are optional. With none of them, `resolveMember` hands the raw input
+ * back and Linear's own user lookup resolves it (`LinearService.resolveUserId`
+ * matches email → displayName → name), which is why an install with no config at
+ * all still works.
+ *
+ * Fail-open throughout: a miss or a failure at any layer falls through to the
+ * next. Never throws.
  */
 export declare function resolveMemberWithRegistry(input: string): Promise<string>;
 /**

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 { resolveViaCommand } from "./identity-resolver.js";
 import { isRegistryConfigured, resolveViaRegistry, } from "./registry-resolve.js";
 /**
  * Resolve a team key/name/alias to its UUID.
@@ -102,16 +103,39 @@ export async function resolveAssignee(input, rootOpts) {
     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).
+ * Resolve a member identifier (alias / handle / name) to a UUID. The shared
+ * async resolution path behind `--assignee` and `--delegate` (DEV-4871 /
+ * DEV-4872 / DEV-5628).
  *
- * 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.
+ * Order, most authoritative first:
+ *
+ *   1. **The identity-resolver hook** (`identity.resolver`, DEV-5628) — an
+ *      operator-supplied command. This is the one to reach for: it can answer
+ *      for aliases and cross-system handles Linear has never heard of, and it
+ *      owns its own credentials, so el-linear carries no auth scheme.
+ *   2. **The HTTP registry** (`EL_IDENTITY_URL`, DEV-4871) — the older,
+ *      env-gated path. Superseded by (1), which needs no URL or CF-Access
+ *      credentials in the environment. Kept because it ships and someone may
+ *      rely on it.
+ *   3. **The bundled config** (`resolveMember`) — a local lookup table.
+ *
+ * All three are optional. With none of them, `resolveMember` hands the raw input
+ * back and Linear's own user lookup resolves it (`LinearService.resolveUserId`
+ * matches email → displayName → name), which is why an install with no config at
+ * all still works.
+ *
+ * Fail-open throughout: a miss or a failure at any layer falls through to the
+ * next. Never throws.
  */
 export async function resolveMemberWithRegistry(input) {
+    // UUIDs are already canonical — don't spend a subprocess on them.
+    if (isUuid(input)) {
+        return input;
+    }
+    const viaCommand = resolveViaCommand(input, loadConfig());
+    if (viaCommand) {
+        return viaCommand;
+    }
     if (isRegistryConfigured()) {
         const viaRegistry = await resolveViaRegistry(input);
         if (viaRegistry) {

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

@@ -70,6 +70,30 @@ export declare const DEFAULT_DUPLICATE_THRESHOLD = 0.35;
  * Overridable via `config.validation.duplicateHardBlockThreshold`.
  */
 export declare const DEFAULT_HARD_BLOCK_THRESHOLD = 0.6;
+/**
+ * The one CLI flag that lets a HARD-BLOCKED create proceed.
+ *
+ * Exported so the remedy copy in {@link formatDuplicateBlock} is BUILT from the
+ * same constant the gate honors, rather than restating it. DEV-6205 shipped a
+ * remedy naming `--parent <id>` alone — a flag the gate never reads — so the
+ * message promised an outcome the command refused. Deriving the copy from this
+ * constant makes that class of drift a compile-time concern instead of a
+ * proofreading one.
+ */
+export declare const DUPLICATE_GATE_OVERRIDE_FLAG = "--allow-duplicate";
+/**
+ * Does this parsed option set clear the duplicate gate's HARD block?
+ *
+ * The single source of truth for the escape set, consumed by the gate itself
+ * (`enforceNoDuplicateIssue`) and asserted against the rendered remedy copy by
+ * the composition test. Note `--skip-validation` also bypasses, but it returns
+ * long before scoring (it skips ALL field validation), so it is not part of the
+ * hard-block decision this predicate models and is deliberately not offered as
+ * a remedy.
+ */
+export declare function bypassesDuplicateHardBlock(options: {
+    allowDuplicate?: unknown;
+}): boolean;
 /** A scored duplicate candidate, ready to print in the block. */
 export interface DuplicateCandidate {
     identifier: string;
@@ -116,5 +140,30 @@ export declare function scoreDuplicateCandidates(title: string, candidates: Line
  * "advisory"` is printed as a warning when the score is below the hard-block
  * threshold: creation already proceeded, so the trailing hint differs (no
  * "re-run" — there's nothing to re-run).
+ *
+ * Three remedies, not two (DEV-6205). "Same work → comment" and "distinct →
+ * --allow-duplicate" leave out the most common real case: the new work is a
+ * piece of the match — neither a duplicate of it nor unrelated to it. Offering
+ * only the two extremes pushes the operator toward reusing the matched issue,
+ * which is actively harmful when that issue is a multi-phase parent: the branch
+ * then carries the parent's id, and merging it auto-closes work that isn't done.
+ * That is not hypothetical — it is what the omission cost on MAR-744, where a
+ * findings pack was filed against a six-criterion parent because `--parent` was
+ * never mentioned.
+ *
+ * The sub-issue remedy is per-tier, NOT shared, because the two tiers are at
+ * opposite sides of the create:
+ *
+ * - **block** — creation was refused, so the remedy is a re-run. `--parent`
+ *   alone does NOT satisfy the gate ({@link bypassesDuplicateHardBlock} reads
+ *   only `allowDuplicate`), so the copy is built from
+ *   {@link DUPLICATE_GATE_OVERRIDE_FLAG} and names both flags. A message that
+ *   names a command the gate then refuses is the DEV-6205 bug one level down;
+ *   the composition test parses this copy through the real CLI and asserts it
+ *   actually clears the gate.
+ * - **advisory** — creation ALREADY proceeded, so there is nothing to re-run
+ *   and a re-run would file a second issue (which then scores 1.0 against its
+ *   own twin and hard-blocks). The remedy is to attach the issue that now
+ *   exists, via `issues update`.
  */
 export declare function formatDuplicateBlock(candidates: DuplicateCandidate[], mode?: "block" | "advisory"): string;

package/dist/utils/duplicate-detection.js

@@ -141,6 +141,30 @@ const BOILERPLATE_STOPWORDS = new Set([
     "create",
     "update",
 ]);
+/**
+ * The one CLI flag that lets a HARD-BLOCKED create proceed.
+ *
+ * Exported so the remedy copy in {@link formatDuplicateBlock} is BUILT from the
+ * same constant the gate honors, rather than restating it. DEV-6205 shipped a
+ * remedy naming `--parent <id>` alone — a flag the gate never reads — so the
+ * message promised an outcome the command refused. Deriving the copy from this
+ * constant makes that class of drift a compile-time concern instead of a
+ * proofreading one.
+ */
+export const DUPLICATE_GATE_OVERRIDE_FLAG = "--allow-duplicate";
+/**
+ * Does this parsed option set clear the duplicate gate's HARD block?
+ *
+ * The single source of truth for the escape set, consumed by the gate itself
+ * (`enforceNoDuplicateIssue`) and asserted against the rendered remedy copy by
+ * the composition test. Note `--skip-validation` also bypasses, but it returns
+ * long before scoring (it skips ALL field validation), so it is not part of the
+ * hard-block decision this predicate models and is deliberately not offered as
+ * a remedy.
+ */
+export function bypassesDuplicateHardBlock(options) {
+    return Boolean(options.allowDuplicate);
+}
 /**
  * Tokenize a title into a set of salient lowercase keywords.
  *
@@ -219,19 +243,52 @@ export function scoreDuplicateCandidates(title, candidates, threshold = DEFAULT_
  * "advisory"` is printed as a warning when the score is below the hard-block
  * threshold: creation already proceeded, so the trailing hint differs (no
  * "re-run" — there's nothing to re-run).
+ *
+ * Three remedies, not two (DEV-6205). "Same work → comment" and "distinct →
+ * --allow-duplicate" leave out the most common real case: the new work is a
+ * piece of the match — neither a duplicate of it nor unrelated to it. Offering
+ * only the two extremes pushes the operator toward reusing the matched issue,
+ * which is actively harmful when that issue is a multi-phase parent: the branch
+ * then carries the parent's id, and merging it auto-closes work that isn't done.
+ * That is not hypothetical — it is what the omission cost on MAR-744, where a
+ * findings pack was filed against a six-criterion parent because `--parent` was
+ * never mentioned.
+ *
+ * The sub-issue remedy is per-tier, NOT shared, because the two tiers are at
+ * opposite sides of the create:
+ *
+ * - **block** — creation was refused, so the remedy is a re-run. `--parent`
+ *   alone does NOT satisfy the gate ({@link bypassesDuplicateHardBlock} reads
+ *   only `allowDuplicate`), so the copy is built from
+ *   {@link DUPLICATE_GATE_OVERRIDE_FLAG} and names both flags. A message that
+ *   names a command the gate then refuses is the DEV-6205 bug one level down;
+ *   the composition test parses this copy through the real CLI and asserts it
+ *   actually clears the gate.
+ * - **advisory** — creation ALREADY proceeded, so there is nothing to re-run
+ *   and a re-run would file a second issue (which then scores 1.0 against its
+ *   own twin and hard-blocks). The remedy is to attach the issue that now
+ *   exists, via `issues update`.
  */
 export function formatDuplicateBlock(candidates, mode = "block") {
     const lines = candidates.map((c) => `    ${c.identifier} · ${c.title} · ${c.state} · ${c.assignee}  (similarity ${c.score})`);
+    // Name the parent when there is exactly one candidate; with several there is
+    // no single right parent, and silently picking the top score would invite a
+    // wrong one.
+    const parentRef = candidates.length === 1 ? candidates[0].identifier : "<id>";
     const header = `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 (mode === "advisory") {
         return (header +
+            "  If this is a piece of one of them rather than a duplicate, attach it with " +
+            `\`issues update <new-id> --parent ${parentRef}\`.\n` +
             "  This is advisory only (DEV-5590) — creation is proceeding. Pass " +
             "--allow-duplicate to silence this notice next time.");
     }
     return (header +
-        "  If this is genuinely distinct, re-run with --allow-duplicate to proceed " +
+        "  If this is a piece of one of them rather than a duplicate, re-run with " +
+        `--parent ${parentRef} ${DUPLICATE_GATE_OVERRIDE_FLAG} to file it as a sub-issue.\n` +
+        `  If this is genuinely distinct, re-run with ${DUPLICATE_GATE_OVERRIDE_FLAG} to proceed ` +
         "(and consider --related-to to link the related issue).");
 }

package/dist/utils/graphql-issues-service.js

@@ -1,3 +1,5 @@
+import { loadConfig } from "../config/config.js";
+import { resolveViaCommand } from "../config/identity-resolver.js";
 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_SCOPED_FILTERED_ISSUES_QUERY, TEAM_STARTED_STATUSES_QUERY, UPDATE_ISSUE_MUTATION, } from "../queries/issues.js";
@@ -1116,9 +1118,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.
+        // Opt-in identity resolution, falling back to the Linear-API user lookup
+        // below on a miss. Both layers are optional and fail-open — an install
+        // with neither configured never reaches the network here.
+        //   1. The resolver-command hook (DEV-5628) — brings its own credentials.
+        //   2. The older env-gated HTTP registry (DEV-4872).
+        const viaCommand = resolveViaCommand(assigneeId, loadConfig());
+        if (viaCommand) {
+            return viaCommand;
+        }
         if (isRegistryConfigured()) {
             const viaRegistry = await resolveViaRegistry(assigneeId);
             if (viaRegistry) {

package/package.json

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