@enrichlayer/el-linear 1.37.1 → 1.38.0

package/dist/commands/profile/members.js

@@ -0,0 +1,132 @@
+/**
+ * `el-linear profile members` — direct, non-interactive alias/handle edits
+ * on the active profile's on-disk config — DEV-5612.
+ *
+ * `init aliases` (the interactive wizard walk) is the right tool for a
+ * first-time setup or a bulk pass over many users, but fixing ONE entry
+ * (e.g. clearing a mistaken alias, or the Linear system actor a user
+ * accidentally aliased before DEV-5612's wizard-side skip existed) meant
+ * either re-walking every user interactively or hand-editing
+ * `~/.config/el-linear/config.json`. These commands are the direct path:
+ *
+ *   el-linear profile members list                      — show configured members
+ *   el-linear profile members clear <name>               — remove all aliases/handles for <name>
+ *   el-linear profile members set <name> [options]        — replace aliases/handles for <name>
+ *
+ * `<name>` is the exact Linear display name as it appears in
+ * `members.aliases`/`members.handles.*` values (see `profile members list`).
+ * These commands operate purely on the local config file — no Linear API
+ * call, no UUID resolution — so they also work to clean up a stale/mistaken
+ * entry for a user no longer in the workspace.
+ */
+import { outputSuccess } from "../../utils/output.js";
+import { applyMemberAliasUpdate } from "../init/aliases.js";
+import { parseCsvList, readConfig, updateConfig, } from "../init/shared.js";
+/**
+ * Reconstruct a per-member view from the on-disk `members.aliases` /
+ * `members.handles.{github,gitlab}` maps (each `{ key: displayName }`).
+ * `WizardConfig`'s maps are `Record<string, string | undefined>` (DeepPartial
+ * over an index signature) — an `undefined` value can't happen in practice
+ * (JSON never round-trips one), but we guard it defensively rather than cast.
+ * Pure — exported for testing.
+ */
+export function listMembers(config) {
+    const aliases = config.members?.aliases ?? {};
+    const github = config.members?.handles?.github ?? {};
+    const gitlab = config.members?.handles?.gitlab ?? {};
+    const byName = new Map();
+    const ensure = (name) => {
+        let entry = byName.get(name);
+        if (!entry) {
+            entry = { displayName: name, aliases: [] };
+            byName.set(name, entry);
+        }
+        return entry;
+    };
+    for (const [alias, name] of Object.entries(aliases)) {
+        if (name === undefined)
+            continue;
+        ensure(name).aliases.push(alias);
+    }
+    for (const [handle, name] of Object.entries(github)) {
+        if (name === undefined)
+            continue;
+        ensure(name).github = handle;
+    }
+    for (const [handle, name] of Object.entries(gitlab)) {
+        if (name === undefined)
+            continue;
+        ensure(name).gitlab = handle;
+    }
+    return [...byName.values()].sort((a, b) => a.displayName.localeCompare(b.displayName));
+}
+/**
+ * Translate a `--github`/`--gitlab` flag value into a HandleAction:
+ *   - flag absent          → keep (leave any existing handle alone)
+ *   - flag present, empty  → clear
+ *   - flag present, value  → set
+ */
+function handleActionFromFlag(raw) {
+    if (raw === undefined)
+        return { kind: "keep" };
+    const trimmed = raw.trim();
+    return trimmed ? { kind: "set", value: trimmed } : { kind: "clear" };
+}
+/** `el-linear profile members list` — exported for direct testing. */
+export async function runMembersList() {
+    const config = await readConfig();
+    return listMembers(config);
+}
+/** `el-linear profile members clear <name>` — exported for direct testing. */
+export async function runMembersClear(name) {
+    await updateConfig((current) => applyMemberAliasUpdate(current, name, {
+        mode: "clear",
+        aliases: [],
+        github: { kind: "clear" },
+        gitlab: { kind: "clear" },
+    }));
+}
+/** `el-linear profile members set <name>` — exported for direct testing. */
+export async function runMembersSet(name, opts) {
+    if (opts.aliases === undefined &&
+        opts.github === undefined &&
+        opts.gitlab === undefined) {
+        throw new Error("Pass at least one of --aliases, --github, --gitlab.");
+    }
+    await updateConfig((current) => applyMemberAliasUpdate(current, name, {
+        mode: opts.aliases !== undefined ? "edit" : "keep",
+        aliases: opts.aliases !== undefined ? parseCsvList(opts.aliases) : [],
+        github: handleActionFromFlag(opts.github),
+        gitlab: handleActionFromFlag(opts.gitlab),
+    }));
+}
+export function registerMembersCommands(profile) {
+    const members = profile
+        .command("members")
+        .description("Directly edit or clear a member's aliases/handles without hand-editing config.json (DEV-5612).");
+    members.action(() => members.help());
+    members
+        .command("list")
+        .description("List members with configured aliases/GitHub/GitLab handles.")
+        .action(async () => {
+        const data = await runMembersList();
+        outputSuccess({ data, meta: { count: data.length } });
+    });
+    members
+        .command("clear <name>")
+        .description("Remove all aliases + GitHub/GitLab handles for <name> (exact display name, see `members list`).")
+        .action(async (name) => {
+        await runMembersClear(name);
+        outputSuccess({ data: { cleared: name } });
+    });
+    members
+        .command("set <name>")
+        .description("Replace aliases/handles for <name> (exact display name). Omit a flag to leave that field unchanged; pass an empty value to clear just that field.")
+        .option("--aliases <csv>", "comma-separated aliases; replaces the existing set for this member")
+        .option("--github <handle>", "GitHub handle; pass an empty string to clear")
+        .option("--gitlab <handle>", "GitLab handle; pass an empty string to clear")
+        .action(async (name, opts) => {
+        await runMembersSet(name, opts);
+        outputSuccess({ data: { updated: name } });
+    });
+}

