@enrichlayer/el-linear 1.29.1 → 1.32.0

package/README.md

@@ -662,9 +662,9 @@ Mutually exclusive with `--field` / `--sections` / `--with`.
 
 ### One-line write confirmations: `-q, --quiet`
 
-`issues create|update` and `comments create|update` accept `-q, --quiet`,
-printing a single confirmation line instead of the full JSON envelope so
-you don't have to `grep` the result:
+`issues create|update`, `issues relate`, and `comments create|update` accept
+`-q, --quiet`, printing a single confirmation line instead of the full JSON
+envelope so you don't have to `grep` the result:
 
 ```bash
 el-linear issues update DEV-123 --status "In Review" --quiet
@@ -672,6 +672,24 @@ el-linear issues update DEV-123 --status "In Review" --quiet
 
 el-linear comments create DEV-123 --body "..." --quiet
 # comment 6f1c…
+
+el-linear issues relate DEV-123 --related-to "DEV-456,DEV-789" --quiet
+# DEV-123  related DEV-456,DEV-789  (2)
+```
+
+For `issues relate` the line is source-oriented — relations are grouped by
+type from the source issue's perspective, so a `--blocked-by` reads back as
+`blockedBy`. `--format summary` renders the same source-oriented view as a
+`TYPE / TARGET / TITLE` table (TARGET is the peer issue; the source isn't
+repeated as a column):
+
+```bash
+el-linear issues relate DEV-1 --blocked-by DEV-9 --format summary
+# TYPE        TARGET   TITLE
+# ------------------------------------
+# blockedBy   DEV-9    Add IP ban system
+#
+# 1 relation
 ```
 
 `--quiet` overrides `--format` and is independent of `--fields` / `--jq`.

package/claude-skills/linear-operations/SKILL.md

