@enrichlayer/el-linear 1.37.2 → 1.38.0

package/README.md

@@ -277,8 +277,9 @@ el-linear can record each gate's fire/override decision to a local JSONL file so
 you can measure its **override-rate** and tell whether it's too aggressive. It is
 **off by default** and writes nothing unless you opt in (e.g.
 `export EL_TELEMETRY_DIR=<path>`); there is no server or database, and
-`EL_TELEMETRY_DISABLED=1` forces it off. Full opt-in rules, the event schema, and
-a `jq` reader are in [docs/telemetry.md](./docs/telemetry.md).
+`EL_TELEMETRY_DISABLED=1` forces it off. The active ledger rotates to one `.old`
+backup before append when it exceeds 2 MiB. Full opt-in rules, the event schema,
+and a `jq` reader are in [docs/telemetry.md](./docs/telemetry.md).
 
 ### Networking (IPv4 preference)
 

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

@@ -237,6 +237,16 @@ 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
    ```
 
+### Cross-linking: be generous, link proactively, don't wait ([DEV-5853](https://linear.app/verticalint/issue/DEV-5853/))
+
+**The default is to link, not to ask.** A cross-link is cheap and reversible; a *missing* link is invisible and costs reviewers and SOP tooling the context they need. When you identify an issue that is **related** / a **blocker** / a **follow-up** / the **origin** of the work in front of you, create the relation yourself — don't stage the candidates and wait for the human to name them, and don't hedge with "tell me if you want these linked."
+
+- **At create time**, pass `--related-to "<ids>"` / `--parent <id>` / `--blocked-by <id>` directly on `issues create` — this path typically passes the classifier, so link generously the moment you file.
+- **After the fact**, call `el-linear issues relate <source> --related-to "<ids>"` (or `--blocked-by` / `--blocks` / `--duplicate-of`) proactively, the same way.
+- Over-linking is self-correcting (a wrong relation is one command to remove); under-linking is not. When in doubt, link.
+
+The one exception is below: if the auto-mode permission classifier actually blocks a specific post-hoc `relate` call, that block — not caution — is your signal to surface the candidates for a one-word confirm.
+
 ### 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**.
@@ -248,38 +258,29 @@ Skipping it cost real rework across sessions: a hook guard and `--jq`/`--fields`
 
 When `el-linear issues search` (or the cross-resource `search`) returns rows
 carrying issue identifiers, the JSON envelope embeds a `_warnings` line
-starting with `relation_candidates:` that enumerates the candidate IDs and
-asks the user to reply with which ones to link, and states the skip phrase.
-
-That warning is the authoritative instruction — surface it to the user
-verbatim and follow it literally: **do not call `el-linear issues relate`
-until the user replies naming the IDs to link.** Only user-named IDs go into
-the `issues relate <source> --related-to "<ids>"` call — never pass an ID the
-user did not name, even one your own search obviously surfaced. The CLI emits
-the full procedure (every candidate ID, the example reply, the skip phrase) in
-that one line, so follow it rather than re-deriving or paraphrasing it away.
-
-Why this matters: Claude Code's auto-mode permission classifier blocks
-`issues relate --related-to "<ids>"` when the IDs were *agent-inferred*
-(came from your own search) rather than *user-specified* (typed by the human),
-because each listed peer is a write target. Routing the IDs through an
-explicit human reply converts them from agent-inferred → user-specified;
-the existing search step (above) stays intact; auto-mode's guard is not
-weakened. The fix is the loop shape, not the guard.
-
-Anti-patterns:
-
-- **Calling `issues relate` directly off your own search output** — even if
-  the IDs are real and the candidates look obvious, this is the exact path
-  the auto-mode guard refuses.
-- **Splitting one relate call into N single-ID calls** to "look smaller" —
-  same provenance problem, same block, just multiplied.
-- **Asking the user a yes/no question** ("Should I link these?") instead of
-  having them name the IDs — yes answers stay agent-inferred, the reply
-  must carry the IDs to convert them to user-specified.
+starting with `relation_candidates:` enumerating the candidate IDs. Treat it
+as a **convenience list of link candidates, not a stop sign** — under the
+proactive default above, relate the ones that are genuinely related/blocking
+without waiting to be told. Prefer create-time `--related-to` when the search
+ran as part of filing a new issue (create-time relations typically pass the
+classifier); otherwise call `issues relate` directly.
+
+**Residual auto-mode constraint (the only reason to pause).** Claude Code's
+auto-mode permission classifier *may* block a standalone `issues relate
+--related-to "<ids>"` when it judges the IDs *agent-inferred* (surfaced by
+your own search) rather than *user-specified*, because each peer is a write
+target. A standing user instruction to cross-link generously is itself
+authorization — so proceed by default. But if a specific `relate` call is
+**actually blocked** by the classifier, that block is your cue: surface the
+candidate IDs to the user for a one-word confirm, then re-run with the
+user-named IDs (which pass). This is the **exception path**, not the default —
+do not pre-emptively withhold links the classifier would have allowed. Two
+ways to keep it frictionless: file relations at create time (`--related-to`),
+or the operator adds a permission rule / runs non-auto-mode so post-hoc
+`relate` never trips.
 
 If `--include-closed` search returns no matches, no `relation_candidates:`
-warning is emitted (nothing to confirm) and the flow proceeds normally.
+warning is emitted and the flow proceeds normally.
 
 ### Viewing existing relations
 

package/dist/commands/comments.js

@@ -4,6 +4,7 @@ import { CREATE_COMMENT_MUTATION, DELETE_COMMENT_MUTATION, GET_COMMENT_QUERY, LI
 import { autoLinkReferences, } from "../utils/auto-link-references.js";
 import { applyFooter } from "../utils/footer.js";
 import { createGraphQLService, } from "../utils/graphql-service.js";
+import { normalizeInlineTextInput } from "../utils/inline-text-input.js";
 import { extractIssueReferences } from "../utils/issue-reference-extractor.js";
 import { wrapIssueReferencesAsLinks } from "../utils/issue-reference-wrapper.js";
 import { createLinearService, } from "../utils/linear-service.js";
@@ -79,7 +80,7 @@ function readBody(options) {
         return readFileSync(options.bodyFile, "utf-8");
     }
     if (options.body) {
-        return options.body;
+        return normalizeInlineTextInput(options.body);
     }
     throw new Error("Either --body or --body-file is required");
 }

package/dist/commands/issues/description.js

@@ -20,6 +20,7 @@ import fs from "node:fs";
 import { loadConfig } from "../../config/config.js";
 import { UPDATE_ISSUE_MUTATION } from "../../queries/issues.js";
 import { autoLinkReferences, } from "../../utils/auto-link-references.js";
+import { normalizeInlineTextInput } from "../../utils/inline-text-input.js";
 import { extractIssueReferences } from "../../utils/issue-reference-extractor.js";
 import { wrapIssueReferencesAsLinks } from "../../utils/issue-reference-wrapper.js";
 import { validateReferences } from "../../utils/validate-references.js";
@@ -59,7 +60,7 @@ export function resolveDescription(options) {
         return readDescriptionFile(options.descriptionFile);
     }
     if (hasInline) {
-        return options.description;
+        return normalizeInlineTextInput(options.description);
     }
     if (hasTemplate) {
         const templates = loadConfig().descriptionTemplates ?? {};

package/dist/commands/issues.js

@@ -13,6 +13,7 @@ import { applyFooter } from "../utils/footer.js";
 import { emitGateEvent } from "../utils/gate-telemetry.js";
 import { createGraphQLAttachmentsService } from "../utils/graphql-attachments-service.js";
 import { createGraphQLService, } from "../utils/graphql-service.js";
+import { normalizeInlineTextInput } from "../utils/inline-text-input.js";
 import { createIssuesService } from "../utils/issues-service-bootstrap.js";
 import { createLinearService, } from "../utils/linear-service.js";
 import { logger } from "../utils/logger.js";
@@ -205,7 +206,8 @@ async function handleListIssues(options, command) {
     // user passes --include-closed OR explicit --status. Explicit status
     // wins because the user already named the workflow states they want.
     const excludeTerminalStates = !options.includeClosed && explicitStatus === undefined;
-    const hasOtherFilters = options.team ||
+    const hasOtherFilters = options.search ||
+        options.team ||
         options.labels ||
         options.status ||
         options.assignee ||
@@ -223,6 +225,7 @@ async function handleListIssues(options, command) {
     // (DEV-4478 cycle-1.)
     if (hasOtherFilters || excludeTerminalStates || options.includeClosed) {
         const searchArgs = {
+            query: options.search,
             teamId: options.team ? resolveTeam(options.team) : undefined,
             assigneeId: options.assignee
                 ? await resolveAssignee(options.assignee, rootOpts)
@@ -244,8 +247,15 @@ async function handleListIssues(options, command) {
         if (excludeTerminalStates) {
             outputWarning("excluded terminal states (Done / Canceled) by default; pass --include-closed to include them");
         }
+        if (options.search) {
+            const relationPrompt = buildRelationCandidatePrompt(result);
+            if (relationPrompt) {
+                outputWarning(relationPrompt);
+            }
+        }
         warnIfTruncated(result.length, limit);
         outputIssues(result, command, {
+            query: options.search,
             team: options.team,
         });
     }
@@ -947,6 +957,12 @@ async function handleUpdateIssue(issueId, options, command) {
     if (options.descriptionFile) {
         options.description = readDescriptionFile(options.descriptionFile);
     }
+    else if (typeof options.description === "string") {
+        options.description = normalizeInlineTextInput(options.description);
+    }
+    if (typeof options.appendDescription === "string") {
+        options.appendDescription = normalizeInlineTextInput(options.appendDescription);
+    }
     validateUpdateOptions(options);
     const rootOpts = getRootOpts(command);
     const { graphQLService, linearService, issuesService } = await createIssuesService(rootOpts);
@@ -1228,6 +1244,7 @@ export function setupIssuesCommands(program) {
         .command("list")
         .description("List issues.")
         .option("-l, --limit <number>", "limit results", "25")
+        .option("--search <query>", "full-text search term; composes with list filters")
         .option("--team <team>", "filter by team key (EL: resolves names)")
         .option("--assignee <assignee>", "filter by assignee (name, alias, or ID)")
         .option("--delegate <delegate>", "filter by delegated agent (name, alias, or ID)")

package/dist/commands/labels.js

@@ -9,8 +9,9 @@ import { getRootOpts } from "../utils/root-opts.js";
 import { parsePositiveInt, validateHexColor } from "../utils/validators.js";
 async function handleCreateLabel(name, options, command) {
     const rootOpts = getRootOpts(command);
-    const teamId = resolveTeam(options.team);
     const graphQLService = await createGraphQLService(rootOpts);
+    const linearService = await createLinearService(rootOpts);
+    const teamId = await linearService.resolveTeamId(resolveTeam(options.team));
     const input = { name, teamId };
     if (options.color) {
         input.color = validateHexColor(options.color);

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/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/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

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/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.
  */

package/dist/utils/relation-candidate-prompt.js

@@ -59,16 +59,23 @@ export function extractCandidateIdentifiers(rows) {
     return out;
 }
 /**
- * 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.
  */
@@ -82,13 +89,20 @@ export function buildRelationCandidatePrompt(rows) {
         ? `${shown.join(", ")}, … (+${overflow} more)`
         : shown.join(", ");
     // Build two concrete example IDs from the head of the list so the
-    // "reply with the IDs you want linked" example is realistic for the
-    // caller's actual search rather than a fixed placeholder. Single-result
+    // fallback "reply with the IDs you want linked" example is realistic for
+    // the caller's actual search rather than a fixed placeholder. Single-result
     // case still reads naturally ("link DEV-1").
     const example = shown.length >= 2 ? `link ${shown[0]} and ${shown[1]}` : `link ${shown[0]}`;
     const noun = ids.length === 1 ? "candidate related issue" : "candidate related issues";
+    // DEV-5853: proactive framing first (relate the relevant ones directly),
+    // then the reply-flow fallback for when auto-mode blocks an agent-inferred
+    // relate. The `relate the relevant ones` / `reply with the IDs you want
+    // linked` / `"no links"` / DEV-4494 tokens are all preserved so downstream
+    // skill/agent matchers stay stable.
     return (`relation_candidates: Found ${ids.length} ${noun} (${idList}). ` +
-        `To link them as related: reply with the IDs you want linked ` +
-        `(e.g. "${example}"). 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. "${example}"), or "no links" to skip. ` +
         `(Agent-inferred IDs are blocked by auto-mode; user-named IDs pass — DEV-4494.)`);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enrichlayer/el-linear",
-  "version": "1.37.2",
+  "version": "1.38.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",
@@ -68,8 +68,9 @@
     "@sentry/node": "^10.50.0"
   },
   "scripts": {
-    "build": "tsc && chmod +x dist/main.js",
+    "build": "tsc -p tsconfig.build.json && chmod +x dist/main.js",
     "clean": "rm -rf dist/",
+    "typecheck": "tsc --noEmit",
     "lint": "biome check .",
     "lint:fix": "biome check --fix .",
     "start": "tsx src/main.ts",