package/dist/commands/profile.js

@@ -26,6 +26,7 @@ import { confirm } from "@inquirer/prompts";
 import { ACTIVE_PROFILE_FILE, CONFIG_DIR, CONFIG_PATH, isSafeProfileName as isSafeName, PROFILES_DIR, profilePaths, readActiveProfileMarker, resolveActiveProfile, setActiveProfileForSession, TOKEN_PATH, } from "../config/paths.js";
 import { outputSuccess, outputWarning } from "../utils/output.js";
 import { runFullWizard } from "./init/index.js";
+import { registerMembersCommands } from "./profile/members.js";
 import { registerMigrateLegacy } from "./profile/migrate-legacy.js";
 export function setupProfileCommands(program) {
     const profile = program
@@ -79,6 +80,9 @@ export function setupProfileCommands(program) {
     // self-contained and unit-testable without dragging in the full
     // profile-management surface.
     registerMigrateLegacy(profile);
+    // `el-linear profile members {list,clear,set}` — DEV-5612: direct,
+    // non-interactive alias/handle edits without hand-editing config.json.
+    registerMembersCommands(profile);
 }
 export async function runProfileList() {
     const active = resolveActiveProfile();

package/dist/commands/projects.js

@@ -1,6 +1,6 @@
 import { loadConfig } from "../config/config.js";
 import { resolveTeam } from "../config/resolver.js";
-import { ARCHIVE_PROJECT_MUTATION, CREATE_PROJECT_MUTATION, DELETE_PROJECT_MUTATION, GET_PROJECT_QUERY, GET_PROJECT_TEAM_ISSUES_QUERY, PROJECT_BY_ID_QUERY, PROJECT_READ_QUERY, SEARCH_PROJECTS_BY_NAME_QUERY, UPDATE_PROJECT_MUTATION, } from "../queries/projects.js";
+import { ARCHIVE_PROJECT_MUTATION, CREATE_PROJECT_MUTATION, DELETE_PROJECT_MUTATION, GET_PROJECT_QUERY, GET_PROJECT_TEAM_ISSUES_QUERY, PROJECT_BY_ID_QUERY, PROJECT_READ_QUERY, SEARCH_PROJECTS_BY_NAME_QUERY, UPDATE_PROJECT_FIELDS_MUTATION, UPDATE_PROJECT_MUTATION, } from "../queries/projects.js";
 import { cached, resolveCacheTTL } from "../utils/disk-cache.js";
 import { createGraphQLService } from "../utils/graphql-service.js";
 import { createLinearService } from "../utils/linear-service.js";
@@ -229,6 +229,26 @@ function formatTeamsOutput(projectUpdate) {
         })),
     };
 }