@@ -197,7 +197,15 @@ el-linear issues search "keywords from proposed title" --include-closed 2>&1
    el-linear issues create "Title" --team ENG --related-to "ENG-456,ENG-789" ... 2>&1
    ```
 
-### Surfacing relation candidates — explicit user reply required ([DEV-4494](https://linear.app/verticalint/issue/DEV-4494/))
+### Existence check — before an "add capability X" issue ([DEV-5097](https://linear.app/verticalint/issue/DEV-5097/))
+
+The dup-check above guards against duplicating an *issue*. This guards against duplicating *reality*: before filing an issue to **add** a flag / guard / command / subcommand, confirm it doesn't **already exist**.
+
+- `<cli> <subcommand> --help` (the flag may be a global option absent from the subcommand's help — check `<cli> --help` too).
+- `el-catalog commands --search "<intent>"` / `el-catalog clis --search` (the snapshot likely already lists it).
+- For a hook/guard, grep the source — e.g. `cli/el-hook/src/checks`.
+
+Skipping it cost two needless branch+MR cycles in one session: a "feature" issue to add a hook guard that already existed and was firing, and one to add `--jq`/`--fields` flags that already worked — both premises only caught at implementation.
 
 When `el-linear issues search` (or the cross-resource `search`) returns rows
 carrying issue identifiers, the JSON envelope embeds a `_warnings` line
@@ -352,6 +360,27 @@ el-linear comments create ENG-123 --body "cc @alice — Bob can you review?" 2>&
 
 Works in comments only (not descriptions).
 
+### Confirming a mention fired (the `mentions` output field)
+
+A real mention lives in the comment's structured `bodyData`, not in the markdown — so a comment whose body reads `@alice` may or may not have actually pinged anyone. **Don't guess: read the `mentions` field** that `comments create|update` attach to their output (the sibling of `autoLinked`):
+
+```jsonc
+{
+  "id": "…",
+  "mentions": {
+    "resolved":   [{ "label": "alice", "userId": "…" }],  // real notifications sent
+    "unresolved": ["bobby"],                                // explicit @names that matched nobody
+    "delivered":  true                                      // false ⇒ Linear rejected bodyData, fell back to plain text
+  }
+}
+```
+
+- An **unresolved** explicit `@name` (typo or unknown handle) is left as plain text — **no notification** — and el-linear prints a loud `⚠ @name did not resolve …` warning to **stderr**. Fix the name and re-comment; never assume the ping landed.
+- `delivered: false` means the structured body was rejected and the comment shipped as plain markdown, so the resolved mentions did **not** fire — also warned on stderr.
+- Under `--quiet`, the stdout stays the one-line `comment <id>`; the `mentions: resolved=[…] unresolved=[…]` confirmation is echoed to **stderr**.
+
+This makes "a real @mention" a verifiable, deterministic convention rather than a hope ([DEV-4987](https://linear.app/verticalint/issue/DEV-4987/)).
+
 ---
 
 ## CLI Syntax Rules

package/dist/commands/branch.d.ts

@@ -0,0 +1,20 @@
+/**
+ * `el-linear branch validate [branch]` — validate that a branch name carries a
+ * **real** Linear team prefix, checked against the workspace's actual teams
+ * (cached `teams list`) rather than a hand-maintained allowlist.
+ *
+ * Built so the tools-repo pre-commit gate (`check-linear-branch.sh`) can
+ * delegate team-validity here instead of hardcoding a bash regex that drifts
+ * (it already did: phantom `CS`, missing `CUS/EMW/NIC/PYT`). Branch *parsing*
+ * already lives in `issue-id`/`parseBranchName`; this adds team *validity*.
+ *
+ * Exit codes (so a caller can distinguish "block" from "fall back"):
+ *   0 — valid: a real team, or an exempt branch (main/master/detached/empty)
+ *   1 — invalid: parsed a team that isn't a real workspace team, or no Linear ID
+ *   2 — indeterminate: the team set couldn't be loaded (offline + cold cache);
+ *       lets the caller fall back to its own check rather than hard-block
+ *
+ * `--exit-zero` reports the JSON verdict but always exits 0 (report-only).
+ */
+import type { Command } from "commander";
+export declare function setupBranchCommands(program: Command): void;

package/dist/commands/branch.js

@@ -0,0 +1,101 @@
+/**
+ * `el-linear branch validate [branch]` — validate that a branch name carries a
+ * **real** Linear team prefix, checked against the workspace's actual teams
+ * (cached `teams list`) rather than a hand-maintained allowlist.
+ *
+ * Built so the tools-repo pre-commit gate (`check-linear-branch.sh`) can
+ * delegate team-validity here instead of hardcoding a bash regex that drifts
+ * (it already did: phantom `CS`, missing `CUS/EMW/NIC/PYT`). Branch *parsing*
+ * already lives in `issue-id`/`parseBranchName`; this adds team *validity*.
+ *
+ * Exit codes (so a caller can distinguish "block" from "fall back"):
+ *   0 — valid: a real team, or an exempt branch (main/master/detached/empty)
+ *   1 — invalid: parsed a team that isn't a real workspace team, or no Linear ID
+ *   2 — indeterminate: the team set couldn't be loaded (offline + cold cache);
+ *       lets the caller fall back to its own check rather than hard-block
+ *
+ * `--exit-zero` reports the JSON verdict but always exits 0 (report-only).
+ */
+import { loadConfig } from "../config/config.js";
+import { cached, resolveCacheTTL } from "../utils/disk-cache.js";
+import { createLinearService } from "../utils/linear-service.js";
+import { handleAsyncCommand, outputSuccess } from "../utils/output.js";
+import { getRootOpts } from "../utils/root-opts.js";
+import { getCurrentBranch, parseBranchName } from "./issue-id.js";
+import { TEAMS_LIST_DEFAULT_LIMIT } from "./teams.js";
+// Branches that never carry a Linear ID and must not be blocked. Mirrors the
+// exemptions in the tools-repo gate (main/master/detached HEAD/empty).
+const EXEMPT_BRANCHES = new Set(["main", "master", "HEAD", ""]);
+export function setupBranchCommands(program) {
+    const branch = program.command("branch").description("Branch-name helpers");
+    branch.action(() => branch.help());
+    branch
+        .command("validate [branch]")
+        .description("Validate a branch's team prefix against real workspace teams. Exit 0 valid, 1 invalid, 2 indeterminate.")
+        .option("--exit-zero", "report the verdict as JSON but always exit 0 (report-only)", false)
+        .action(handleAsyncCommand(async (branchArg, options, command) => {
+        const branchName = branchArg ?? getCurrentBranch();
+        if (EXEMPT_BRANCHES.has(branchName)) {
+            outputSuccess({
+                branch: branchName,
+                valid: true,
+                team: null,
+                issueId: null,
+                reason: "exempt",
+            });
+            return;
+        }
+        const parsed = parseBranchName(branchName);
+        if (!(parsed.issueId && parsed.team)) {
+            outputSuccess({
+                branch: branchName,
+                valid: false,
+                team: null,
+                issueId: null,
+                reason: "no-linear-id",
+            });
+            if (!options.exitZero)
+                process.exitCode = 1;
+            return;
+        }
+        let teamKeys;
+        try {
+            const rootOpts = getRootOpts(command);
+            const ttl = resolveCacheTTL({
+                configTTL: loadConfig().cacheTTLSeconds,
+                noCacheFlag: rootOpts.cache === false,
+            });
+            // Same cache key and limit as `teams list` default — share the entry.
+            const teams = await cached(`teams-list-limit:${TEAMS_LIST_DEFAULT_LIMIT}`, ttl, async () => {
+                const service = await createLinearService(rootOpts);
+                return service.getTeams(TEAMS_LIST_DEFAULT_LIMIT);
+            });
+            teamKeys = teams.map((t) => t.key);
+        }
+        catch {
+            // Couldn't load the team set (offline + cold cache). Signal
+            // indeterminate so the caller can fall back instead of blocking.
+            outputSuccess({
+                branch: branchName,
+                valid: null,
+                team: parsed.team,
+                issueId: parsed.issueId,
+                reason: "teams-unavailable",
+            });
+            if (!options.exitZero)
+                process.exitCode = 2;
+            return;
+        }
+        const valid = teamKeys.includes(parsed.team);
+        outputSuccess({
+            branch: branchName,
+            valid,
+            team: parsed.team,
+            issueId: parsed.issueId,
+            reason: valid ? "ok" : "unknown-team",
+            ...(valid ? {} : { knownTeams: teamKeys }),
+        });
+        if (!(valid || options.exitZero))
+            process.exitCode = 1;
+    }));
+}

package/dist/commands/comments.js

@@ -7,8 +7,9 @@ import { createGraphQLService, } from "../utils/graphql-service.js";
 import { extractIssueReferences } from "../utils/issue-reference-extractor.js";
 import { wrapIssueReferencesAsLinks } from "../utils/issue-reference-wrapper.js";
 import { createLinearService, } from "../utils/linear-service.js";
-import { resolveMentions } from "../utils/mention-resolver.js";
-import { handleAsyncCommand, outputSuccess } from "../utils/output.js";
+import { logger } from "../utils/logger.js";
+import { resolveMentions, } from "../utils/mention-resolver.js";
+import { getQuietMode, handleAsyncCommand, outputSuccess, } from "../utils/output.js";
 import { getRootOpts } from "../utils/root-opts.js";
 import { validateReferences } from "../utils/validate-references.js";
 import { parsePositiveInt } from "../utils/validators.js";
@@ -17,6 +18,54 @@ import { getWorkspaceUrlKey } from "../utils/workspace-url.js";
 // tweak on their side doesn't silently regress the fallback path.
 const BODY_DATA_ERROR_RE = /prosemirror|bodydata|invalid.*body/i;
 const ISSUE_IDENTIFIER_REGEX = /^[A-Z][A-Z0-9]*-\d+$/;
+/**
+ * Turn a {@link MentionReport} into the `mentions` output field, or `undefined`
+ * when there is nothing to report. `delivered=false` records a bodyData→plain
+ * fallback so the JSON output never falsely claims a ping was sent.
+ */
+function buildMentionsOutput(report, delivered) {
+    if (!report) {
+        return undefined;
+    }
+    if (report.resolved.length === 0 && report.unresolvedExplicit.length === 0) {
+        return undefined;
+    }
+    return {
+        resolved: report.resolved.map((m) => ({
+            label: m.label,
+            userId: m.userId,
+        })),
+        unresolved: report.unresolvedExplicit,
+        delivered,
+    };
+}
+/**
+ * Emit the human-facing side of mention resolution to **stderr** (so it never
+ * pollutes the machine-stable stdout line, and survives `--quiet`):
+ *   - a loud warning for each explicit `@name` that resolved to nobody,
+ *   - a warning when a bodyData rejection dropped resolved mentions,
+ *   - under `--quiet`, a one-line confirmation of what resolved (since the
+ *     quiet stdout line can't carry the `mentions` field).
+ */
+function reportMentions(mentions) {
+    if (!mentions) {
+        return;
+    }
+    for (const name of mentions.unresolved) {
+        logger.error(`⚠ @${name} did not resolve to a team member — left as plain text (no notification sent)`);
+    }
+    if (!mentions.delivered && mentions.resolved.length > 0) {
+        logger.error(`⚠ Linear rejected the structured comment body; fell back to plain text — ${mentions.resolved.length} mention(s) were NOT delivered as notifications`);
+    }
+    // In quiet mode stdout is a single `comment <id>` line with no room for the
+    // `mentions` field, so echo a concise confirmation to stderr.
+    if (getQuietMode()) {
+        const resolved = mentions.delivered
+            ? mentions.resolved.map((m) => `${m.label}→${m.userId}`).join(", ")
+            : "(none delivered)";
+        logger.error(`mentions: resolved=[${resolved}] unresolved=[${mentions.unresolved.join(", ")}]`);
+    }
+}
 function readBody(options) {
     // --body and --body-file are two sources for the same field; accepting both
     // would silently drop one. Reject up front (DEV-4450) — the same mutual-
@@ -130,12 +179,15 @@ async function handleCreateComment(issueId, options, command) {
         selfUserId,
     });
     const input = { issueId: resolvedIssueId };
-    if (mentionResult) {
+    if (mentionResult?.bodyData) {
         input.bodyData = mentionResult.bodyData;
     }
     else {
         input.body = body;
     }
+    // Tracks whether resolved mentions actually shipped as structured nodes;
+    // flipped to false if the bodyData fallback below sends plain text instead.
+    let mentionsDelivered = true;
     let result;
     try {
         result = await graphQLService.rawRequest(CREATE_COMMENT_MUTATION, { input });
@@ -146,6 +198,7 @@ async function handleCreateComment(issueId, options, command) {
         // Linear handle the conversion server-side.
         const msg = err instanceof Error ? err.message : String(err);
         if (input.bodyData && BODY_DATA_ERROR_RE.test(msg)) {
+            mentionsDelivered = false;
             const fallbackInput = {
                 issueId: resolvedIssueId,
                 body,
@@ -179,7 +232,13 @@ async function handleCreateComment(issueId, options, command) {
         linearService,
     });
     const output = transformComment(mutation.comment);
-    outputSuccess(autoLinked ? { ...output, autoLinked } : output);
+    const mentions = buildMentionsOutput(mentionResult, mentionsDelivered);
+    reportMentions(mentions);
+    outputSuccess({
+        ...output,
+        ...(autoLinked ? { autoLinked } : {}),
+        ...(mentions ? { mentions } : {}),
+    });
 }
 async function handleUpdateComment(commentId, options, command) {
     const rootOpts = getRootOpts(command);
@@ -196,12 +255,13 @@ async function handleUpdateComment(commentId, options, command) {
         selfUserId,
     });
     const input = {};
-    if (mentionResult) {
+    if (mentionResult?.bodyData) {
         input.bodyData = mentionResult.bodyData;
     }
     else {
         input.body = body;
     }
+    let mentionsDelivered = true;
     let result;
     try {
         result = await graphQLService.rawRequest(UPDATE_COMMENT_MUTATION, { id: commentId, input });
@@ -217,6 +277,7 @@ async function handleUpdateComment(commentId, options, command) {
         // extraction; copy-then-refactor on the third per the repo convention.
         const msg = err instanceof Error ? err.message : String(err);
         if (input.bodyData && BODY_DATA_ERROR_RE.test(msg)) {
+            mentionsDelivered = false;
             const fallbackInput = { body };
             result = await graphQLService.rawRequest(UPDATE_COMMENT_MUTATION, { id: commentId, input: fallbackInput });
         }
@@ -243,7 +304,13 @@ async function handleUpdateComment(commentId, options, command) {
         });
     }
     const output = transformComment(comment);
-    outputSuccess(autoLinked ? { ...output, autoLinked } : output);
+    const mentions = buildMentionsOutput(mentionResult, mentionsDelivered);
+    reportMentions(mentions);
+    outputSuccess({
+        ...output,
+        ...(autoLinked ? { autoLinked } : {}),
+        ...(mentions ? { mentions } : {}),
+    });
 }
 async function handleListComments(issueId, options, command) {
     const rootOpts = getRootOpts(command);

package/dist/commands/issue-id.d.ts

@@ -24,5 +24,6 @@ interface ParsedBranch {
     team: string | null;
 }
 export declare function parseBranchName(branch: string): ParsedBranch;
+export declare function getCurrentBranch(): string;
 export declare function setupIssueIdCommand(program: Command): void;
 export {};

package/dist/commands/issue-id.js

@@ -50,7 +50,7 @@ export function parseBranchName(branch) {
         slug: m[3] ?? null,
     };
 }
-function getCurrentBranch() {
+export function getCurrentBranch() {
     const result = spawnSync("git", ["rev-parse", "--abbrev-ref", "HEAD"], {
         encoding: "utf8",
     });

package/dist/commands/issues.js

@@ -1233,6 +1233,7 @@ export function setupIssuesCommands(program) {
         .option("--blocks <issues>", "issues this blocks (comma-separated)")
         .option("--blocked-by <issues>", "issues blocking this (comma-separated)")
         .option("--duplicate-of <issue>", "mark as duplicate of another issue")
+        .option("-q, --quiet", "print one confirmation line (SOURCE  type targets  (count)) instead of the full JSON")
         .action(handleAsyncCommand(handleRelateIssue));
     issues
         .command("related <issueId>")

package/dist/commands/teams.d.ts

@@ -1,2 +1,3 @@
 import type { Command } from "commander";
+export declare const TEAMS_LIST_DEFAULT_LIMIT = 100;
 export declare function setupTeamsCommands(program: Command): void;

package/dist/commands/teams.js

@@ -4,6 +4,7 @@ import { createLinearService } from "../utils/linear-service.js";
 import { handleAsyncCommand, outputSuccess } from "../utils/output.js";
 import { getRootOpts } from "../utils/root-opts.js";
 import { parsePositiveInt } from "../utils/validators.js";
+export const TEAMS_LIST_DEFAULT_LIMIT = 100;
 export function setupTeamsCommands(program) {
     const teams = program
         .command("teams")
@@ -13,7 +14,7 @@ export function setupTeamsCommands(program) {
     teams
         .command("list")
         .description("List all teams")
-        .option("-l, --limit <number>", "limit results", "100")
+        .option("-l, --limit <number>", "limit results", String(TEAMS_LIST_DEFAULT_LIMIT))
         .action(handleAsyncCommand(async (options, command) => {
         const rootOpts = getRootOpts(command);
         const limit = parsePositiveInt(options.limit, "--limit");

package/dist/main.js

@@ -5,6 +5,7 @@ import { fileURLToPath } from "node:url";
 import { program } from "commander";
 import { setupAttachmentsCommands } from "./commands/attachments.js";
 import { setupBatchCommands } from "./commands/batch.js";
+import { setupBranchCommands } from "./commands/branch.js";
 import { setupCommentsCommands } from "./commands/comments.js";
 import { setupConfigCommands } from "./commands/config.js";
 import { setupCyclesCommands } from "./commands/cycles.js";
@@ -132,6 +133,7 @@ program.action(() => {
 });
 setupAttachmentsCommands(program);
 setupBatchCommands(program);
+setupBranchCommands(program);
 setupSearchCommands(program);
 setupIssuesCommands(program);
 setupIssueIdCommand(program);

package/dist/utils/formatters/summary.d.ts

@@ -32,6 +32,16 @@ export declare function formatMilestoneSummary(milestone: Record<string, unknown
 export declare function formatMilestoneList(milestones: unknown[]): string;
 export declare function formatTeamList(teams: unknown[]): string;
 export declare function formatLabelList(labels: unknown[]): string;
+/**
+ * Table render for an `issues relate` result — the `{ data: IssueRelation[] }`
+ * envelope where each entry is `{ type, issue, relatedIssue }`. Rendered
+ * **source-oriented** (`TYPE  TARGET  TITLE`) to match the `--quiet` line: the
+ * type is normalized from the source's perspective (a `--blocked-by` reads as
+ * `blockedBy`) and TARGET is the peer (non-source) issue. `sourceRef` comes
+ * from the envelope's `meta.source` via `dispatch`; absent it (a bare array),
+ * the row falls back to the stored direction.
+ */
+export declare function formatRelationList(relations: unknown[], sourceRef?: string): string;
 export declare function formatUserSummary(user: Record<string, unknown>): string;
 export declare function formatUserList(users: unknown[]): string;
 export declare function formatDocumentSummary(doc: Record<string, unknown>): string;
@@ -49,7 +59,7 @@ export declare function formatSearchResultList(results: unknown[]): string;
  * the full payload. Lists fall back to a simple bulleted list.
  */
 export declare function formatGenericSummary(value: unknown): string;
-export type ResourceKind = "issue" | "issue-list" | "project" | "project-list" | "comment" | "comment-list" | "cycle" | "cycle-list" | "milestone" | "milestone-list" | "team-list" | "label-list" | "user" | "user-list" | "document" | "document-list" | "template" | "template-list" | "attachment-list" | "release" | "release-list" | "search-result-list" | "empty-list" | "generic";
+export type ResourceKind = "issue" | "issue-list" | "project" | "project-list" | "comment" | "comment-list" | "cycle" | "cycle-list" | "milestone" | "milestone-list" | "team-list" | "label-list" | "user" | "user-list" | "document" | "document-list" | "template" | "template-list" | "attachment-list" | "release" | "release-list" | "search-result-list" | "relation-list" | "empty-list" | "generic";
 /**
  * Heuristic — used by the central `outputSuccess` path which doesn't know
  * which command produced the payload. Looks at the shape of the data to

package/dist/utils/formatters/summary.js

@@ -689,6 +689,64 @@ export function formatLabelList(labels) {
         { header: "COLOR", minWidth: 5, extract: (l) => s(l.color) },
     ], { emptyText: "(no labels)", itemNoun: "label" });
 }
+// ── relations ──────────────────────────────────────────────────
+/**
+ * Re-frame a stored relation row from the source issue's perspective: returns
+ * the normalized relation `type` (a reverse `blocks` becomes `blockedBy`) and
+ * the `peer` — the non-source issue node. `createRelations` stores a
+ * `--blocked-by X` row reversed (`{ type:"blocks", issue:X, relatedIssue:source }`),
+ * so the source can sit on either side; we orient by `sourceRef`.
+ *
+ * `sourceRef` is the raw arg the user passed — a canonical `TEAM-NUM`
+ * identifier or a UUID, the only two forms `resolveIssueId` admits — matched
+ * against either node's `identifier` or `id`. (Coupling note: if that resolver
+ * is ever widened to accept Linear URLs / slug-ids, as `--project` already
+ * does, this match would need the resolved `sourceId` instead.) With no source
+ * (`"—"`, e.g. a bare array with no `meta`), nothing matches, so it falls back
+ * to the stored direction: peer = `relatedIssue`, type uninverted.
+ */
+function relationFromSource(rel, sourceRef) {
+    const matchesSource = (node) => !!node &&
+        sourceRef !== "—" &&
+        (s(node.identifier) === sourceRef || s(node.id) === sourceRef);
+    const issue = asObj(rel.issue);
+    const related = asObj(rel.relatedIssue);
+    // Source on the relatedIssue side ⇒ this is the inverse direction.
+    const sourceIsRelated = matchesSource(related) && !matchesSource(issue);
+    const peer = sourceIsRelated ? issue : related;
+    const rawType = s(rel.type);
+    const type = sourceIsRelated && rawType === "blocks" ? "blockedBy" : rawType;
+    return { type, peer };
+}
+/**
+ * Table render for an `issues relate` result — the `{ data: IssueRelation[] }`
+ * envelope where each entry is `{ type, issue, relatedIssue }`. Rendered
+ * **source-oriented** (`TYPE  TARGET  TITLE`) to match the `--quiet` line: the
+ * type is normalized from the source's perspective (a `--blocked-by` reads as
+ * `blockedBy`) and TARGET is the peer (non-source) issue. `sourceRef` comes
+ * from the envelope's `meta.source` via `dispatch`; absent it (a bare array),
+ * the row falls back to the stored direction.
+ */
+export function formatRelationList(relations, sourceRef = "—") {
+    const rows = relations.map((raw) => {
+        const { type, peer } = relationFromSource(asObj(raw) ?? {}, sourceRef);
+        return {
+            type,
+            target: s(peer?.identifier ?? peer?.id),
+            title: s(peer?.title),
+        };
+    });
+    return renderTable(rows, [
+        { header: "TYPE", minWidth: 4, extract: (r) => r.type },
+        { header: "TARGET", minWidth: 6, extract: (r) => r.target },
+        {
+            header: "TITLE",
+            minWidth: 5,
+            maxWidth: TITLE_TRUNC,
+            extract: (r) => r.title,
+        },
+    ], { emptyText: "(no relations)", itemNoun: "relation" });
+}
 // ── users ──────────────────────────────────────────────────────
 export function formatUserSummary(user) {
     const name = s(user.name);
@@ -968,6 +1026,10 @@ function inferListKind(items) {
         return "empty-list";
     }
     const sample = asObj(items[0]) ?? {};
+    // IssueRelation rows ({ type, issue, relatedIssue }) carry no top-level
+    // identifier/title, so this must precede the issue-list check below.
+    if ("relatedIssue" in sample && "issue" in sample && "type" in sample)
+        return "relation-list";
     if ("identifier" in sample && "title" in sample) {
         // could be issue or search result
         if ("type" in sample && !("templateData" in sample)) {
@@ -1088,6 +1150,8 @@ export function dispatch(kind, payload, fields) {
             return formatReleaseList(list ?? []);
         case "search-result-list":
             return formatSearchResultList(list ?? []);
+        case "relation-list":
+            return formatRelationList(list ?? [], s(asObj(obj?.meta)?.source));
         case "empty-list":
             return "(no results)";
         case "generic":
@@ -1122,5 +1186,44 @@ export function formatLine(payload) {
     if (kind === "comment" && obj) {
         return `comment ${s(obj.id)}`;
     }
+    if (kind === "relation-list") {
+        return formatRelationLine(payload);
+    }
     return JSON.stringify(payload);
 }
+/**
+ * `--quiet` render for an `issues relate` result: one source-oriented line
+ * grouping the created relations by type from the source issue's perspective.
+ *
+ *   EMW-331  related EMW-339,EMW-340  (2)
+ *   EMW-331  blockedBy EMW-400; related EMW-339  (2)
+ *
+ * The per-row reframing (peer + type inversion for reverse `--blocked-by`)
+ * is shared with the summary table via `relationFromSource`; see its doc for
+ * the direction and source-matching rules.
+ */
+function formatRelationLine(payload) {
+    const obj = asObj(payload);
+    const relations = Array.isArray(payload)
+        ? payload
+        : Array.isArray(obj?.data)
+            ? obj.data
+            : [];
+    const sourceRef = s(asObj(obj?.meta)?.source);
+    // Preserve first-seen type order for a stable line.
+    const byType = new Map();
+    for (const raw of relations) {
+        const rel = asObj(raw);
+        if (!rel)
+            continue;
+        const { type, peer } = relationFromSource(rel, sourceRef);
+        const targetId = s(peer?.identifier ?? peer?.id);
+        const bucket = byType.get(type);
+        if (bucket)
+            bucket.push(targetId);
+        else
+            byType.set(type, [targetId]);
+    }
+    const segments = [...byType.entries()].map(([type, ids]) => `${type} ${ids.join(",")}`);
+    return `${sourceRef}  ${segments.join("; ")}  (${relations.length})`;
+}

package/dist/utils/mention-resolver.d.ts

@@ -12,6 +12,27 @@ export interface ResolveMentionsOptions {
      */
     selfUserId?: string;
 }
+interface ResolvedMention {
+    label: string;
+    userId: string;
+}
+export interface MentionReport {
+    /**
+     * ProseMirror doc carrying `suggestion_userMentions` nodes — the structured
+     * body that makes Linear fire real notifications. `null` when nothing
+     * resolved (the caller should send the plain markdown `body` instead).
+     */
+    bodyData: ProseMirrorNode | null;
+    /** Mentions that resolved to a real user (explicit `@name` + bare names). */
+    resolved: ResolvedMention[];
+    /**
+     * Explicit `@name` tokens that did NOT resolve to any team member — almost
+     * always a typo or an unknown handle. Left as plain text (no notification),
+     * so the caller surfaces them as a warning. Bare-name non-matches are not
+     * tracked here: they were never an intended ping.
+     */
+    unresolvedExplicit: string[];
+}
 /**
  * Resolve mentions in markdown body text to Linear user IDs.
  *
@@ -23,9 +44,9 @@ export interface ResolveMentionsOptions {
  * are also converted to mentions — without requiring the `@` prefix. This
  * catches cases like "Bob owns the design" → "@bob owns the design".
  *
- * Returns a ProseMirror `bodyData` doc with `suggestion_userMentions` nodes,
- * or `null` if nothing was resolved.
+ * Returns a {@link MentionReport} describing which names resolved, which
+ * explicit `@names` did not, and the `bodyData` doc to send — or `null` when
+ * there was nothing to resolve and nothing to warn about.
  */
-export declare function resolveMentions(body: string, linearService: LinearService, options?: ResolveMentionsOptions): Promise<{
-    bodyData: ProseMirrorNode;
-} | null>;
+export declare function resolveMentions(body: string, linearService: LinearService, options?: ResolveMentionsOptions): Promise<MentionReport | null>;
+export {};

package/dist/utils/mention-resolver.js

@@ -5,7 +5,8 @@ import { isUuid } from "./uuid.js";
 // Unicode-aware mention regex: ASCII-only `\w` would silently fail to
 // match Cyrillic / accented Latin / CJK names (`@Юрий`, `@Niño`).
 // `\p{L}` covers all Unicode letters; `\p{N}` covers all numerics.
-const EXPLICIT_MENTION_REGEX = /@([\p{L}\p{N}_]+)/gu;
+const MENTION_NAME_CHARS = "\\p{L}\\p{N}_";
+const EXPLICIT_MENTION_REGEX = new RegExp(`(?<![${MENTION_NAME_CHARS}])@([${MENTION_NAME_CHARS}]+)(?![${MENTION_NAME_CHARS}/])`, "gu");
 const WHITESPACE_SPLIT_REGEX = /\s+/;
 const FENCED_CODE_REGEX = /```[\s\S]*?```/g;
 const INLINE_CODE_REGEX = /`[^`]+`/g;
@@ -21,20 +22,27 @@ const MARKDOWN_LINK_REGEX = /\[([^\]]+)\]\(([^)]+)\)/g;
  * are also converted to mentions — without requiring the `@` prefix. This
  * catches cases like "Bob owns the design" → "@bob owns the design".
  *
- * Returns a ProseMirror `bodyData` doc with `suggestion_userMentions` nodes,
- * or `null` if nothing was resolved.
+ * Returns a {@link MentionReport} describing which names resolved, which
+ * explicit `@names` did not, and the `bodyData` doc to send — or `null` when
+ * there was nothing to resolve and nothing to warn about.
  */
 export async function resolveMentions(body, linearService, options = {}) {
     const autoMention = options.autoMention !== false;
     const selfUserId = options.selfUserId;
     // 1. Resolve explicit @name mentions (existing behavior).
     const explicit = new Map();
+    const unresolvedExplicit = [];
     const explicitNames = [...body.matchAll(EXPLICIT_MENTION_REGEX)].map((m) => m[1]);
     for (const name of new Set(explicitNames)) {
         const userId = await resolveUserByName(name, linearService);
         if (userId) {
             explicit.set(name, { userId, label: name });
         }
+        else {
+            // An explicit `@name` the author clearly meant as a ping, but it
+            // matched no team member — surface it so the ping never dies silently.
+            unresolvedExplicit.push(name);
+        }
     }
     // 2. Bare-name mentions: scan for candidate names that actually appear as
     //    standalone words in the body (outside code / link contexts).
@@ -61,12 +69,33 @@ export async function resolveMentions(body, linearService, options = {}) {
             bare.set(candidate, { userId, label: candidate });
         }
     }