+function hasOption(options, key) {
+    return options[key] !== undefined;
+}
+function flattenProjectUpdate(projectUpdate) {
+    if (!projectUpdate.project) {
+        throw new Error("Failed to update project");
+    }
+    const updatedProject = projectUpdate.project;
+    return {
+        id: updatedProject.id,
+        name: updatedProject.name,
+        description: updatedProject.description ?? undefined,
+        content: updatedProject.content ?? undefined,
+        teams: updatedProject.teams.nodes.map((t) => ({
+            id: t.id,
+            key: t.key,
+            name: t.name,
+        })),
+    };
+}
 async function handleAddTeam(projectNameOrId, teamInput, _options, command) {
     const rootOpts = getRootOpts(command);
     const graphQLService = await createGraphQLService(rootOpts);
@@ -437,6 +457,31 @@ async function handleReadProject(projectNameOrId, _options, command) {
         teams: teams.nodes.map((t) => ({ id: t.id, key: t.key, name: t.name })),
     });
 }
+async function handleUpdateProject(projectNameOrId, options, command) {
+    const input = {};
+    if (hasOption(options, "name")) {
+        input.name = options.name;
+    }
+    if (hasOption(options, "description")) {
+        input.description = options.description;
+    }
+    if (hasOption(options, "content")) {
+        input.content = options.content;
+    }
+    if (Object.keys(input).length === 0) {
+        throw new Error("Nothing to update. Pass at least one of --name, --description, or --content.");
+    }
+    const rootOpts = getRootOpts(command);
+    const graphQLService = await createGraphQLService(rootOpts);
+    const linearService = await createLinearService(rootOpts);
+    const projectId = await linearService.resolveProjectId(projectNameOrId);
+    const updateResult = await graphQLService.rawRequest(UPDATE_PROJECT_FIELDS_MUTATION, { id: projectId, input });
+    const projectUpdate = updateResult.projectUpdate;
+    if (!projectUpdate.success) {
+        throw new Error(`Failed to update project "${projectNameOrId}"`);
+    }
+    outputSuccess(flattenProjectUpdate(projectUpdate));
+}
 export function setupProjectsCommands(program) {
     const projects = program
         .command("projects")
@@ -463,6 +508,13 @@ export function setupProjectsCommands(program) {
         .command("read <project>")
         .description("Read one project's full details (resolves name/slug/URL/ID). `--format summary` shows state, lead, teams, target, progress, url; JSON includes description/content.")
         .action(handleAsyncCommand(handleReadProject));
+    projects
+        .command("update <project>")
+        .description("Update project name, short description, or markdown content")
+        .option("--name <name>", "project name")
+        .option("-d, --description <text>", "short summary (max 255 chars, shown in lists)")
+        .option("--content <markdown>", "full markdown body (shown in project panel)")
+        .action(handleAsyncCommand(handleUpdateProject));
     projects
         .command("list")
         .description("List projects")

package/dist/commands/users.js

@@ -5,6 +5,15 @@ import { parsePositiveInt } from "../utils/validators.js";
 export function setupUsersCommands(program) {
     const users = program.command("users").description("User operations");
     users.action(() => users.help());
+    users
+        .command("read <id>")
+        .description("Look up a single user by UUID, email, or name (resolves ambiguity the same way as other --assignee-style lookups).")
+        .action(handleAsyncCommand(async (id, _options, command) => {
+        const rootOpts = getRootOpts(command);
+        const service = await createLinearService(rootOpts);
+        const result = await service.getUser(id);
+        outputSuccess({ data: result });
+    }));
     users
         .command("list")
         .description("List all users")

package/dist/config/config.d.ts

@@ -69,6 +69,17 @@ export interface ElLinearConfig {
          * `DEFAULT_DUPLICATE_THRESHOLD` (0.35). Lower = more aggressive.
          */
         duplicateThreshold?: number;
+        /**
+         * Jaccard title-similarity threshold (0-1) above which a duplicate
+         * candidate HARD blocks creation (throws, requires `--allow-duplicate`).
+         * A candidate scoring at/above `duplicateThreshold` but below this is
+         * advisory only — printed, creation proceeds. Defaults to
+         * `DEFAULT_HARD_BLOCK_THRESHOLD` (0.6). See DEV-5590 for why the gate
+         * is two-tier: single-threshold override-rate telemetry showed score
+         * alone doesn't separate genuine duplicates from legitimate distinct
+         * issues in the 0.35-0.6 range.
+         */
+        duplicateHardBlockThreshold?: number;
         /**
          * OPT-IN SOP-label parent gate (DEV-5378). When `true`, `issues create`
          * requires an issue carrying an SOP-type label (see `sopLabels`) to point

package/dist/queries/projects-types.d.ts

@@ -77,6 +77,16 @@ export interface UpdateProjectResponse {
         project: ProjectBaseNode | null;
     };
 }
+interface ProjectUpdateFieldsNode extends ProjectBaseNode {
+    description: string | null;
+    content: string | null;
+}
+export interface UpdateProjectFieldsResponse {
+    projectUpdate: {
+        success: boolean;
+        project: ProjectUpdateFieldsNode | null;
+    };
+}
 interface ProjectArchiveEntity {
     id: string;
 }

package/dist/queries/projects.d.ts

@@ -14,5 +14,6 @@ export declare const GET_PROJECT_TEAM_ISSUES_QUERY = "\n  query GetProjectTeamIs
 export declare const SEARCH_PROJECTS_BY_NAME_QUERY = "\n  query SearchProjectsByName($name: String!) {\n    projects(filter: { name: { containsIgnoreCase: $name } }, first: 10) {\n      nodes {\n        id\n        name\n        state\n        teams {\n          nodes { id key name }\n        }\n      }\n    }\n  }\n";
 export declare const CREATE_PROJECT_MUTATION = "\n  mutation CreateProject($input: ProjectCreateInput!) {\n    projectCreate(input: $input) {\n      success\n      project {\n        id\n        name\n        state\n        teams {\n          nodes { id key name }\n        }\n      }\n    }\n  }\n";
 export declare const UPDATE_PROJECT_MUTATION = "\n  mutation UpdateProject($id: String!, $input: ProjectUpdateInput!) {\n    projectUpdate(id: $id, input: $input) {\n      success\n      project {\n        id\n        name\n        teams {\n          nodes {\n            id\n            key\n            name\n          }\n        }\n      }\n    }\n  }\n";
+export declare const UPDATE_PROJECT_FIELDS_MUTATION = "\n  mutation UpdateProjectFields($id: String!, $input: ProjectUpdateInput!) {\n    projectUpdate(id: $id, input: $input) {\n      success\n      project {\n        id\n        name\n        description\n        content\n        teams {\n          nodes {\n            id\n            key\n            name\n          }\n        }\n      }\n    }\n  }\n";
 export declare const ARCHIVE_PROJECT_MUTATION = "\n  mutation ArchiveProject($id: String!) {\n    projectArchive(id: $id) {\n      success\n      lastSyncId\n      entity {\n        id\n      }\n    }\n  }\n";
 export declare const DELETE_PROJECT_MUTATION = "\n  mutation DeleteProject($id: String!) {\n    projectDelete(id: $id) {\n      success\n      lastSyncId\n      entity {\n        id\n      }\n    }\n  }\n";

package/dist/queries/projects.js

@@ -129,6 +129,26 @@ export const UPDATE_PROJECT_MUTATION = `
     }
   }
 `;
+export const UPDATE_PROJECT_FIELDS_MUTATION = `
+  mutation UpdateProjectFields($id: String!, $input: ProjectUpdateInput!) {
+    projectUpdate(id: $id, input: $input) {
+      success
+      project {
+        id
+        name
+        description
+        content
+        teams {
+          nodes {
+            id
+            key
+            name
+          }
+        }
+      }
+    }
+  }
+`;
 export const ARCHIVE_PROJECT_MUTATION = `
   mutation ArchiveProject($id: String!) {
     projectArchive(id: $id) {

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

@@ -32,6 +32,44 @@ import type { LinearIssue } from "../types/linear.js";
  * Overridable via `config.validation.duplicateThreshold`.
  */
 export declare const DEFAULT_DUPLICATE_THRESHOLD = 0.35;
+/**
+ * Threshold above which a candidate is a HARD block (creation refuses without
+ * `--allow-duplicate`). Below this (but at/above {@link DEFAULT_DUPLICATE_THRESHOLD})
+ * a candidate is ADVISORY ONLY — printed, but creation proceeds — DEV-5590.
+ *
+ * Why a second threshold instead of just retuning the first: `el-telemetry
+ * gates` measured a 52.2% override rate on the single-threshold (0.35) gate
+ * over 144 real fires. Analyzing the real ledger (`top_score` + `outcome` per
+ * fire, no title text is ever recorded — el-linear collects nothing by
+ * default) falsifies the obvious fix of "just raise the threshold": mean/
+ * median `top_score` for `blocked` fires (0.414 / 0.40) and `overridden`
+ * fires (0.421 / 0.40) are statistically indistinguishable, and simulating
+ * every cutoff from 0.35 to 0.56 against the real corpus held the override
+ * rate flat at 52–63% — *increasing* at some higher cutoffs. Score alone does
+ * not separate genuine duplicates from legitimate distinct issues in this
+ * workspace's real usage; no single threshold in the observed range is
+ * better than a coin flip.
+ *
+ * Given that, blocking hard on a weak signal is worse than not blocking at
+ * all: over half the stops were wrong. 0.6 sits above the entire analyzed
+ * range (only 1/144 historical fires scored this high) and is reserved for
+ * near-verbatim title overlap — at Jaccard >= 0.6, more than 6 of every 10
+ * combined salient tokens are shared, which is a qualitatively different
+ * (and much rarer) signal than the "shares a few topical words" fires that
+ * dominate the false-positive population. This preserves a real backstop for
+ * the obvious copy-paste case while no longer forcing a stop-and-override
+ * ritual on the ambiguous 0.35-0.6 band, where the data shows we're wrong
+ * about as often as we're right.
+ *
+ * Caveat for future tuning: this corpus has no title text, so it cannot
+ * validate a *tokenization* fix (further stopwording per DEV-4830) — only a
+ * threshold-shape fix. A real precision improvement (distinguishing WHICH
+ * 0.35-0.6 fires are genuine) needs the title corpus, which is intentionally
+ * not collected. Revisit if `el-telemetry gates` after this ships still shows
+ * an unhealthy override rate on the >=0.6 hard-block tier specifically.
+ * Overridable via `config.validation.duplicateHardBlockThreshold`.
+ */
+export declare const DEFAULT_HARD_BLOCK_THRESHOLD = 0.6;
 /** A scored duplicate candidate, ready to print in the block. */
 export interface DuplicateCandidate {
     identifier: string;
@@ -71,6 +109,12 @@ export declare function scoreDuplicateCandidates(title: string, candidates: Line
 /**
  * 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.
+ * assignee).
+ *
+ * `mode: "block"` (default) is the body of the thrown error when the gate
+ * hard-blocks (score >= the hard-block threshold — DEV-5590). `mode:
+ * "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).
  */
-export declare function formatDuplicateBlock(candidates: DuplicateCandidate[]): string;
+export declare function formatDuplicateBlock(candidates: DuplicateCandidate[], mode?: "block" | "advisory"): string;

package/dist/utils/duplicate-detection.js

@@ -31,6 +31,44 @@
  * Overridable via `config.validation.duplicateThreshold`.
  */
 export const DEFAULT_DUPLICATE_THRESHOLD = 0.35;
+/**
+ * Threshold above which a candidate is a HARD block (creation refuses without
+ * `--allow-duplicate`). Below this (but at/above {@link DEFAULT_DUPLICATE_THRESHOLD})
+ * a candidate is ADVISORY ONLY — printed, but creation proceeds — DEV-5590.
+ *
+ * Why a second threshold instead of just retuning the first: `el-telemetry
+ * gates` measured a 52.2% override rate on the single-threshold (0.35) gate
+ * over 144 real fires. Analyzing the real ledger (`top_score` + `outcome` per
+ * fire, no title text is ever recorded — el-linear collects nothing by
+ * default) falsifies the obvious fix of "just raise the threshold": mean/
+ * median `top_score` for `blocked` fires (0.414 / 0.40) and `overridden`
+ * fires (0.421 / 0.40) are statistically indistinguishable, and simulating
+ * every cutoff from 0.35 to 0.56 against the real corpus held the override
+ * rate flat at 52–63% — *increasing* at some higher cutoffs. Score alone does
+ * not separate genuine duplicates from legitimate distinct issues in this
+ * workspace's real usage; no single threshold in the observed range is
+ * better than a coin flip.
+ *
+ * Given that, blocking hard on a weak signal is worse than not blocking at
+ * all: over half the stops were wrong. 0.6 sits above the entire analyzed
+ * range (only 1/144 historical fires scored this high) and is reserved for
+ * near-verbatim title overlap — at Jaccard >= 0.6, more than 6 of every 10
+ * combined salient tokens are shared, which is a qualitatively different
+ * (and much rarer) signal than the "shares a few topical words" fires that
+ * dominate the false-positive population. This preserves a real backstop for
+ * the obvious copy-paste case while no longer forcing a stop-and-override
+ * ritual on the ambiguous 0.35-0.6 band, where the data shows we're wrong
+ * about as often as we're right.
+ *
+ * Caveat for future tuning: this corpus has no title text, so it cannot
+ * validate a *tokenization* fix (further stopwording per DEV-4830) — only a
+ * threshold-shape fix. A real precision improvement (distinguishing WHICH
+ * 0.35-0.6 fires are genuine) needs the title corpus, which is intentionally
+ * not collected. Revisit if `el-telemetry gates` after this ships still shows
+ * an unhealthy override rate on the >=0.6 hard-block tier specifically.
+ * Overridable via `config.validation.duplicateHardBlockThreshold`.
+ */
+export const DEFAULT_HARD_BLOCK_THRESHOLD = 0.6;
 /**
  * Function words and issue-boilerplate tokens that carry no topical signal.
  * Dropping them keeps the Jaccard score driven by the distinctive nouns
@@ -174,14 +212,26 @@ export function scoreDuplicateCandidates(title, candidates, threshold = DEFAULT_
 /**
  * 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.
+ * assignee).
+ *
+ * `mode: "block"` (default) is the body of the thrown error when the gate
+ * hard-blocks (score >= the hard-block threshold — DEV-5590). `mode:
+ * "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).
  */
-export function formatDuplicateBlock(candidates) {
+export function formatDuplicateBlock(candidates, mode = "block") {
     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 ` +
+    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 one of these is the same work, comment on it instead of creating a new issue.\n";
+    if (mode === "advisory") {
+        return (header +
+            "  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 " +
         "(and consider --related-to to link the related issue).");
 }

package/dist/utils/gate-telemetry.d.ts

@@ -1,3 +1,23 @@
+/**
+ * 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`.
+ */
+export declare const GATE_LEDGER_MAX_BYTES: number;
+export declare const GATE_LEDGER_BACKUP_SUFFIX = ".old";
 /** 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
@@ -29,9 +49,15 @@ export interface GateEvent {
      * `blocked` — the gate stopped creation. `overridden` — a gate-specific
      * override flag let a would-block proceed. `fail-open` — the gate could not
      * evaluate (infra/service error) and let creation proceed rather than block
-     * on trouble; tracked so degradation is measurable (DEV-5378).
+     * on trouble; tracked so degradation is measurable (DEV-5378). `advisory` —
+     * the gate fired below its hard-block threshold: printed, but never forced
+     * a stop (DEV-5590). Like `fail-open`, the tools-repo reader
+     * (`el-telemetry gates`) only recognizes `blocked`/`overridden` for the
+     * override-rate denominator — an unrecognized outcome is skipped rather
+     * than counted, so `advisory` fires are visible in the raw ledger but
+     * intentionally excluded from the metric.
      */
-    outcome: "blocked" | "overridden" | "fail-open";
+    outcome: "blocked" | "overridden" | "fail-open" | "advisory";
     /** Highest candidate similarity that triggered the gate (0–1). */
     topScore?: number;
     /** How many candidates crossed the threshold. */

package/dist/utils/gate-telemetry.js

@@ -1,5 +1,5 @@
 import { existsSync } from "node:fs";
-import { appendFile, mkdir } from "node:fs/promises";
+import { appendFile, mkdir, rename, rm, stat } from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 /**
@@ -20,6 +20,8 @@ import { dirname, join } from "node:path";
  * `GATE_EVENTS_PATH`; keep the two in sync. Format + reader are documented in
  * `docs/telemetry.md`.
  */
+export const GATE_LEDGER_MAX_BYTES = 2 * 1024 * 1024;
+export const GATE_LEDGER_BACKUP_SUFFIX = ".old";
 /** The default ledger directory when `EL_TELEMETRY_DIR` is not set. */
 function defaultTelemetryDir() {
     return join(homedir(), ".cache", "el-telemetry");
@@ -67,6 +69,28 @@ function gateLedgerIfEnabled() {
         defaultDirExists: existsSync(defaultDir),
     });
 }
+async function rotateGateLedgerIfOverLimit(path) {
+    let size = 0;
+    try {
+        const s = await stat(path);
+        if (!s.isFile())
+            return;
+        size = s.size;
+    }
+    catch {
+        return;
+    }
+    if (size <= GATE_LEDGER_MAX_BYTES)
+        return;
+    try {
+        const backupPath = `${path}${GATE_LEDGER_BACKUP_SUFFIX}`;
+        await rm(backupPath, { force: true });
+        await rename(path, backupPath);
+    }
+    catch {
+        // best-effort — telemetry never blocks issue creation
+    }
+}
 /**
  * Best-effort append of a gate event to the local ledger — but only when
  * telemetry is opted in ({@link gateLedgerIfEnabled}); otherwise a silent
@@ -80,6 +104,7 @@ export async function emitGateEvent(name, subcommand, event) {
     }
     try {
         await mkdir(dirname(path), { recursive: true });
+        await rotateGateLedgerIfOverLimit(path);
         const record = {
             ts: new Date().toISOString(),
             kind: "gate",

package/dist/utils/inline-text-input.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Normalize shell-literal newline escapes in inline CLI text fields.
+ *
+ * File inputs are intentionally excluded by call site: a file body is already
+ * explicit authored text and may intentionally contain backslash sequences.
+ */
+export declare function normalizeInlineTextInput(value: string): string;

package/dist/utils/inline-text-input.js

@@ -0,0 +1,12 @@
+/**
+ * Normalize shell-literal newline escapes in inline CLI text fields.
+ *
+ * File inputs are intentionally excluded by call site: a file body is already
+ * explicit authored text and may intentionally contain backslash sequences.
+ */
+export function normalizeInlineTextInput(value) {
+    return value
+        .replace(/\\r\\n/g, "\n")
+        .replace(/\\n/g, "\n")
+        .replace(/\\r/g, "\n");
+}

package/dist/utils/linear-service.d.ts

@@ -14,6 +14,14 @@ export declare class LinearService {
     resolveIssueId(issueId: string): Promise<string>;
     getTeams(limit?: number): Promise<LinearTeam[]>;
     resolveUserId(nameOrEmailOrId: string): Promise<string>;
+    /**
+     * Single-user lookup by UUID, email, or name (DEV-5612) — the natural
+     * complement to `getUsers`/`users list`, so identifying one actor (e.g. an
+     * unrecognized member surfaced by the alias wizard) doesn't require
+     * dumping the whole workspace. Resolution/ambiguity semantics match every
+     * other `--assignee`-style lookup in the CLI via {@link resolveUserId}.
+     */
+    getUser(nameOrEmailOrId: string): Promise<LinearUser>;
     getUsers(activeOnly?: boolean, limit?: number, nameFilter?: string): Promise<LinearUser[]>;
     getProjects(limit?: number, options?: {
         nameFilter?: string;

package/dist/utils/linear-service.js

@@ -99,6 +99,24 @@ export class LinearService {
         }
         throw notFoundError("User", nameOrEmailOrId);
     }
+    /**
+     * Single-user lookup by UUID, email, or name (DEV-5612) — the natural
+     * complement to `getUsers`/`users list`, so identifying one actor (e.g. an
+     * unrecognized member surfaced by the alias wizard) doesn't require
+     * dumping the whole workspace. Resolution/ambiguity semantics match every
+     * other `--assignee`-style lookup in the CLI via {@link resolveUserId}.
+     */
+    async getUser(nameOrEmailOrId) {
+        const id = await this.resolveUserId(nameOrEmailOrId);
+        const user = await this.client.user(id);
+        return {
+            id: user.id,
+            name: user.name,
+            displayName: user.displayName,
+            email: user.email,
+            active: user.active,
+        };
+    }
     async getUsers(activeOnly, limit = 100, nameFilter) {
         const filter = {};
         if (activeOnly) {

package/dist/utils/relation-candidate-prompt.d.ts

@@ -41,16 +41,23 @@
  */
 export declare function extractCandidateIdentifiers(rows: unknown[]): string[];
 /**
- * Build the relation-candidate confirmation warning string, or `null` when
- * the result set has no identifier-bearing rows (nothing to confirm).
+ * Build the relation-candidate warning string, or `null` when the result set
+ * has no identifier-bearing rows (nothing to surface).
  *
  * Shape (single line, structured-prose so a skill can match on the prefix):
  *
  *     relation_candidates: Found N candidate related issues (DEV-1, DEV-2, …).
- *     To link them as related: reply with the IDs you want linked
- *     (e.g. "link DEV-1 and DEV-2"). To skip linking: reply "no links".
+ *     Link the relevant ones now — at create time with --related-to, or
+ *     `issues relate <id> --related-to "<ids>"`. If auto-mode blocks an
+ *     agent-inferred relate, reply with the IDs you want linked
+ *     (e.g. "link DEV-1 and DEV-2"), or "no links" to skip.
  *
- * The `relation_candidates:` prefix matches the existing `results_truncated:`
+ * DEV-5853: the primary framing is **proactive** — this is a convenience list
+ * of link candidates, not a stop sign. Relate the relevant ones directly
+ * rather than waiting to be told; the reply flow is the *fallback* for when
+ * the auto-mode classifier actually blocks an agent-inferred `issues relate`
+ * (create-time `--related-to` typically passes, so prefer it). The
+ * `relation_candidates:` prefix matches the existing `results_truncated:`
  * convention in `outputWarning` callers — a stable token a skill / agent
  * harness can grep for without parsing free-form prose.
  */