-    if (explicit.size === 0 && bare.size === 0) {
+    // Nothing resolved and no failed explicit ping → caller has nothing to do.
+    if (explicit.size === 0 &&
+        bare.size === 0 &&
+        unresolvedExplicit.length === 0) {
         return null;
     }
-    const doc = markdownToProseMirror(body);
-    const bodyData = injectMentions(doc, explicit, bare);
-    return { bodyData };
+    // De-dup by userId for the reported set: a capitalized explicit `@Bob` also
+    // matches the bare candidate "Bob" (the `@` isn't a word char, so the bare
+    // lookbehind passes), landing the same user in both maps. The injected
+    // bodyData is unaffected (the `@name` alternation consumes the span first,
+    // so only one mention node is emitted), but `resolved` would over-count and
+    // `--quiet` would print the user twice — which undercuts the whole point of
+    // a trustworthy mention report. Explicit-first so the label is the typed
+    // `@name`, not the capitalized bare candidate.
+    const resolvedByUser = new Map();
+    for (const m of [...explicit.values(), ...bare.values()]) {
+        if (!resolvedByUser.has(m.userId)) {
+            resolvedByUser.set(m.userId, m);
+        }
+    }
+    const resolved = [...resolvedByUser.values()];
+    // Only build the structured doc when something actually resolved; a body
+    // whose only mention was an unresolved `@typo` is sent as plain markdown.
+    const bodyData = explicit.size > 0 || bare.size > 0
+        ? injectMentions(markdownToProseMirror(body), explicit, bare)
+        : null;
+    return { bodyData, resolved, unresolvedExplicit };
 }
 async function resolveUserByName(name, linearService) {
     const configResult = resolveMember(name);
@@ -225,7 +254,7 @@ function buildCombinedRegex(explicit, bare) {
         // Same Unicode-aware character class as EXPLICIT_MENTION_REGEX
         // at module top so the splitter and the resolver agree on
         // what counts as a name char.
-        parts.push("@[\\p{L}\\p{N}_]+");
+        parts.push(`(?<![${MENTION_NAME_CHARS}])@[${MENTION_NAME_CHARS}]+(?![${MENTION_NAME_CHARS}/])`);
     }
     if (bare.size > 0) {
         const alternation = [...bare.keys()]

package/dist/utils/output.d.ts

@@ -6,6 +6,12 @@ export declare function setRawMode(enabled: boolean): void;
  * the summary block. Set in main.ts's preAction when the flag is present.
  */
 export declare function setQuietMode(enabled: boolean): void;
+/**
+ * Whether `--quiet` is active. Lets a command decide to route extra
+ * human-facing detail (e.g. a mention-resolution confirmation) to stderr,
+ * keeping the single machine-stable stdout line intact.
+ */
+export declare function getQuietMode(): boolean;
 export declare function setJqFilter(filter: string | null): void;
 export declare function setFieldsFilter(fields: string[] | null): void;
 export declare function setOutputFormat(format: OutputFormat): void;

package/dist/utils/output.js

@@ -19,6 +19,14 @@ export function setRawMode(enabled) {
 export function setQuietMode(enabled) {
     quietMode = enabled;
 }
+/**
+ * Whether `--quiet` is active. Lets a command decide to route extra
+ * human-facing detail (e.g. a mention-resolution confirmation) to stderr,
+ * keeping the single machine-stable stdout line intact.
+ */
+export function getQuietMode() {
+    return quietMode;
+}
 export function setJqFilter(filter) {
     jqFilter = filter;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enrichlayer/el-linear",
-  "version": "1.29.1",
+  "version": "1.32.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",
@@ -53,7 +53,7 @@
   "dependencies": {
     "@inquirer/prompts": "^8.4.2",
     "@linear/sdk": "^86.0.0",
-    "commander": "^14.0.0",
+    "commander": "^15.0.0",
     "picocolors": "^1.1.1"
   },
   "devDependencies": {